@r3dlex/ai-catapult 0.1.0

package/dist/codex-plugin/skills/ai-catapult-init/modules/skill-modernization.md

@@ -0,0 +1,72 @@
+# Skill Modernization Module
+
+Read when auditing or updating a skill catalog for compact metadata, progressive disclosure, trigger clarity, runnable validation, cross-skill workflow links, and AI-SDLC compatibility.
+
+## Generated outputs
+
+| Output | Purpose |
+| --- | --- |
+| `.ai/skills/catalog-audit.json` | Machine-readable audit of every first-class skill description, body length, trigger boundary, and compatibility status. |
+| `.ai/skills/description-exceptions.json` | Explicit exceptions for descriptions that exceed the hard budget; default is no exceptions. |
+| `.ai/skills/modernization-report.md` | Human report summarizing fixes, warnings, and remaining follow-up. |
+
+## Budget policy
+
+- Target description length: `<= 180` characters.
+- Hard-fail description length: `> 280` characters unless listed in `.ai/skills/description-exceptions.json` with owner, reason, and expiry.
+- `SKILL.md` body stays under 100 lines.
+- Descriptions state capability plus concrete trigger conditions; move examples, background, and variants to modules or references.
+
+## Required checks
+
+1. Audit only first-class catalog skill directories plus the `ai-sdlc-init` compatibility shim; exclude `.agents/`, hidden/runtime directories, reference fixtures, and golden outputs.
+2. Verify every first-class skill has `name` and `description` frontmatter.
+3. Warn when a description exceeds the 180-character target; fail when it exceeds 280 without an audited exception.
+4. Verify body line limits and progressive-disclosure anti-patterns through `tests/test-skills.sh`.
+5. Verify trigger/non-trigger/fallback boundaries are present in each first-class description (see "Trigger boundaries").
+6. Validate referenced surfaces: no broken relative links, aliases resolve to a real canonical skill, every referenced file exists, and every bundled script passes `bash -n` (see "Link, alias, referenced-file, and script validation").
+7. Verify generated workflow links remain discoverable for skills that create PRDs, issues, releases, traces, or AI-SDLC artifacts.
+8. Emit a stable catalog audit artifact and keep exceptions explicit, reviewed, and time-bounded.
+
+## Trigger boundaries
+
+Every audited skill description must make three boundaries explicit so an agent can route correctly without loading the body:
+
+- **Trigger** — the concrete conditions under which the skill should run (verbs, artifacts, keywords).
+- **Non-trigger** — adjacent situations the skill must *not* claim, to prevent over-eager invocation (e.g. "use X instead for live-app runs"). Audit warns when a skill's description overlaps another skill's trigger without a non-trigger carve-out.
+- **Fallback** — what happens when a precondition is missing or an optional tool/host is unavailable (graceful degradation, plain-markdown path, or "defer to <other skill>"). A skill with optional host/tool dependencies must name its fallback.
+
+## Link, alias, referenced-file, and script validation
+
+The audit statically validates a skill's referenced surfaces — offline, no network:
+
+- **Broken link check** — every relative Markdown link and `modules/*`/`reference/*` pointer in `SKILL.md` and its modules resolves to a tracked file.
+- **Alias check** — declared aliases/shims (e.g. the `ai-sdlc-init` → `ai-catapult-init` and `init-ai-repo` → `ai-catapult-init` compatibility aliases) point to a real canonical skill and do not collide with another first-class name.
+- **Referenced-file check** — every file a skill names (templates, fixtures, ADRs, golden outputs) exists at the cited path; cite by content where line numbers would drift.
+- **Script check** — every bundled `scripts/*` a skill invokes exists and passes `bash -n`; the audit does not execute network- or credential-dependent scripts.
+
+## Cross-skill workflow links
+
+- `ai-catapult-init` owns generated workflow, traceability, cascade, and catalog audit artifacts.
+- `setup-skills` owns tracker/domain-doc configuration that downstream issue and PRD skills consume.
+- `to-prd`, `to-issues`, and `triage` must preserve traceability IDs and tracker backlinks.
+- `publish-semver` must link release evidence to specs, PRs, and tests.
+- `write-a-skill` and `write-agent-docs` own authoring guidance for future catalog changes.
+
+## Codex parity verification (P2)
+
+The mechanical Codex-parity bar (no Claude/OMC-only hard dependencies) is
+enforced offline by `scripts/check-codex-parity.sh`. The **verified** bar — a
+human actually running representative skills under Codex — is recorded
+out-of-band, never in CI. Follow `docs/learning/codex-verification.md` to run a
+skill under Codex via `scripts/install-codex.sh`, what to record, and the pass
+criteria; recorded transcript evidence lives under
+`reference/fixtures/v3/standalone/.ai/evals/codex-verification/` and carries the
+"recorded out-of-band verification, not a CI gate" disclaimer (validation check
+#20, ADR-0004).
+
+## Safety rules
+
+- Do not weaken validators to make existing skills pass; fix the skill or add a reviewed exception.
+- Do not add new runtime dependencies for catalog validation.
+- Do not rewrite skill workflows for style only; preserve behavior unless a validation gate proves a problem.

package/dist/codex-plugin/skills/ai-catapult-init/modules/sync.md

@@ -0,0 +1,111 @@
+# Sync Module
+
+Read when propagating inherited assets from an umbrella repo to its managed sub-repos, when generating drift reports, or when backing up the v3 scaffold. Physical-copy is the canonical sync strategy. Symlinks and git submodules are explicitly rejected as canonical.
+
+## Sync strategy
+
+`sync_strategy: physical-copy` is the only canonical value in `.ai/matrix.json`. The sync lifecycle is:
+
+1. **Resolve** — read `.ai/matrix.json` and compute the set of inherited assets and the set of managed repos.
+2. **Backup** — write a snapshot of every destination file that will be overwritten under `.ai/drift/backups/<timestamp>/`. Skip files that are unchanged.
+3. **Copy** — overwrite the destination with the source file. Use ordinary file copies, not symlinks and not git submodule references.
+4. **Verify** — compute a SHA-256 of source and destination and assert equality. On mismatch, mark the asset as `failed` in the drift report and roll back from the backup.
+5. **Audit** — append a sync record to `.ai/drift/last-sync.json` with timestamp, per-asset status, and SHA-256 values.
+6. **Drift report** — write `.ai/drift/last-drift.json` listing per-asset `unchanged`, `updated`, `added`, or `failed` status.
+
+## What sync is allowed to write
+
+Sync is allowed to write only paths that appear in `.ai/matrix.json#inherited_assets`. Any other write is rejected. In particular:
+
+- `.memory/human-override/` is never in the inherited-assets list and never written by sync.
+- `.memory/self-learned/` is per-repo only and never written by sync.
+- The umbrella root's own `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and `README.md` are not written by sync unless they are explicitly listed in `inherited_assets`.
+
+## Depth rule
+
+Sync is allowed to run only when `current_depth <= max_allowed_depth`. For `umbrella` topologies, `max_allowed_depth` is fixed at `3`. The validator must:
+
+1. Walk the tree rooted at the umbrella repo and compute the maximum path depth of any managed repo.
+2. Treat any path whose depth exceeds 3 as a violation.
+3. Refuse to run the sync when the violation persists.
+
+## Drift detection
+
+Drift is detected by comparing the SHA-256 of each source asset against the SHA-256 of the destination asset. Drift is reported per asset:
+
+| Status | Meaning |
+| --- | --- |
+| `unchanged` | Source and destination SHA-256 match. |
+| `updated` | Source and destination SHA-256 differ; destination was overwritten and a backup was written. |
+| `added` | Destination did not exist; new file written. |
+| `failed` | Sync attempted but SHA-256 mismatch persisted, or write was rejected by safety policy. The destination was rolled back from the backup. |
+| `skipped` | Asset was intentionally skipped (e.g., excluded by `.ai/matrix.json#exclusions` or by `.memory/human-override/` membership). |
+
+The drift report is written to `.ai/drift/last-drift.json` and has this shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "2026-06-07T00:00:00Z",
+  "umbrella_root": ".",
+  "managed_repos": 3,
+  "assets": [
+    {
+      "path": "AGENTS.md",
+      "source": ".",
+      "mode": "physical-copy",
+      "status": "unchanged",
+      "source_sha256": "...",
+      "destination_sha256": "..."
+    }
+  ],
+  "summary": {
+    "unchanged": 12,
+    "updated": 1,
+    "added": 0,
+    "failed": 0,
+    "skipped": 2
+  }
+}
+```
+
+## Audit log
+
+Every sync run appends an entry to `.ai/drift/sync-audit.jsonl` with one JSON object per line. Each entry has:
+
+- `ts` — ISO-8601 timestamp.
+- `umbrella_root` — repo path.
+- `actor` — `ai-sdlc-init` or specific agent role.
+- `mode` — `apply` or `dry-run`.
+- `assets_changed` — count of `updated` and `added` assets.
+- `assets_failed` — count of `failed` assets.
+- `confirmation_token` — only present when `mode: apply`; references the explicit user confirmation that authorized the run.
+
+Dry-run is the default. The first `apply` for a given run requires a fresh confirmation token. A confirmation token is valid only for the run that produced it; subsequent retries of the same plan require a fresh confirmation. See `modules/host-policy-automation.md` for the canonical confirmation-token rule.
+
+## Local overrides
+
+A managed sub-repo may declare a local override file at `.ai/local-overrides.json`. The file lists paths that the sub-repo does not want to inherit from the umbrella. Each entry has:
+
+- `path` — the inherited-asset path being overridden.
+- `reason` — short human-readable reason.
+- `expires_at` — optional ISO-8601 timestamp after which the override should be re-evaluated.
+
+Overrides are honored by sync; the asset status becomes `skipped` with reason `local-override`. Override expiry is enforced during drift review: an expired override is reported in the drift report under `expiring_overrides`.
+
+## Safety rules
+
+- Sync never deletes files outside the inherited-assets list.
+- Destructive operations (deleting a destination, removing a backup) require explicit confirmation and emit an audit entry.
+- Backups older than the retention window are pruned only with explicit confirmation. Default retention is 30 days; the value lives in `.ai/matrix.json#sync_status.retention_days` when present.
+- Sync does not call hosted APIs to apply branch or policy changes. Hosted mutations are scoped to `modules/host-policy-automation.md`.
+
+## Failure modes
+
+| Failure | Behavior |
+| --- | --- |
+| `current_depth > max_allowed_depth` | Sync refuses to start. Error names the offending repo path and depth. |
+| Destination write fails | Sync rolls back from the backup, marks the asset `failed`, and continues with the next asset. |
+| Source file missing | Sync marks the asset `failed` and emits a `source-missing` audit entry. |
+| Backups directory unwritable | Sync refuses to start. |
+| `.ai/matrix.json` invalid | Sync refuses to start. The validator reports the schema violation. |

