ai-catapult 0.1.0

package/dist/claude-plugin/skills/ai-catapult-init/modules/documentation-blueprint.md

@@ -0,0 +1,185 @@
+# Documentation Blueprint Module
+
+Read when generating the v3 canonical layout in a target repo. The blueprint defines the deterministic `.ai/`, `.memory/`, and `docs/` trees, and the human/agent entry files. Standalone and umbrella repos both use the same blueprint; umbrella repos only differ in the inherited-assets list and the managed repos.
+
+## Tree shape
+
+```
+.
+├── .ai/
+│   ├── matrix.json
+│   ├── system-prompts/
+│   │   ├── architect.md
+│   │   ├── developer.md
+│   │   └── qa-engineer.md
+│   ├── skills/                  # target-repo tool injection definitions, not Codex skill packages
+│   │   ├── git-ops.json
+│   │   └── workspace-sync.json
+│   ├── workflows/
+│   │   ├── repo-workflow.md
+│   │   └── repo-workflow.json
+│   ├── phases/
+│   │   ├── 01-discover-decide/status.json
+│   │   ├── 02-govern-plan/status.json
+│   │   ├── 03-configure-generate/status.json
+│   │   └── 04-validate-handoff/status.json
+│   ├── handoff/
+│   │   └── init-ai-repo-handoff.md
+│   ├── traceability/
+│   │   ├── graph.json
+│   │   ├── index.md
+│   │   └── validation-report.md
+│   ├── evals/
+│   │   ├── coverage-exceptions.json
+│   │   └── <set>/
+│   │       ├── evalset.json
+│   │       ├── rubric.md
+│   │       └── judge-config.json
+│   ├── policies/
+│   │   └── model-routing.json
+│   ├── observability/
+│   │   ├── conventions.md
+│   │   └── audit-checklist.md
+│   ├── mcp/
+│   │   ├── registry.json
+│   │   └── a2a-handoff.md
+│   ├── reviews/
+│   │   └── ai-failure-modes.md
+│   ├── rules/
+│   │   ├── security.md
+│   │   └── technical-bounds.md
+│   └── drift/
+│       ├── last-drift.json
+│       └── backups/
+├── .memory/
+│   ├── human-override/          # terminal-priority; never silently rewritten
+│   │   ├── custom-conventions.md
+│   │   └── tribal-knowledge.md
+│   └── self-learned/            # local machine-readable knowledge
+│       ├── error-patterns.json
+│       └── module-complexity.json
+├── docs/
+│   ├── architecture/
+│   │   ├── adr/
+│   │   │   └── 0001-init.md
+│   │   └── data-contracts/
+│   ├── specifications/
+│   │   ├── ACTIVE/
+│   │   └── ARCHIVED/
+│   └── learning/
+│       ├── concept-maps/
+│       └── troubleshooting-matrix.md
+├── AGENTS.md
+├── CLAUDE.md                     # thin pointer to AGENTS.md
+├── GEMINI.md                     # thin pointer to AGENTS.md
+├── CONTRIBUTING.md
+└── README.md
+```
+
+## Layer rules
+
+| Layer | Path | Audience | Mutable by sync? |
+| --- | --- | --- | --- |
+| Execution / policy | `.ai/` | Agents and CI | Inherited assets only. |
+| Human override | `.memory/human-override/` | Humans | No; terminal priority. |
+| Self-learned | `.memory/self-learned/` | Agents, local | No; written only by local agents, never by physical-copy sync. |
+| Architecture | `docs/architecture/` | Humans | No; per-repo authorship. |
+| Specifications | `docs/specifications/` | Humans | No; per-repo authorship. |
+| Learning | `docs/learning/` | Humans | No; per-repo authorship. |
+| Entry files | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, `README.md` | Both | Inherited assets only when explicitly listed. |
+
+## `.ai/`
+
+- `system-prompts/` holds role-specific instructions for `architect`, `developer`, and `qa-engineer`. New roles are added with a clearly named `.md` file and a one-line description in the file's first paragraph.
+- `skills/` holds target-repo tool injection definitions in JSON form. These are tool/MCP descriptors that the target repo exposes to agents; they are not the same as Codex skill packages under `skills/`.
+- `rules/` holds repo-specific safety and technical-bounds rules in Markdown. Cross-reference these from `.rules.ts` when present.
+- `matrix.json` holds the topology matrix; see `modules/topology.md`.
+- `workflows/` holds the human repo workflow and machine-readable workflow manifest.
+- `phases/` holds per-phase status JSON for mandatory workflow steps.
+- `handoff/` holds the generated initialization handoff index.
+- `traceability/` holds graph.json, index.md, and validation-report.md for BRD/PRD/work artifact links.
+- `evals/` holds one directory per evalset (`evalset.json`, `rubric.md`, `judge-config.json`) plus `coverage-exceptions.json`. Both output and trajectory evaluation are representable; see `modules/evals.md`. The eval-coverage gate is offline-structural only.
+- `policies/` holds machine-readable routing/config policy. `model-routing.json` (ADR-0003) declares a `schema_version`, provider-neutral tiers `{frontier, mid, cheap}`, a `task_classes` map (task-class → tier), and a `host_aliases` table binding each host (e.g. `claude`, `codex`) to per-tier model names. Frontier covers requirements/architecture/initial-implementation/hard-verification; mid covers standard implementation/planning; cheap covers test generation/first-pass code review/CI monitoring/lookups. Tier aliases — not provider IDs — keep the policy portable; routing is validated offline-structurally (`modules/validation.md` check #15) with no network model resolution.
+- `observability/` holds the generated observability surface (ADR-0005): `conventions.md` (logging and trace conventions) and `audit-checklist.md` (the token-cost and trajectory-audit checklist). Observability is non-optional harness surface — without it agent drift, cost, and trajectory are not auditable. These are generated conventions and a checklist, not live metering: token-cost and trajectory metering execute out-of-band and are recorded as evidence; CI validates only that the conventions and checklist exist (`modules/validation.md` check #16). The PR merge gate in `modules/ci-policy.md` references the audit checklist for behavior-changing PRs.
+- `mcp/` holds the generated MCP/A2A surface (ADR-0005) under `.ai/mcp/`: `registry.json` (the MCP-server registry stub) and `a2a-handoff.md` (the A2A cross-agent handoff convention). Promoting MCP/A2A from a mention to a real surface adopts the open standards now and preserves multi-vendor optionality. The registry is a stub — declared servers carry `status: "stub"` and no resolved endpoint — and the handoff doc is a convention, not a live router; generation makes no network or model call. CI validates only that the registry parses with the expected shape and the handoff convention exists (`modules/validation.md` check #17). See `modules/mcp-a2a.md`.
+- `reviews/` (`.ai/reviews/`) holds the generated AI-failure-mode review checklist (`ai-failure-modes.md`, spec §4.B) plus per-PR review records. The checklist gives reviewers actionable items for the failure modes common to AI-authored code — hallucinated dependencies, slopsquatting, inadequate error handling, and "looks-right" / subtle correctness gaps — so they are caught in review rather than relied on to surface in tests. It is a generated review convention, not a live CI gate; the PR merge gate in `modules/ci-policy.md` references it for AI-authored PRs. CI validates only that the checklist exists and covers the named failure modes (`modules/validation.md` check #18).
+
+## `.memory/`
+
+- `human-override/` is terminal priority. The scaffold never overwrites existing files in this directory; new files are only created with explicit opt-in.
+- `self-learned/` holds machine-readable knowledge such as `error-patterns.json` and `module-complexity.json`. Schemas are versioned with a `schema_version` field and a changelog under `.memory/self-learned/CHANGELOG.md`. See `modules/memory.md` for the full schema rules.
+
+## `docs/`
+
+- `architecture/adr/` holds ADR files numbered as `NNNN-title.md`, starting at `0001-init.md`.
+- `architecture/data-contracts/` holds shared data contract definitions referenced by ADRs and code.
+- `specifications/ACTIVE/` holds current specs; `ARCHIVED/` holds retired specs with a `superseded_by` pointer in their first paragraph.
+- `learning/concept-maps/` holds concept-map diagrams or Markdown summaries; `troubleshooting-matrix.md` is the canonical index for known-issue → fix pairs.
+
+## Entry files
+
+- `AGENTS.md` — agent-facing operating contract and single source of truth for rule-file/static context.
+- `CLAUDE.md` — thin pointer to `AGENTS.md` with no content-bearing sections (ADR-0004).
+- `GEMINI.md` — thin pointer to `AGENTS.md` with no content-bearing sections (ADR-0004).
+- `CONTRIBUTING.md` — human contributor guide.
+- `README.md` — top-level human entry point.
+
+`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, and `README.md` are required for standalone repos. Umbrella repos include them as inherited assets; managed sub-repos may have a thin local override that references the umbrella. Generated `AGENTS.md` and `README.md` link to `.ai/workflows/repo-workflow.md` and `.ai/workflows/repo-workflow.json`. `CLAUDE.md` and `GEMINI.md` carry only a single pointer to `AGENTS.md` and are emitted as thin pointers, not workflow-linking surfaces.
+
+## Harness Map
+
+Generated `AGENTS.md` carries a `## Harness Map` section enumerating the six context types and documenting the static-vs-dynamic context boundary (ADR-0005). The Harness Map is non-optional AGENTS.md surface: it makes the agent's context inputs explicit and reviewable rather than implicit.
+
+The six context types, each emitted as a code-fenced cell pointing at its canonical source in the v3 tree:
+
+| Context type | Canonical source | Static or dynamic |
+| --- | --- | --- |
+| `Instructions` | `AGENTS.md`, `.ai/system-prompts/`, `.ai/rules/` | Static |
+| `Knowledge` | `docs/architecture/`, `docs/specifications/`, `docs/learning/` | Static |
+| `Memory` | `.memory/human-override/`, `.memory/self-learned/` | Dynamic |
+| `Examples` | `.ai/evals/<set>/`, `docs/learning/concept-maps/` | Static |
+| `Tools` | `.ai/skills/`, `.ai/mcp/registry.json` | Dynamic |
+| `Guardrails` | `.ai/rules/security.md`, `.ai/rules/technical-bounds.md`, `.ai/policies/` | Static |
+
+**Static-vs-dynamic boundary.** Static context is fixed at the start of a task (instructions, knowledge, examples, guardrails) and is reviewed and versioned in-repo; dynamic context is assembled per-run (memory written by local agents, tool/MCP results resolved at call time). The boundary is a reviewed, versioned architectural decision (ADR-0005), not an implicit one: moving a context type across the boundary requires an ADR update.
+
+## Mechanical scaffold templates
+
+The static, deterministic subset of this tree is pre-authored in
+`ai-catapult-init/templates/` and is the SSOT the ai-catapult CLI vendors and
+emits. The boundary between mechanical (templated, deterministic) and
+judgment-laden (generated in-harness after discovery) paths is recorded in
+`ai-catapult-init/templates/boundary-manifest.json`.
+
+- **Mechanical** — directory layout, matrix.json skeleton, phase status stubs,
+  policy/rules stubs, MCP registry stub, observability/review checklists,
+  system-prompt skeletons, entry-file pointers (AGENTS.md/CLAUDE.md/GEMINI.md),
+  Archgate rules (.rules.ts), CI hook config (prek.toml, ci-prek.yml).
+  Template files use `{{TOKEN}}` placeholders for repo-specific values
+  (REPO_ID, TOPOLOGY_TYPE, DATE, UPSTREAM_URL, UPSTREAM_REF).
+- **Judgment-laden** — handoff document, traceability graph and index,
+  ADR bodies, cascade plan, .memory/ human-override content. These are
+  produced in-harness by the plugin after the four discovery phases.
+
+When adding a new `.ai/` path to this blueprint, update
+`ai-catapult-init/templates/boundary-manifest.json` to classify it and, if
+mechanical, add the corresponding template file under `ai-catapult-init/templates/`.
+
+## Generation rules
+
+1. Existing files are never overwritten silently. If a target path exists, the generator emits a `present-not-overwritten` audit entry and skips the write.
+2. The first generation writes a `migration` block to `.ai/matrix.json` referencing the legacy-to-v3 migration manifest; see `modules/validation.md`.
+3. Destructive operations (deleting a legacy artifact) require explicit confirmation; see `modules/host-policy-automation.md` and `modules/validation.md`.
+4. Generation emits an audit log under `.ai/drift/last-generation.json` listing per-path action (`created`, `present-not-overwritten`, `skipped-conflict`).
+
+## Migration from legacy scaffold
+
+Migration rules, the action vocabulary, and the migration-manifest schema are owned by `modules/migration.md`. The blueprint does not duplicate them; consumers must read `modules/migration.md` for the authoritative classification of `.agents/`, `.rules.ts`, `docs/adr/`, marker blocks, and any pre-existing `.memory/` content.
+
+## Cascade outputs
+
+When the cascade branch is enabled, generate `.ai/cascade/cascade-plan.json`, `.ai/cascade/audit.jsonl`, `.ai/cascade/reconciliation-report.md`, and `.ai/cascade/host-adapters/<host>.json` for each configured host. These outputs are validation artifacts; hosted mutation remains confirmation-gated.
+
+## Skill catalog outputs
+
+When the target repo owns a skill catalog, generate `.ai/skills/catalog-audit.json`, `.ai/skills/description-exceptions.json`, and `.ai/skills/modernization-report.md`. These artifacts enforce compact descriptions, progressive disclosure, trigger boundaries, cross-skill links, and AI-SDLC compatibility.

package/dist/claude-plugin/skills/ai-catapult-init/modules/evals.md

@@ -0,0 +1,93 @@
+# Evals Module
+
+Read when generating the `.ai/evals/` scaffold or wiring the offline eval-coverage gate. Evals are the verification surface for non-deterministic behavior; tests verify deterministic parts, evals verify the rest. See ADR-0002.
+
+## Principle
+
+"Set the bar at the eval, not the demo." A shippable capability is not complete without an eval carrying an explicit rubric. In CI the bar is **structural** (schema + rubric + judge-config present and well-formed) and **offline** — no model or network call. Eval **quality** is verified out-of-band via an LM-judge run, recorded as evidence, not as a CI gate.
+
+## Generated outputs
+
+| Output | Purpose |
+| --- | --- |
+| `.ai/evals/<set>/evalset.json` | Labelled cases for one evalset: inputs, expected behavior, and reference trajectories. |
+| `.ai/evals/<set>/rubric.md` | Scoring rubric. Required. Criteria, weights summing to `1.0`, and a passing threshold. |
+| `.ai/evals/<set>/judge-config.json` | LM-judge harness configuration (stub by default): judge tier, mode, evaluated dimensions, and threshold. |
+| `.ai/evals/coverage-exceptions.json` | Audited exceptions for changes that bypass the coverage gate; owner, reason, expiry. Default is no exceptions. |
+
+## Evalset structure
+
+`evalset.json` declares `schema_version`, a stable `set_id`, a `kind`
+(`output` or `trajectory`), an optional `skill_under_test`, and a non-empty
+`cases` array. Each case carries a stable `case_id`, an `input`, an
+`expected_behavior`, and a reference `trajectory` (the expected tool-call
+sequence).
+
+Both evaluation modes are representable in one scaffold:
+
+- **Output evaluation** scores the final artifact against `expected_behavior`
+  using the rubric's output criteria.
+- **Trajectory evaluation** scores the recorded tool-call sequence against the
+  case `trajectory` using the rubric's trajectory criteria. The recorded
+  sequence is represented by the `trajectory_trace` block in `judge-config.json`
+  and surfaces in the traceability graph as a `trajectory-trace` node.
+
+## Rubric template
+
+`rubric.md` is a required Markdown table. Each row names a criterion, the
+dimension it scores (`output` or `trajectory`), a weight, and the passing bar.
+Weights sum to `1.0`; the file declares a passing threshold. A missing or empty
+rubric fails the coverage gate.
+
+## LM-judge harness stub
+
+`judge-config.json` declares the judge `tier` (a provider-neutral routing tier;
+see `modules/documentation-blueprint.md` policy outputs), `mode`
+(`lm-judge`), the `harness` (`stub` by default), the `evaluates` dimensions
+(`output`, `trajectory`, or both), a `passing_threshold`, and `execution`
+(`out-of-band`). The stub is intentionally non-executing: it documents the
+shape an out-of-band runner consumes. CI never invokes it.
+
+## Worked example: out-of-band LM-judge demonstration
+
+`reference/fixtures/v3/standalone/.ai/evals/example-output-eval/judgment-demo.json`
+is a recorded out-of-band LM-judge judgment for the `example-output-eval`
+fixture, committed as evidence. It shows the shape an out-of-band runner
+produces end-to-end: which evalset and rubric were judged, the illustrative
+judge model and a timestamp placeholder, one per-criterion score and rationale
+for every rubric criterion, and an aggregate score (the rubric-weighted sum)
+checked against the rubric's passing threshold.
+
+It is a demonstration, not a CI gate — it carries an explicit "recorded
+out-of-band demonstration, not a CI gate" disclaimer, was authored without any
+live model or network call, and CI never invokes it. It is the in-repo proof
+that the structural-in-CI + quality-out-of-band split works. The discoverable
+offline runner is `tests/lm_judge_demo_test.sh`.
+
+## Eval-coverage gate (D1/D2)
+
+The gate is diff-aware and offline:
+
+1. **Trigger (D1).** A skill changed in the PR diff that declares a non-empty
+   `eval:` key in its frontmatter is a shippable capability. Doc-only or
+   unchanged skills are exempt.
+2. **Structural check (D2).** The declared evalset directory must exist and be
+   structurally valid: `evalset.json` and `judge-config.json` parse and carry
+   their required keys; `rubric.md` exists and is non-empty.
+3. **Audited exception.** A token in `.ai/evals/coverage-exceptions.json`
+   (owner, reason, expiry) bypasses the gate for a non-shippable change. This
+   mirrors the `> 280`-character description-exception escape hatch in
+   `modules/skill-modernization.md`.
+
+The gate exits non-zero only when a changed shippable skill references a missing
+or malformed evalset with no audited exception. It performs no model or network
+call. The generated PR-merge-gate text (see `modules/ci-policy.md`) carries the
+honest caveat: eval coverage is enforced structurally in CI; eval quality is
+verified via an out-of-band LM-judge run.
+
+## Safety rules
+
+- Do not weaken the structural validator to make a missing evalset pass; author
+  the evalset or record an audited exception.
+- Do not add a model or network dependency to the CI eval path.
+- Do not claim a passing eval in CI; CI proves declaration, not quality.

package/dist/claude-plugin/skills/ai-catapult-init/modules/foundation.md

@@ -0,0 +1,19 @@
+# Foundation Module
+
+Read when writing the current base scaffold artifacts. This module names the artifact set; use `../REFERENCE.md` for full legacy template bodies until the templates are split further.
+
+## Artifacts
+
+- `.agents/skills/karpathy-guidelines/SKILL.md` and `REFERENCE.md`
+- `upstream.lock` with source, via, pinned SHA, update date, and sync script
+- `.gitignore` marker block plus `upstream-pocock/.gitkeep`
+- `raw/docs/incident-template.md`
+- `scripts/sync-upstream.sh` as a documented sync scaffold
+- `.github/workflows/ci-prek.yml`, `prek.toml`, `scripts/validate-rules.sh`, and `scripts/archgate.sh`
+- `.rules.ts` with backend, frontend, data, architecture, and general rule domains
+- `AGENTS.md` and `README.md` AI SDLC marker blocks (`CLAUDE.md`/`GEMINI.md` are thin pointers to `AGENTS.md` and carry no marker block)
+- `docs/adr/ADR-TEMPLATE.md` and `ADR-0001-record-architecture-decisions.md`
+
+## Idempotency
+
+Before writing marker blocks, check both the marker and the `AI SDLC Methodology` header. If the header exists without the marker, warn and skip rather than duplicating content.

package/dist/claude-plugin/skills/ai-catapult-init/modules/host-policy-automation.md

@@ -0,0 +1,151 @@
+# Host Policy Automation Module
+
+Read when applying hosted branch, pull-request, or policy mutations to GitHub, Azure DevOps, GitLab, or Jira, or when emitting dry-run diffs and confirmation gates. This module governs the apply path. The default is dry-run; an externally visible or policy-altering apply requires explicit confirmation even when admin credentials are present.
+
+## Default behavior: dry-run first
+
+The default run is `dry-run`. The output is a diff that lists every setting that would change, added, or removed. The apply path is gated by:
+
+1. **Discovery** — read current host settings via the official REST/GraphQL APIs and cache them in `.ai/host-policy/<host>/discovery.json`.
+2. **Dry-run diff** — compute the diff between current and intended settings and write it to `.ai/host-policy/<host>/dry-run.json`. The diff includes `path`, `current_value`, `intended_value`, and `change_kind` (`add`, `update`, `remove`).
+3. **Confirmation gate** — stop and require an explicit user confirmation. The confirmation is recorded as a `confirmation_token` in the audit log; see `## Audit log` below.
+4. **Apply** — call the official APIs to apply the intended settings. Capture every API response and the resulting `etag` or version.
+5. **Readback** — re-read the host settings after the apply and assert they match the intended values. Write the readback to `.ai/host-policy/<host>/readback.json`.
+6. **Audit** — append an entry to `.ai/host-policy/audit.jsonl` with timestamp, host, plan, diff SHA-256, confirmation token, apply results, and readback status.
+
+Apply is rejected if any of discovery, dry-run, confirmation, or readback fails. A failed apply is rolled back to the values recorded at discovery time when the host supports it; otherwise the audit log records the partial state and emits a `rollback-skipped` entry with the host's response.
+
+## Confirmation boundary
+
+The confirmation gate is mandatory for every apply, including when admin credentials are present. The user's confirmation must:
+
+- name the host (e.g., `github.com/example/repo`),
+- name the protected branch or project (e.g., `main`, `services/auth`),
+- summarize the dry-run diff (number of adds, updates, removes),
+- capture the timestamp and the actor identity, and
+- be recorded in the audit log as a `confirmation_token` tied to the run.
+
+A confirmation token is valid only for the run that produced it. Retrying the same plan after a failure requires a fresh confirmation.
+
+### Token format
+
+Confirmation tokens follow the pattern `ct-YYYY-MM-DD-NNN` where `YYYY-MM-DD` is the run date and `NNN` is a zero-padded sequence number scoped to the run date. Tokens are unique per run date; a token is consumed by the first apply that uses it and is invalid for any subsequent apply, even on retry of the same plan.
+
+Implementations validate the format with the regex `^ct-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}$` and reject tokens that do not match. The format is intentionally human-readable so audit entries are auditable without a separate format decoder.
+
+## Admin exception and auto-approval
+
+Admins may use host-supported mechanisms to bypass or auto-merge when policy permits. The module never fabricates approvals on top of a host that does not support them. Concretely:
+
+- **GitHub** — admins may use the host's bypass / auto-merge / admin-enforcement features. The module records the bypass as a `host-supported-bypass` audit entry and does not invent a separate approval layer.
+- **Azure DevOps** — admins may use the host's policy override or allowed-author bypass. The module records the override and does not invent a separate approval.
+- **GitLab** — admins may use the host's allowed-to-merge / allowed-to-push bypass. The module records the bypass and does not invent a separate approval.
+- **Jira** — admins may use the host's project-level permissions to bypass workflow transitions. The module records the bypass and does not invent a separate approval.
+
+**Non-admin auto-approval is disallowed.** The module never marks a pull request, merge request, or work item as approved on behalf of a non-admin actor. If the user 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.
+
+## Provider matrix
+
+### GitHub
+
+- **Discovery** — REST API: `GET /repos/{owner}/{repo}/branches/{branch}/protection` and `GET /repos/{owner}/{repo}/rulesets`. See [GitHub REST branch protection](https://docs.github.com/en/rest/branches/branch-protection) and [GitHub rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets).
+- **Dry-run diff** — compares current protection and rulesets against the intended shape (required status checks, required review count, dismiss stale reviews, required linear history, signed commits, merge queue).
+- **Apply** — `PUT /repos/{owner}/{repo}/branches/{branch}/protection` and the rulesets endpoints. Capture the response `etag` per change.
+- **Readback** — re-fetch the protection and rulesets; assert equality with the intended shape; record in `.ai/host-policy/github/readback.json`.
+- **Admin exception** — host-supported bypass / auto-merge / admin enforcement only; non-admin auto-approval is disallowed.
+- **Negative test** — when admin credentials are present but no confirmation is captured, the apply path emits the dry-run diff and refuses to call the mutation endpoints. The audit log records `apply-blocked-no-confirmation`.
+
+Official documentation anchors:
+
+- [GitHub branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches)
+- [GitHub rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)
+- [GitHub REST branch protection](https://docs.github.com/en/rest/branches/branch-protection)
+
+### Azure DevOps
+
+- **Discovery** — REST API: `GET https://dev.azure.com/{org}/{project}/_apis/git/policy/configurations?repositoryId={repoId}&refName=refs/heads/{branch}`. See [Azure Repos branch policies](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies-overview?view=azure-devops) and [Azure Repos branch policies settings](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops).
+- **Dry-run diff** — compares existing policies (build validation, required reviewers, comment resolution, work-item linking) against the intended shape.
+- **Apply** — `POST` and `PUT /_apis/git/policy/configurations` for each policy type. Capture the response status and policy id.
+- **Readback** — re-fetch the policy configurations; assert equality; record in `.ai/host-policy/ado/readback.json`.
+- **Admin exception** — host-supported policy override / allowed-author bypass only; non-admin auto-approval is disallowed.
+- **Negative test** — when admin credentials are present but no confirmation is captured, the apply path emits the dry-run diff and refuses to call the mutation endpoints. The audit log records `apply-blocked-no-confirmation`.
+
+Official documentation anchors:
+
+- [Azure Repos branch policies overview](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies-overview?view=azure-devops)
+- [Azure Repos branch policies settings and build validation](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops)
+- [Azure Pipelines triggers (YAML `pr:` triggers vs branch-policy build validation)](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/triggers?view=azure-devops)
+
+### GitLab
+
+- **Discovery** — REST API: `GET /api/v4/projects/{id}/protected_branches` and `GET /api/v4/projects/{id}/merge_request_approval_rules`. See [GitLab protected branches](https://docs.gitlab.com/ee/user/project/protected_branches.html) and [GitLab merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/).
+- **Dry-run diff** — compares current protected-branch shape and approval rules against the intended shape. Note GitLab tier differences: some approval-rule features require Premium or higher; blocked or unsupported features are reported in the dry-run and require tier-appropriate configuration. If discovery reports a Free/Core tier for a Premium/Ultimate-only approval-rule mutation, apply refuses mutation endpoints and records `apply-rejected-gitlab-tier-restriction`.
+- **Apply** — `POST /api/v4/projects/{id}/protected_branches` and the approval-rule endpoints. Capture the response status and rule id.
+- **Readback** — re-fetch the protected branches and approval rules; assert equality; record in `.ai/host-policy/gitlab/readback.json`.
+- **Admin exception** — host-supported allowed-to-merge / allowed-to-push bypass only; non-admin auto-approval is disallowed.
+- **Negative test** — when admin credentials are present but no confirmation is captured, the apply path emits the dry-run diff and refuses to call the mutation endpoints. The audit log records `apply-blocked-no-confirmation`.
+
+Official documentation anchors:
+
+- [GitLab protected branches](https://docs.gitlab.com/ee/user/project/protected_branches.html)
+- [GitLab merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
+
+### Jira
+
+- **Discovery** — REST API: `GET /rest/api/3/project/{projectIdOrKey}` and `GET /rest/api/3/issue/{issueIdOrKey}`. See [Jira Cloud REST API v3 introduction](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/).
+- **Dry-run diff** — compares the project metadata, workflow scheme, and issue fields against the intended shape.
+- **Apply** — Jira mutations are externally visible. The apply path requires an explicit confirmation that names the project key, the workflow scheme id, and the list of affected issues. See [Jira Cloud REST API v3 projects](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/) and [Jira Cloud REST API v3 workflows](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflows/).
+- **Readback** — re-fetch the project and workflow configuration; assert equality; record in `.ai/host-policy/jira/readback.json`.
+- **Admin exception** — host-supported project-permission bypass only; non-admin auto-approval is disallowed.
+- **Negative test** — when admin credentials are present but no confirmation is captured, the apply path emits the dry-run diff and refuses to call the mutation endpoints. The audit log records `apply-blocked-no-confirmation`.
+
+Official documentation anchors:
+
+- [Jira Cloud REST API v3 introduction](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)
+- [Jira Cloud REST API v3 projects](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/)
+- [Jira Cloud REST API v3 workflows](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflows/)
+
+## Mocked and live modes
+
+Tests use mocked host adapters. Live host mutations require explicit credentials and an explicit confirmation token recorded in the run directory. The module does not silently fall back from mocked to live mode. The skill's regression suite asserts:
+
+- `apply-blocked-no-confirmation` is recorded when admin credentials are present without confirmation.
+- `apply-rejected-non-admin` is recorded when the actor is not an admin and the host does not support a non-admin bypass.
+- `apply-rejected-dry-run-mismatch` is recorded when the readback differs from the intended shape.
+- `apply-rejected-gitlab-tier-restriction` is recorded when GitLab discovery reports a Free/Core tier for an intended Premium/Ultimate-only approval-rule mutation.
+
+## Audit log
+
+Every run appends one JSON object per line to `.ai/host-policy/<host>/audit.jsonl`, where `<host>` is `github`, `ado`, `gitlab`, or `jira`:
+
+```json
+{
+  "ts": "2026-06-07T00:00:00Z",
+  "host": "github.com/example/repo",
+  "audit_path": ".ai/host-policy/github/audit.jsonl",
+  "actor": "init-ai-repo",
+  "mode": "apply",
+  "confirmation_token": "ct-2026-06-07-001",
+  "diff_sha256": "...",
+  "apply_results": [
+    {"path": "branch_protection.required_status_checks", "status": "ok", "etag": "..."}
+  ],
+  "readback_status": "match",
+  "rollback": "not-needed"
+}
+```
+
+Dry-run entries set `mode: "dry-run"` and omit `apply_results` and `confirmation_token`. Blocked entries set `mode: "blocked"` and include the reason in `apply_results[].status`.
+
+## Safety rules
+
+- The apply path is always confirmation-gated. There is no `auto-apply` mode.
+- Backups of pre-apply host settings live under `.ai/host-policy/<host>/discovery.json` and are kept for at least the audit retention window.
+- The module never reads or writes credentials to disk. Credentials are passed via environment variables or the host CLI's secret store.
+- The module never publishes a `confirmation_token` to the audit log when the run was a dry-run.
+
+## Cross-references
+
+- `modules/ci-policy.md` — CI files and branch-policy/ruleset checklist artifacts. Host-policy-automation is the apply path; ci-policy is the checklist path.
+- `modules/tracker-adapters.md` — tracker adapter choice; Jira adapter is added in v3.
+- `modules/validation.md` — host-policy negative tests, regression commands, and the audit-format check.

package/dist/claude-plugin/skills/ai-catapult-init/modules/language-packs.md

@@ -0,0 +1,63 @@
+# Language Packs Module
+
+Read when selecting local and CI checks for a repo. Packs are modular: detect manifests first, then ask or require explicit opt-in before assuming missing tools/dependencies. Each pack is opt-in and never adds dependencies on its own.
+
+## Selection rules
+
+1. Detect manifests and lockfiles.
+2. Prefer existing package manager commands over inventing new ones.
+3. Add CI steps only for tools already present or explicitly selected.
+4. In polyglot repos, run each detected pack independently and keep failures attributable to the pack.
+5. Do not add dependencies as part of `ai-catapult-init` unless the user explicitly asks.
+
+## Pack matrix
+
+| Pack | Detection signals | Local checks | CI notes |
+| --- | --- | --- | --- |
+| TypeScript/Node | `package.json`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `tsconfig.json` | package-manager test/lint/typecheck scripts when present | Use detected package manager; do not assume npm if pnpm/yarn lock exists. |
+| Python | `pyproject.toml`, `requirements.txt`, `uv.lock`, `poetry.lock`, `setup.py` | existing pytest/ruff/mypy scripts or documented commands | Prefer uv/poetry when lockfile exists; do not install tools implicitly. |
+| Rust | `Cargo.toml`, `Cargo.lock` | `cargo test`, `cargo clippy`, `cargo fmt --check` when configured | Use stable toolchain unless repo pins another toolchain. |
+| Go | `go.mod`, `go.sum` | `go test ./...`, `go vet ./...`, configured linters | Respect module/workspace layout and existing Make targets. |
+| JVM | `pom.xml`, `build.gradle`, `settings.gradle`, `gradlew`, `mvnw` | Maven/Gradle wrapper test/check tasks | Prefer checked-in wrapper over system Maven/Gradle. |
+| .NET Core / EF Core | `*.csproj` with `TargetFramework` `net6.0`+ or `netstandard2.1`+; `*.sln`; `global.json`; `appsettings*.json`; `Program.cs` using `Host.CreateDefaultBuilder` or `WebApplication.CreateBuilder`; `*.DbContext` and `*ModelBuilder*.cs` for EF Core | `dotnet test`, `dotnet build`, `dotnet format --verify-no-changes`, `dotnet ef migrations script` (when EF Core present) | Respect SDK pinned by `global.json`. CI must use the same SDK; do not run `dotnet --list-sdks` from a system install. |
+| Legacy .NET / EF (Framework) | `*.csproj` with `TargetFrameworkVersion` v4.x; `packages.config`; `App.config` / `Web.config`; `*.edmx` under `Models\\` or `DAL\\`; presence of `EntityFramework` 6.x package reference | `msbuild /t:Build` (when present) plus `nuget restore`; legacy `EF` migrations via `migrate.exe` only if configured | Do not assume the host has .NET Framework SDK installed; run on a Windows agent or in a self-hosted runner with the legacy toolchain. Surface legacy checks as opt-in until the toolchain is verified. |
+| Polyglot | Multiple pack signals | Run each pack's existing commands separately | Name CI jobs per pack to keep required checks unambiguous. |
+
+## .NET Core / EF Core specifics
+
+- Detection: parse `*.csproj` for `<TargetFramework>net6.0</TargetFramework>` or newer, or for `<PackageReference Include="Microsoft.EntityFrameworkCore" ...>`. EF Core is implied by `Microsoft.EntityFrameworkCore.*` package references.
+- Toolchain pin: respect `global.json`. If `global.json` is missing, record a `toolchain-not-pinned` note in the scaffold output; do not assume a default SDK.
+- Local checks: `dotnet restore` (when lockfile missing), `dotnet build -c Release`, `dotnet test`, `dotnet format --verify-no-changes`, and `dotnet ef migrations script --idempotent` only when EF Core is present.
+- CI matrix: run on `ubuntu-latest` and `windows-latest` only when the repo contains Windows-only code paths. Do not silently add a Windows job to a Linux-only repo.
+- Analyzers: when `Microsoft.CodeAnalysis.NetAnalyzers` is referenced, add `<EnableNETAnalyzers>true</EnableNETAnalyzers>` and `<AnalysisLevel>latest</AnalysisLevel>` checks; surface them as opt-in when not present.
+- Migrations: `dotnet ef migrations script` is a build-time artifact, not a runtime test. The pack does not run migrations against a live database in CI.
+
+## Legacy .NET / EF specifics
+
+- Detection: parse `*.csproj` for `<TargetFrameworkVersion>v4.</TargetFrameworkVersion>` (4.x) or for `packages.config` alongside `App.config` / `Web.config`. EF 6.x is implied by `<package id="EntityFramework" version="6.x" />` in `packages.config`.
+- Toolchain pin: legacy projects pin the .NET Framework target version in the project file. The pack must not assume the agent has the matching reference assemblies. Surface a `legacy-toolchain-required` note and require explicit opt-in.
+- Local checks: prefer `msbuild` from a self-hosted runner or a Windows agent. Do not run `dotnet test` against a legacy project; it is not supported.
+- Migrations: EF 6.x migrations are produced via `migrate.exe` and may require a startup project. The pack documents the path but does not run migrations in CI by default.
+- Supersession: when a legacy project is migrating to .NET Core / EF Core, the pack records both states in `language-packs-snapshot.json` and tracks the migration in `docs/architecture/adr/`. See `modules/migration.md` for the full migration classification rules.
+
+## Scaffold output
+
+When a pack is selected, record:
+
+- detection evidence (which file matched and which line was the signal)
+- selected commands and their rationale
+- commands intentionally skipped and why (e.g., `dotnet ef migrations script` skipped because EF Core is not present)
+- CI job/check names per pack
+- required environment variables or services
+- owner for maintaining the pack
+- toolchain pin (or `toolchain-not-pinned` note)
+
+## Golden fixture expectations
+
+At minimum, fixture coverage should demonstrate:
+
+- one TypeScript/Node repo with `pnpm-lock.yaml` resolved to pnpm, not npm
+- one Python repo with `uv.lock` resolved to uv
+- one .NET Core / EF Core repo with `global.json` and EF Core migrations
+- one legacy .NET / EF Framework repo marked as opt-in and surfaced via the legacy supersession rules
+- one polyglot repo where each pack's checks run independently

package/dist/claude-plugin/skills/ai-catapult-init/modules/mcp-a2a.md

@@ -0,0 +1,63 @@
+# MCP/A2A Module
+
+Read when generating the `.ai/mcp/` scaffold: the MCP-server registry stub and
+the A2A cross-agent handoff convention. This promotes the single passing MCP/A2A
+mention into a real, reviewed surface. See ADR-0005.
+
+## Principle
+
+Adopt open standards now: **MCP** (Model Context Protocol) for tool access and
+**A2A** (Agent2Agent) for cross-agent delegation. Choosing them at init time
+preserves multi-vendor/framework optionality and avoids re-platforming later.
+The generated surface is **offline and deterministic** — a registry stub plus a
+convention doc. `ai-catapult-init` resolves no live endpoint and makes no network or
+model call at generation time.
+
+## Generated outputs
+
+| Output | Purpose |
+| --- | --- |
+| `.ai/mcp/registry.json` | MCP-server registry stub: declared servers, their transport, advertised tools, and an `a2a` block pointing at the handoff convention. |
+| `.ai/mcp/a2a-handoff.md` | A2A cross-agent handoff convention: the handoff envelope, its fields, and the rules that keep delegation auditable. |
+
+## Registry stub shape
+
+`registry.json` declares `schema_version`, a `servers` array, and an `a2a`
+block. Each server entry carries `name`, `transport`, `status`, `endpoint`, and
+a `tools` array. Every server `status` is `"stub"` and `endpoint` is `null`: the
+registry documents the shape an out-of-band runner consumes, never a resolved
+live connection. The `a2a` block declares the `protocol`, a `handoff_convention`
+pointer to `.ai/mcp/a2a-handoff.md`, and `correlation_id_required`. Umbrella
+repos additionally set `a2a.cross_repo: true` and may register a workspace-sync
+server for managed-repository operations.
+
+## A2A handoff convention
+
+`a2a-handoff.md` defines a single JSON handoff envelope carried on every
+cross-agent delegation. Required fields: `correlation_id` (preserved end-to-end
+so the trajectory stays one trace), `from_agent`, `to_agent`, `task` (with an
+acceptance check), `context_refs` (pointers, not copied context), and
+`constraints` (offline-only, no hosted mutation). The receiving agent opens a
+child span linked by `correlation_id`, mirroring the trace conventions in
+`.ai/observability/conventions.md`. Envelopes never inline secrets; large
+context is referenced by pointer. In an umbrella, cross-repo handoffs reference
+the managed repository by its matrix path and never bypass the physical-copy
+sync boundary.
+
+## Validation
+
+The MCP/A2A surface is validated offline and structurally by
+`modules/validation.md` check #17: for both v3 fixtures, `.ai/mcp/registry.json`
+parses, declares `schema_version`, a `servers` array of stub entries, and an
+`a2a` block with a `handoff_convention` pointer; `.ai/mcp/a2a-handoff.md` exists,
+is non-empty, and carries the handoff-envelope and `correlation_id` keywords.
+The discoverable runner is `tests/mcp_a2a_test.sh`.
+
+## Safety rules
+
+- Do not add a model or network dependency to the generated MCP/A2A path; the
+  registry is a stub and the handoff doc is a convention.
+- Do not record a resolved live `endpoint`; servers stay `status: "stub"` until
+  an out-of-band operator wires them.
+- Do not drop `correlation_id` from the handoff envelope; the trace and the
+  cross-agent trajectory depend on it.