feat: declare ingested content as internally authored (DeclaresProvenance) - #2
Conversation
Adopts DeclaresProvenance from connector-base v1.5.0, labelling everything this connector ingests ProvenanceTier::TrustedInternal. The connector reads a Jira site the organisation administers — a system whose write access the organisation grants. Whoever authored a document had to be given the ability to author it, and that property is exactly what the tier records. It is the counterpart to the IMAP connector, whose mailbox accepts a message from anyone who knows the address; until now both were ingested as the same kind of fact, so no deployment could say how much of its corpus was written by outsiders. "Trusted" is a statement about authorship, not about correctness or curation. An internal page can be wrong, stale or unreviewed — that is the Auto-Wiki curation tier's question, and deliberately a different one. The tier is a label; nothing enforces on it yet. Requires connector-base ^1.5 for the capability interface. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QPJodaHYMJ3wppek7aYTBX
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7c911ebdd8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| */ | ||
| public function provenanceTier(int $installationId): ProvenanceTier | ||
| { | ||
| return ProvenanceTier::TrustedInternal; |
There was a problem hiding this comment.
For Jira Service Management installations where portal customers create issues or comments—or projects permit anonymous/external contributors—this unconditional tier labels their content TrustedInternal. The connector synchronizes every accessible project and includes issue descriptions and all returned comments without checking their authors, so the provenance report cannot reliably distinguish externally authored material and any downstream trust policy will treat it as internal; use a conservative tier for mixed installations or derive provenance from the actual authors/access model.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR adopts the DeclaresProvenance contract from askmydocs-connector-base and declares Jira-ingested content as ProvenanceTier::TrustedInternal, enabling downstream provenance labeling (Phase 1 of ADR 0028) without enforcement changes yet.
Changes:
- Implement
DeclaresProvenanceonJiraConnectorand returnProvenanceTier::TrustedInternalfromprovenanceTier(). - Bump
padosoft/askmydocs-connector-basedependency constraint to^1.5. - Add unit tests and README documentation describing the connector’s provenance stance.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
src/JiraConnector.php |
Implements provenance declaration via DeclaresProvenance and returns TrustedInternal. |
tests/Unit/ProvenanceDeclarationTest.php |
Adds coverage asserting the connector declares provenance and returns a stable tier. |
README.md |
Documents the new provenance declaration behavior. |
composer.json |
Updates dependency constraint to padosoft/askmydocs-connector-base: ^1.5. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| final class ProvenanceDeclarationTest extends TestCase |
| - 🏢 **Per-tenant isolated** — every credential read and ingestion dispatch is scoped to the active `TenantContext`. | ||
| - 🧪 **Test-friendly** — pure-PHP unit tests for the ADF converter + JQL builder, `Http::fake()` feature tests for the connector, opt-in live test against a real Atlassian sandbox cloud when `CONNECTOR_JIRA_LIVE=1`. | ||
|
|
||
| - **Provenance declaration** — implements `DeclaresProvenance` (connector-base ^1.5), labelling ingested content `TrustedInternal`: a Jira site the organisation administers, so whoever wrote a document had to be granted the ability to write it. A statement about *authorship*, not about correctness — see the IMAP connector for the contrasting case. |
| "illuminate/http": "^12.0|^13.0", | ||
| "illuminate/contracts": "^12.0|^13.0", | ||
| "padosoft/askmydocs-connector-base": "^1.3" | ||
| "padosoft/askmydocs-connector-base": "^1.5" |
Pint's ordered_imports fixer flagged the two `use` lines added with the provenance declaration: they were written with LF into a file the checkout keeps as CRLF, so the run reported them as mis-ordered. No code change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QPJodaHYMJ3wppek7aYTBX
Adopts
DeclaresProvenancefrom connector-base v1.5.0. Phase 1 of AskMyDocs ADR 0028.Why
Ingestion records what a document is and nothing about who wrote it. That is invisible until you line up what connectors actually do: this one reads a Jira site the organisation administers — a system whose write access the organisation grants, so whoever authored a document had to be given the ability to author it. The IMAP connector's mailbox accepts a message from anyone who knows the address.
Both became documents, then chunks, then retrieval grounding on a platform that also exposes tools an agent can call — stored as the same kind of fact, with nothing marking the difference. No deployment could answer "how much of our corpus is externally authored?".
Change
Plus the
^1.5constraint bump, a README bullet, and three tests."Trusted" means authored internally, not correct
Worth being explicit, because the word invites the wrong reading. An internal Jira page can be wrong, stale, or never reviewed by anyone. Whether a human vouched for a document is the Auto-Wiki curation tier's question — a separate axis that already exists. Provenance records authorship origin. A human-accepted page summarising an external email is high-curation and externally authored at once, and collapsing the two would lose the half that matters for trust decisions.
Enforcement
None yet, by design. The tier is a label: enforcement is only testable against a corpus that is already labelled, which is why ADR 0028 ships labelling first.