package/dist/codex-plugin/skills/ai-catapult-init/modules/topology.md

@@ -0,0 +1,102 @@
+# Topology Module
+
+Read when the target repo is a standalone repository or an umbrella repository that needs canonical topology, max-depth, and sync metadata. The matrix is generated under `.ai/matrix.json` and is the single source of truth for repo layout, sync strategy, and inherited assets.
+
+## Topology types
+
+| Type | When to use | Required fields in `.ai/matrix.json` |
+| --- | --- | --- |
+| `standalone` | A single repository with one top-level tree, no nested managed repos. | `topology_type`, `max_allowed_depth: 0`, `current_depth: 0`, `sync_strategy: physical-copy`, `upstream_authority`, `inherited_assets`, `sync_status`. |
+| `umbrella` | A repository that owns managed sub-repositories and propagates inherited assets to them. | All standalone fields plus `managed_repositories`, `max_allowed_depth: 3`, and a per-repo `depth` value. |
+
+`max_allowed_depth` is fixed at `3` for `umbrella` topologies. `current_depth` is the maximum path depth observed across managed repositories. When `current_depth > max_allowed_depth`, validation must fail or block the apply path; the error must identify the offending repo path and the offending depth.
+
+## `.ai/matrix.json` schema (v1.0)
+
+```json
+{
+  "schema_version": "1.0",
+  "topology_type": "umbrella",
+  "max_allowed_depth": 3,
+  "current_depth": 2,
+  "sync_strategy": "physical-copy",
+  "upstream_authority": {
+    "type": "git",
+    "url": "https://github.com/example/upstream.git",
+    "ref": "main"
+  },
+  "managed_repositories": [
+    {
+      "path": "services/auth",
+      "depth": 2,
+      "inherits_assets_from": "."
+    }
+  ],
+  "inherited_assets": [
+    {
+      "path": "AGENTS.md",
+      "source": ".",
+      "mode": "physical-copy"
+    },
+    {
+      "path": ".ai/matrix.json",
+      "source": ".",
+      "mode": "physical-copy"
+    }
+  ],
+  "sync_status": {
+    "last_synced_at": "2026-06-07T00:00:00Z",
+    "drift_detected": false,
+    "last_drift_report": ".ai/drift/last-drift.json"
+  }
+}
+```
+
+### Required fields and types
+
+- `schema_version` (string) — fixed at `"1.0"` until v2 is introduced.
+- `topology_type` (string enum) — `standalone` or `umbrella`.
+- `max_allowed_depth` (integer) — `0` for standalone, `3` for umbrella. Other values are rejected.
+- `current_depth` (integer) — `0` for standalone, computed for umbrella.
+- `sync_strategy` (string enum) — `physical-copy` only. `symlink` and `git-submodule` are explicitly rejected as canonical.
+- `upstream_authority` (object) — non-null when sync reads from an upstream source. `type` is `git` or `local`. `url` and `ref` describe the source.
+- `managed_repositories` (array) — required when `topology_type` is `umbrella`. Each entry has `path`, `depth`, and `inherits_assets_from`.
+- `inherited_assets` (array) — list of file or directory paths propagated to managed repos. Each entry has `path`, `source`, and `mode: physical-copy`.
+- `sync_status` (object) — `last_synced_at`, `drift_detected`, and an optional `last_drift_report` path.
+
+### Optional fields
+
+- `migration` (object) — references the legacy-to-v3 migration manifest; see `modules/migration.md` for the migration manifest format.
+- `exclusions` (array of strings) — managed repos or paths that opt out of inheritance. Exclusions must be explicit and listed in the matrix, not inferred from `.gitignore`.
+
+## Umbrella depth rule
+
+`max_allowed_depth: 3` is a hard limit. The validator must:
+
+1. Walk the tree rooted at the umbrella repo and compute the maximum path depth of any managed repo relative to the umbrella root.
+2. Treat any path whose depth exceeds 3 as a violation.
+3. Emit a blocking error that names the offending repo path and its depth.
+4. Refuse to start the sync or apply path while the violation persists.
+
+Depth is the number of path segments from the umbrella root to the managed repo, not the Git history depth.
+
+## Sync-strategy rule
+
+`sync_strategy: physical-copy` is the canonical strategy. Concretely:
+
+- Inherited assets are propagated as ordinary file copies at sync time.
+- The sync path writes a backup under `.ai/drift/backups/<timestamp>/` before overwriting any inherited asset.
+- The sync path emits a drift report that lists per-asset `unchanged`, `updated`, or `added` status.
+- Symlinks and git submodules are not the canonical strategy and must not appear as `mode` values.
+
+See `modules/sync.md` for the full sync lifecycle, drift detection, and audit log format.
+
+## Standalone-only files
+
+A standalone repo does not need `managed_repositories`. A standalone repo must still set `max_allowed_depth: 0`, `current_depth: 0`, and `sync_strategy: physical-copy` so the schema is uniform.
+
+## Safety rules
+
+- Matrix generation never deletes files outside the inherited-assets list.
+- Destructive migration of legacy matrix fields requires explicit confirmation; see `modules/migration.md` for the migration audit manifest format.
+- `.memory/human-override/` is terminal priority and is never listed in `inherited_assets` because it is per-repo, not propagated.

package/dist/codex-plugin/skills/ai-catapult-init/modules/traceability.md

@@ -0,0 +1,136 @@
+# Traceability Graph Module
+
+Read when generating or validating requirement/work-artifact traceability for an `ai-catapult-init` target repository. This module owns stable IDs, node/edge schema, backlink validation, graph fixtures, and cross-skill contracts.
+
+## Generated outputs
+
+| Output | Purpose |
+| --- | --- |
+| `.ai/traceability/graph.json` | Machine-readable node/edge graph for requirements, work items, reviews, tests, and handoffs. |
+| `.ai/traceability/index.md` | Human index of graph nodes, backlinks, and uncovered artifacts. |
+| `.ai/traceability/validation-report.md` | Validation result proving no dangling edges and required artifact coverage. |
+
+Generated workflow and handoff surfaces should link to the traceability index once this phase is active.
+
+## Stable ID policy
+
+- IDs are deterministic strings: `<type>:<repo-id>:<slug>`.
+- `type` is one of `brd`, `prd`, `adr`, `plan`, `issue`, `pr`, `test`, `handoff`, `workflow`, or `validation`. Schema `1.1` additively adds `eval-result` and `trajectory-trace` (see below).
+- `repo-id` comes from `.ai/matrix.json` when present; otherwise use `root` for the local repo fixture.
+- `slug` is lower-kebab-case from the artifact title or host key.
+- IDs never include credentials, access tokens, or mutable host session IDs.
+
+## Graph schema v1.0
+
+```json
+{
+  "schema_version": "1.0",
+  "root_repo_id": "root",
+  "generated_at": "2026-06-27T00:00:00Z",
+  "nodes": [
+    {
+      "id": "prd:root:init-ai-repo-workflow-surfaces",
+      "type": "prd",
+      "title": "init-ai-repo workflow surfaces",
+      "status": "active",
+      "repo_id": "root",
+      "path": "docs/specifications/ACTIVE/init-ai-repo-workflow-surfaces.md",
+      "backlinks": ["plan:root:init-ai-repo-pr-stack"]
+    }
+  ],
+  "edges": [
+    {
+      "source": "plan:root:init-ai-repo-pr-stack",
+      "target": "prd:root:init-ai-repo-workflow-surfaces",
+      "relation": "decomposes-to",
+      "created_by": "init-ai-repo",
+      "evidence_path": ".ai/traceability/index.md"
+    }
+  ]
+}
+```
+
+## Graph schema v1.1 (additive)
+
+Schema `1.1` is a strictly additive bump over `1.0`. No `1.0` field is removed or renamed, so existing `1.0` graphs and fixtures stay valid unchanged.
+
+- `schema_version` is `"1.1"`.
+- The `type` enum gains two node types: `eval-result` (a recorded LM-judge/eval outcome for a skill or PR) and `trajectory-trace` (a recorded agent trajectory captured during an eval run).
+- New relations are permitted for the new types, e.g. `evaluated-by` (work item → `eval-result`) and `traced-by` (`eval-result` → `trajectory-trace`).
+- All other node/edge field rules from `1.0` apply unchanged to the new types: each node still carries `id`, `type`, `title`, `status`, `repo_id`, and either `path` or `host_url`; backlinks and edges must resolve.
+
+```json
+{
+  "schema_version": "1.1",
+  "root_repo_id": "umbrella-root",
+  "nodes": [
+    {
+      "id": "eval-result:umbrella-root:example-output-eval",
+      "type": "eval-result",
+      "title": "example-output-eval LM-judge result",
+      "status": "active",
+      "repo_id": "umbrella-root",
+      "path": ".ai/evals/example-output-eval/evalset.json",
+      "backlinks": ["pr:umbrella-root:workflow-surfaces"]
+    },
+    {
+      "id": "trajectory-trace:umbrella-root:example-output-eval",
+      "type": "trajectory-trace",
+      "title": "example-output-eval trajectory trace",
+      "status": "active",
+      "repo_id": "umbrella-root",
+      "path": ".ai/evals/example-output-eval/rubric.md",
+      "backlinks": ["eval-result:umbrella-root:example-output-eval"]
+    }
+  ],
+  "edges": [
+    {
+      "source": "pr:umbrella-root:workflow-surfaces",
+      "target": "eval-result:umbrella-root:example-output-eval",
+      "relation": "evaluated-by",
+      "created_by": "init-ai-repo",
+      "evidence_path": ".ai/traceability/index.md"
+    }
+  ]
+}
+```
+
+### Wiring eval evidence (eval-result / trajectory-trace)
+
+When eval evidence exists, wire it into the graph so it is reachable from the work item it grades:
+
+- Link the evaluated work item (a `skill`, `pr`, `test`, `issue`, or `plan` node) to its `eval-result` node with an `evaluated-by` edge (`source` = work item, `target` = `eval-result`).
+- Link the `eval-result` node to its `trajectory-trace` node with a `traced-by` edge (`source` = `eval-result`, `target` = `trajectory-trace`).
+- Each `eval-result` and `trajectory-trace` node's `path` MUST point at a real eval artifact under `.ai/evals/<set-id>/` that exists on disk (e.g. the recorded `judgment-demo.json` for a result, the `evalset.json` trajectory or `rubric.md` for a trace). Do not invent paths; reference the committed eval fixtures/outputs.
+- The `evidence_path` on `evaluated-by` / `traced-by` edges should point at the same real eval artifact rather than a generic index, so the edge itself carries provenance.
+
+Both topologies ship a fixture demonstrating this: `reference/fixtures/v3/standalone/.ai/traceability/graph-1.1.json` and `reference/fixtures/v3/umbrella/.ai/traceability/graph-1.1.json`. Each wires a `pr` node → `eval-result` (`evaluated-by`) → `trajectory-trace` (`traced-by`) against the `.ai/evals/example-output-eval/` fixtures.
+
+### Version acceptance and migration
+
+- The validator accepts any graph whose `schema_version` is `>= 1.1` and treats `eval-result`/`trajectory-trace` as known types; it also still accepts `1.0` graphs (back-compat). A node `type` outside the known enum still fails validation at any version.
+- Migration is a no-op for `1.0` consumers: a `1.0` graph is a valid `1.1` graph minus the two new node types. To migrate, bump `schema_version` to `"1.1"` and add `eval-result`/`trajectory-trace` nodes as eval evidence becomes available.
+
+## Required validation
+
+1. Every edge `source` and `target` exists in `nodes`.
+2. Every node has `id`, `type`, `title`, `status`, `repo_id`, and either `path` or `host_url`. Every `type` is in the known enum for the declared schema version (`1.1` adds `eval-result` and `trajectory-trace`); an unknown type fails.
+3. Every node backlink references another existing node ID.
+4. The graph covers BRD/PRD/ADR/plan/issue/PR/test/handoff/workflow/validation artifacts when those artifacts exist.
+5. The human index links every node ID back to its file path or host URL.
+6. The validation report records `status: pass` only when the graph has no dangling edges or backlinks.
+
+## Cross-skill contracts
+
+- `to-prd` must emit or update `prd:*` nodes for generated PRDs/specs.
+- `to-issues` must emit or update `issue:*` nodes and `implements` / `tracked-by` edges.
+- `triage` must preserve issue node status and host URLs when state changes.
+- `setup-skills` must record tracker adapter source metadata for hosted issue nodes.
+- `publish-semver` must link release/versioning evidence to PRD/spec and PR/test nodes.
+- `ai-catapult-init` owns validation and handoff nodes for generated scaffold evidence.
+
+## Safety rules
+
+- Do not infer hosted links from prose when a host adapter readback is available; use the readback URL/ID.
+- Do not drop local fallback nodes during hosted reconciliation; mark them `superseded` and link to the hosted node.
+- Do not store credentials or private tokens in graph nodes, edges, evidence paths, or validation reports.

package/dist/codex-plugin/skills/ai-catapult-init/modules/tracker-adapters.md

@@ -0,0 +1,51 @@
+# Tracker Adapters Module
+
+Read when choosing where BRDs, PRDs, tickets, and comments live. The adapter is selected at scaffold time and referenced by `ai-catapult-init`; full operation semantics live in `setup-skills`. v3 adds an optional Jira adapter and explicit confirmation boundaries for any host adapter that mutates externally visible state.
+
+## Adapter rule
+
+`ai-catapult-init` selects and references setup-skills tracker adapters; it does not duplicate their full operation semantics.
+
+| Host | Adapter | Confirmation-gated operations |
+| --- | --- | --- |
+| GitHub Issues | `setup-skills/issue-tracker-github.md` | create / update / close / re-open / label / assign / project move |
+| Azure DevOps Boards | `setup-skills/issue-tracker-ado.md` | create / update / close / re-open / tag / assign / state transition |
+| GitLab Issues | `setup-skills/issue-tracker-gitlab.md` | create / update / close / re-open / label / assign |
+| Jira (Cloud) | `setup-skills/issue-tracker-jira.md` (v3) | create / update / transition / close / re-open / assign / project / workflow mutation |
+| Local Markdown | `setup-skills/issue-tracker-local.md` | none (local file writes) |
+
+## Required operation shape
+
+Every adapter must document equivalents for:
+
+- create ticket/work item
+- read ticket/work item with comments
+- list/query by state and label/tag
+- comment
+- update state
+- apply/remove label or tag
+- preserve BRD/PRD/parent backlinks
+
+## Jira adapter (v3)
+
+The Jira adapter is optional and confirmation-gated. Use it only when the target repo already uses Jira for issue tracking or the user explicitly opts in. The adapter must document:
+
+- **Project bootstrap** — read existing project metadata and emit a discovery report before any mutation.
+- **Issue creation** — create issues with `summary`, `description`, `issuetype`, `labels`, `assignee`, and BRD/PRD/parent backlinks. Capture the issue key on success.
+- **Workflow transitions** — list the available transitions for a given issue and apply one with explicit confirmation. Non-admin auto-approval of workflow transitions is disallowed.
+- **Comments** — append a comment and capture the comment id. Comments must preserve BRD/PRD/parent backlinks.
+- **Search** — use JQL (`project = FOO AND type = Bug AND status != Done`) for state and label/tag queries.
+- **Webhook ingestion** — optional; if enabled, the adapter reads webhook events and routes them to the local memory layer (`.memory/self-learned/event-patterns.json`). Webhook ingestion does not require confirmation because it is read-only.
+
+### Confirmation boundaries for Jira
+
+- Project creation, project metadata changes, and workflow scheme mutations are externally visible. The adapter must capture an explicit confirmation token before calling the mutation API.
+- Issue creation, update, transition, close, and re-open are externally visible. Each apply call must capture a confirmation token.
+- Comments and read operations do not require a confirmation token.
+- The adapter never fabricates an approval on behalf of a non-admin actor. When the actor is not an admin and the host does not support a non-admin bypass, the apply path is rejected and the dry-run plan is returned for explicit human follow-up.
+- The adapter never stores or generates credentials. Credentials are passed via environment variables or the host CLI's secret store.
+- The adapter writes an audit entry to `.ai/host-policy/jira/audit.jsonl` (per-host, consistent with `modules/host-policy-automation.md`), mirroring the format in `modules/host-policy-automation.md`.
+
+## Hosted apply path
+
+Tracker adapter mutations are routed through the host-policy-automation apply path when they are externally visible. See `modules/host-policy-automation.md` for the discovery / dry-run / confirmation / apply / readback / audit lifecycle.