@r3dlex/ai-catapult 0.1.0

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

@@ -0,0 +1,79 @@
+---
+name: ai-catapult-init
+description: 'Bootstrap AI-ready repo governance, traceability, cascade, catalog audits, validation. Deprecated compatibility aliases: init-ai-repo, ai-sdlc-init. Use when setting up AI SDLC.'
+---
+
+# Init AI Repo
+
+## Quick Start
+
+Run this skill in the target repo. `ai-catapult-init` is the canonical skill name; `init-ai-repo` and `ai-sdlc-init` remain deprecated compatibility aliases. Use dry-run first when scope or host choices are unclear. Keep hosted settings as checklist output unless the user explicitly requests an admin/credentialed action.
+
+## Workflow
+
+### Phase 1 — Discover & Decide
+Inspect repository state, host tooling, trackers, CI, and runtime conventions. Choose greenfield bootstrap, brownfield adoption, hosted-tracker-first, or local fallback. Emit `.ai/matrix.json`, `.ai/init/repo-profile.json`, `.ai/init/sdlc-path.md`, and `.ai/phases/01-discover-decide/`. OMX surfaces: `$deep-interview`, `$plan`, `$ralplan`; OMC surfaces must produce the same artifact contract.
+
+### Phase 2 — Govern & Plan
+Generate or refresh `AGENTS.md`, `RULES.md`, `PLANS.md`, `CONTRIBUTING.md`, active/archived specs, ADRs, `.ai/work-intake/`, `.ai/plans/`, and `.ai/phases/02-govern-plan/`. Ensure a hosted issue/ticket when configured and authorized. Local fallback is allowed before coding, but it must be reconciled before final PR merge. Require active spec/PRD, plan, and acceptance criteria before implementation.
+
+### Phase 3 — Configure & Generate
+Generate command/runtime surfaces and policy automation under `.ai/bin/`, `.ai/policies/`, `.ai/commands/omx/`, `.ai/commands/omc/`, `.ai/language-packs/`, optional `Makefile`/`justfile`, and `.ai/phases/03-configure-generate/`. OMX surfaces: `$ralph`, `$team`, `$ultragoal`, `$ultrawork`; OMC aliases/commands delegate to the same generated structures rather than duplicate semantics.
+
+### Phase 4 — Validate & Handoff
+Run local validation, drift checks, generated smoke tests, and hosted/local ticket reconciliation. Emit `.ai/validation/report.md`, `.ai/drift/migration-manifest.json`, `.ai/handoff/init-ai-repo-handoff.md`, and `.ai/phases/04-validate-handoff/`. OMX surfaces: `$doctor`, `$code-review`, `$team`, `$ralph`. The handoff records done, verified, remaining, and reconciliation status.
+
+### Internal checkpoints
+
+The public workflow is four phases, but the generator preserves the original eight internal checkpoints for compatibility and traceability:
+
+1. Detect repo state
+2. Choose SDLC path
+3. Scaffold foundation and v3 layout
+4. Scaffold work intake
+5. Configure host adapters
+6. Configure CI and policy
+7. Select language packs
+8. Validate and emit handoff
+
+## PR Merge Gate
+
+Every implementation initialized by this skill must assume protected `main` and PR-only delivery. Emit provider-specific branch-policy checklist/config artifacts unless the user explicitly authorizes hosted mutation with credentials. Admin users may self-approve only when host policy permits it and the host/runtime explicitly supports an admin approve/admin bypass lane for the same actor; all required checks must still pass. If the host rejects same-actor review approval (for example, GitHub hosted PR review), use a distinct admin reviewer or explicit host admin bypass/admin merge. Record the actor, authority, reason, checks, and approval mode, and fail closed when same-actor admin approval support cannot be proven.
+
+When this skill creates or updates PR workflow guidance, require merge only after:
+
+1. The **architect** confirms the implementation still matches ADRs, module boundaries, branch policy, and acceptance criteria.
+2. The **reviewer** confirms code quality, safety, documentation, and drift checks have no blocking findings.
+3. The **executor** confirms the requested change is implemented, cleanup is complete, and all required checks are green.
+4. All actionable PR comments are resolved and local CI plus host SCM CI (GitHub Actions, Azure Pipelines, or GitLab CI as applicable) are green.
+5. The loop reaches explicit agreement across architect, reviewer, and executor; if any role disagrees, comments remain actionable, checks are not green, or branch policy forbids merge, do not merge or auto-merge.
+
+`modules/ci-policy.md` adds a mechanical eval-coverage check to this PR merge gate: a changed shippable skill must declare a structurally valid evalset. See `modules/evals.md`.
+
+## Module Map
+
+- `modules/README.md` — read when choosing which Layer 3 module applies.
+- `modules/phases/README.md` — read when mapping the four public phases to internal checkpoints.
+- `modules/topology.md` — read when generating `.ai/matrix.json` or validating umbrella depth.
+- `modules/documentation-blueprint.md` — read when generating the v3 `.ai/`, `.memory/`, and `docs/` trees.
+- `modules/memory.md` — read when defining `.memory/human-override/` and `.memory/self-learned` schemas.
+- `modules/sync.md` — read when implementing physical-copy sync and drift detection.
+- `modules/host-policy-automation.md` — read when applying hosted branch/PR/policy mutations safely.
+- `modules/validation.md` — read when validating generated artifacts, depth rules, and golden fixtures.
+- `REFERENCE.md` — read only for legacy full template bodies that have not yet moved into focused modules.
+- `modules/readme-documentation.md` — read when initializing, augmenting, or rewriting `README.md`.
+- `modules/release-versioning.md` — read when initializing release tagging, versioning, or CI/CD release workflows.
+- `modules/workflow.md` — read when generating repo workflow docs, workflow/status manifests, entry-surface links, and handoff indexes.
+- `modules/traceability.md` — read when generating stable traceability IDs, graph schema, backlink validation, graph fixtures, or cross-skill requirement/work-artifact links.
+- `modules/cascade.md` — read when generating multi-repo cascade plans, first-run confirmation gates, idempotent linked updates, host adapter contracts, audits, and reconciliation reports.
+- `modules/skill-modernization.md` — read when auditing compact descriptions, progressive disclosure, trigger boundaries, cross-skill links, and AI-SDLC compatibility.
+- `modules/evals.md` — read when generating the `.ai/evals/` scaffold or the offline eval-coverage gate that `modules/ci-policy.md` adds to the PR merge gate.
+- `modules/mcp-a2a.md` — read when generating the `.ai/mcp/` registry stub and the A2A cross-agent handoff convention.
+
+## Safety Rules
+
+- Keep `SKILL.md` under 100 body lines; move variants to modules.
+- Treat GitHub/ADO/GitLab/Jira branch and policy settings as confirmation-gated mutations; do not apply them without explicit opt-in even with admin credentials.
+- Reference `setup-skills` and `publish-semver` host docs instead of copying their full semantics.
+- Preserve existing GitLab/local support unless a later module explicitly migrates it.
+- Physical-copy is the canonical sync strategy; symlinks and git submodules are not.

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

@@ -0,0 +1,48 @@
+# Init AI Repo Modules
+
+Layer 3 modules keep the canonical `ai-catapult-init` skill lean. These files live under the canonical `ai-catapult-init/` path; `init-ai-repo/` and `ai-sdlc-init/` are deprecated compatibility path/alias shims. Read only the module that matches the current scaffold decision.
+
+| Module | When to read |
+| --- | --- |
+| `foundation.md` | Read when creating the base AI SDLC scaffold: Karpathy guidance, ADRs, `.rules.ts`, prek, sync scripts, and doc markers. |
+| `validation.md` | Read when running scaffold verification, golden fixture checks, or regression tests. |
+| `brd-prd-traceability.md` | Read when adding BRD, PRD, issue/ticket, agent brief, and drift-report backlinks. |
+| `tracker-adapters.md` | Read when choosing GitHub, ADO, GitLab, Jira, or local markdown tracker integration. |
+| `ci-policy.md` | Read when adding GitHub/ADO/GitLab CI and branch-policy/ruleset checklist artifacts. |
+| `host-policy-automation.md` | Read when applying hosted branch/PR/policy mutations to GitHub, ADO, GitLab, or Jira, or when emitting dry-run diffs and confirmation gates. |
+| `archgate.md` | Read when configuring structural `.rules.ts` validation or optional semantic/drift checks. |
+| `language-packs.md` | Read when selecting local/CI checks for TypeScript, Python, Rust, Go, JVM, .NET Core/EF Core, legacy .NET/EF, or polyglot repos. |
+| `readme-documentation.md` | Read when initializing, augmenting, or rewriting `README.md` (template mode for sparse repos, safe augmentation/rewrite for existing). |
+| `release-versioning.md` | Read when initializing release tagging, versioning, or CI/CD release workflows (Hybrid default, SemVer/CalVer variants, GHA/Azure/GitLab templates, tag guardrails). |
+| `topology.md` | Read when the target repo needs a standalone or umbrella topology matrix, depth validation, or `.ai/matrix.json` schema generation. |
+| `documentation-blueprint.md` | Read when generating the v3 canonical `.ai/`, `.memory/`, `docs/architecture`, `docs/specifications`, `docs/learning` trees, and the entry files. |
+| `memory.md` | Read when defining the `.memory/human-override/` and `.memory/self-learned` schemas. |
+| `sync.md` | Read when implementing physical-copy sync, drift detection, backups, or audit logs. |
+| `migration.md` | Read when migrating a target repo from a legacy AI-SDLC scaffold to the v3 layout, or when classifying legacy artifacts. |
+| `phases/README.md` | Read when mapping the four public phases to internal checkpoints. |
+| `phases/01-discover-decide.md` | Read when executing Phase 1 discovery, lane selection, hosted-ticket posture, and OMX/OMC planning surfaces. |
+| `workflow.md` | Read when generating repo workflow docs, workflow/status manifests, entry-surface links, and handoff indexes. |
+| `traceability.md` | Read when generating stable IDs, graph schema, backlink validation, graph fixtures, and cross-skill artifact links. |
+| `cascade.md` | Read when generating multi-repo cascade plans, first-run confirmation gates, idempotent linked updates, host adapter contracts, audits, and reconciliation reports. |
+| `skill-modernization.md` | Read when auditing compact descriptions, progressive disclosure, trigger boundaries, cross-skill links, and AI-SDLC compatibility. |
+
+`workflow.md`, `traceability.md`, `cascade.md`, and `skill-modernization.md` are active phase modules. Fall back to `REFERENCE.md` only for legacy template bodies that have not yet moved into focused modules.
+
+## Module ordering for a fresh v3 scaffold
+
+1. `topology.md` — decide standalone or umbrella, set `max_allowed_depth`.
+2. `documentation-blueprint.md` — generate the v3 tree.
+3. `memory.md` — wire `.memory/` schemas.
+4. `sync.md` — wire physical-copy propagation and drift.
+5. `tracker-adapters.md` + `host-policy-automation.md` — choose tracker and apply path.
+6. `ci-policy.md` — CI workflow and branch-policy checklist.
+7. `language-packs.md` — choose checks.
+8. `validation.md` — verify the scaffold matches the blueprint and golden fixtures.
+9. `foundation.md` + `brd-prd-traceability.md` + `archgate.md` + `migration.md` — supporting modules as needed (migration only when a legacy scaffold is present).
+
+## Phase modules
+
+| Module | Purpose |
+|--------|---------|
+| [`phases/README.md`](phases/README.md) | Four-phase AI-SDLC phase index and original eight-checkpoint mapping. |
+| [`phases/01-discover-decide.md`](phases/01-discover-decide.md) | Phase 1 discovery, lane selection, hosted-ticket posture, and OMX/OMC planning surfaces. |

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

@@ -0,0 +1,42 @@
+# Archgate Module
+
+Read when configuring `.rules.ts` validation, CI governance, or optional semantic/drift checks.
+
+## Default structural check
+
+Structural validation stays fast and default-on:
+
+```sh
+bash scripts/validate-rules.sh .rules.ts
+bash scripts/archgate.sh --mode structural --rules .rules.ts --format json
+```
+
+The structural check verifies that `.rules.ts` exports the required rule domains and remains suitable for local/CI execution.
+
+## JSON contract
+
+`bash scripts/archgate.sh --format json` emits one JSON object:
+
+```json
+{
+  "status": "pass|fail|skipped",
+  "mode": "structural|semantic|drift",
+  "rulesFile": ".rules.ts",
+  "base": "<optional base ref>",
+  "head": "<optional head ref>",
+  "checks": [
+    { "id": "archgate-structural", "status": "pass", "message": "..." }
+  ],
+  "exitCode": 0
+}
+```
+
+## Optional semantic/drift checks
+
+Semantic and drift modes are opt-in. They must not block CI until the repo has project-specific rules and `ARCHGATE_SEMANTIC=1` is deliberately configured.
+
+```sh
+ARCHGATE_SEMANTIC=1 bash scripts/archgate.sh --mode drift --base origin/main --head HEAD --format json
+```
+
+Drift checks compare the PR diff with BRD, PRD, acceptance criteria, relevant ADRs, and `.rules.ts`. Until a project-specific checker exists, the contract returns `skipped` without `ARCHGATE_SEMANTIC=1` and `fail` with it.

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

@@ -0,0 +1,64 @@
+# BRD/PRD Traceability Module
+
+Read when the repo needs a visible path from business need to implementation tickets and drift verification.
+
+## Artifact chain
+
+1. **BRD** — captures business problem, measurable outcome, stakeholders, constraints, risks, and success metrics.
+2. **PRD** — references the BRD, translates business outcomes into user stories, acceptance criteria, implementation decisions, and testing decisions.
+3. **Tickets/issues/work items** — reference both BRD and PRD, slice implementation as tracer bullets, and carry acceptance criteria.
+4. **Agent brief** — references the ticket, PRD, relevant ADRs, Archgate rules, and verification commands.
+5. **Drift report** — checks PR diff against BRD, PRD, acceptance criteria, ADRs, and `.rules.ts`.
+
+## Minimum fields
+
+### BRD
+
+- `BRD ID`
+- `Business problem`
+- `Target users/stakeholders`
+- `Desired outcomes / metrics`
+- `Constraints and non-goals`
+- `Risks and open questions`
+
+### PRD
+
+- `PRD ID`
+- `BRD link`
+- `Problem statement`
+- `Solution`
+- `User stories`
+- `Acceptance criteria`
+- `Implementation decisions`
+- `Testing decisions`
+- Optional `versionImpact` metadata (`major|minor|patch|none`) when the product owner wants an explicit release-impact claim; release tooling must still infer impact from PRD/spec prose when this field is absent.
+- `Out of scope`
+
+### Ticket/work item
+
+- `BRD link`
+- `PRD link`
+- `Parent link`
+- `What to build`
+- `Acceptance criteria`
+- `Version impact` — copy the highest available PRD/spec/ADR signal; do not infer a lower impact from commits when the product spec says otherwise.
+- `Blocked by`
+- `Verification`
+
+## Version-impact signal precedence
+
+Use a **highest-signal-wins** rule whenever release/versioning behavior needs a version-impact decision:
+
+1. Explicit PRD, product spec, acceptance criteria, or ADR compatibility statements.
+2. Ticket/work-item version-impact fields copied from the PRD/spec chain.
+3. Conventional-commit or diff inference.
+4. Operator defaults or unknown impact.
+
+If signals conflict, preserve every signal in the audit record and select the highest-priority source above. Do not downgrade a PRD/spec breaking-change signal because commits look non-breaking.
+
+## Skill handoffs
+
+- `to-prd` consumes a BRD link/ID when present and writes it into the PRD Traceability section.
+- `to-issues` copies BRD and PRD backlinks into every generated ticket/work item.
+- `triage` preserves traceability fields while changing state/labels/tags.
+- `ai-catapult-init` release versioning consumes PRD/spec prose and optional `versionImpact` metadata as auditable inputs; incompatible explicit claims must be recorded for review before tagging.

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

@@ -0,0 +1,110 @@
+# Cascade Module
+
+Read when initializing multiple repositories together or when an umbrella repository must keep parent/child work items, traceability graphs, workflow handoffs, and tracker links in sync. This module owns multi-repo orchestration, idempotency, parent/child linking, reconciliation, and composition of tracker adapters with host-policy safety.
+
+## Generated outputs
+
+| Output | Purpose |
+| --- | --- |
+| `.ai/cascade/cascade-plan.json` | Machine-readable plan for topology discovery, parent/child work items, host adapters, and intended mutations. |
+| `.ai/cascade/audit.jsonl` | Append-only audit of dry-run, blocked, confirmed, apply, readback, and idempotent update events. |
+| `.ai/cascade/reconciliation-report.md` | Human report proving linked items are present, duplicates are absent, and host/local readback matched. |
+| `.ai/cascade/host-adapters/<host>.json` | Mocked adapter contract fixture for GitHub, Azure DevOps, GitLab, Jira, and Local Markdown. |
+
+Workflow and handoff surfaces must link to the cascade plan, audit, and reconciliation report when this branch is available.
+
+## Common cascade workflow
+
+1. **Discover topology** — read `.ai/matrix.json`; standalone repos produce a no-op plan unless the user explicitly selects multiple repos. Umbrella repos read `managed_repositories` and reject paths that violate the topology depth rule.
+2. **Plan links** — create a parent work item for the mother repo and child work items for each managed repo; every child records `parent_id`, `parent_url` or `parent_path`, BRD/PRD links, and traceability node IDs.
+3. **Dry-run mutations** — route hosted changes through `modules/host-policy-automation.md`; local markdown writes remain normal file writes but still appear in the dry-run plan.
+4. **First-run confirmation** — the first externally visible apply requires a confirmation token matching `^ct-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}$`. Without it, hosted adapters must return `apply-blocked-no-confirmation` and must not call mutation endpoints.
+5. **Apply and readback** — apply only the confirmed plan, capture host response IDs/ETags/version numbers, then read back each parent/child link before reporting success.
+6. **Idempotent subsequent update** — after a confirmed cascade scope exists, later runs update the known linked items by stable ID instead of creating duplicates. Unsupported, destructive, or policy-changing mutations still require fresh confirmation.
+7. **Audit and reconcile** — append every dry-run/apply/readback/idempotency event to `.ai/cascade/audit.jsonl`, then write `.ai/cascade/reconciliation-report.md` with duplicate count, missing link count, and readback status.
+
+## Host adapter cascade contract
+
+Each configured host adapter must expose the same logical operations:
+
+- `discover_scope`
+- `plan_parent_item`
+- `plan_child_item`
+- `dry_run`
+- `confirm_first_run`
+- `apply_confirmed_plan`
+- `readback_links`
+- `apply_idempotent_update`
+- `audit_event`
+- `reconcile`
+
+Configured hosts are `github`, `ado`, `gitlab`, `jira`, and `local-markdown`. Hosted adapters delegate externally visible mutation safety to `modules/host-policy-automation.md`; local markdown writes still record audit/readback evidence but do not need confirmation.
+
+## Host adapter JSON schema
+
+Each `.ai/cascade/host-adapters/<host>.json` is a mocked, offline contract fixture — never a live connector and never a credential store. The schema is intentionally small so the idempotency and no-duplicate guarantees are mechanically checkable without a network:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `schema_version` | string | Adapter contract version (`"1.0"`). |
+| `host` | string | One of `github`, `ado`, `gitlab`, `jira`, `local-markdown`. |
+| `host_label` | string | Human label for the tracker surface. |
+| `hosted` | bool | `true` for externally visible hosts; `false` for `local-markdown`. |
+| `adapter_doc` | string | Pointer to the `setup-skills/*` adapter detail doc. |
+| `operations` | string[] | Exactly the 10 logical operations (see below). |
+| `safety` | object | `credentials_stored: false`, `host_policy_mutation: false`, and (for hosted) `first_run_without_confirmation: "blocked"`, `confirmation_token_required: true`, `confirmation_token` matching `^ct-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}$`. |
+| `dry_run` | object | Planned mutation summary (`status`, `would_create_parent`, `would_create_children`). No external call. |
+| `apply` | object | First confirmed apply result (`status`, `parent_key`, `child_keys`). |
+| `second_run` | object | Idempotent re-run result: `status: "updated-existing"`, `duplicates_created: 0`, and a stable `idempotency_key`. |
+| `readback` | object | Required link evidence: `status`, `parent_link_present`, `child_links_present`. |
+| `audit_path` | string | Pointer to `.ai/cascade/audit.jsonl`. |
+
+The `operations` array is exactly these 10 logical ops: `discover_scope`, `plan_parent_item`, `plan_child_item`, `dry_run`, `confirm_first_run`, `apply_confirmed_plan`, `readback_links`, `apply_idempotent_update`, `audit_event`, `reconcile`.
+
+### Stable idempotency key
+
+`second_run.idempotency_key` is the stable key (derived from the cascade `cascade_id`, e.g. `init-ai-repo:<repo-id>:cascade`) that maps the cascade scope to already-created host work items. On any re-run, the adapter resolves the existing child by this key and **updates it in place** (`status: "updated-existing"`) instead of creating a duplicate; `duplicates_created` stays `0`. This is the contract that makes the no-duplicate-child guarantee testable offline (see `tests/cascade-host-adapter-schema_test.sh`, which runs a mocked adapter twice and asserts a single child).
+
+### No credentials
+
+Adapter fixtures must never contain API tokens, access/refresh tokens, OAuth secrets, bearer headers, passwords, or any `authorization:` material. Credential handling is owned by `setup-skills` configuration and `modules/host-policy-automation.md`, never serialized into cascade artifacts.
+
+```json
+{
+  "schema_version": "1.0",
+  "host": "github",
+  "hosted": true,
+  "operations": [
+    "discover_scope", "plan_parent_item", "plan_child_item", "dry_run",
+    "confirm_first_run", "apply_confirmed_plan", "readback_links",
+    "apply_idempotent_update", "audit_event", "reconcile"
+  ],
+  "safety": {
+    "first_run_without_confirmation": "blocked",
+    "confirmation_token_required": true,
+    "confirmation_token": "ct-2026-06-27-001",
+    "credentials_stored": false,
+    "host_policy_mutation": false
+  },
+  "apply": { "status": "created-or-linked", "parent_key": "GH-101", "child_keys": ["GH-102"] },
+  "second_run": { "status": "updated-existing", "duplicates_created": 0, "idempotency_key": "init-ai-repo:umbrella-root:cascade" },
+  "readback": { "status": "match", "parent_link_present": true, "child_links_present": true }
+}
+```
+
+## Safety rules
+
+- Never auto-create hosted parent/child items on the first run without an explicit confirmation token.
+- Never create duplicate child work items when a stable `cascade_id` or traceability node already maps to a host item.
+- Never store credentials, API tokens, OAuth refresh tokens, or secret headers in cascade plans, host adapter fixtures, audit logs, or reconciliation reports.
+- Never downgrade missing readback to success; if readback cannot prove parent/child links, reconciliation status is `fail` or `blocked`.
+- Never mutate host branch, project, workflow, permission, or approval policy from cascade; those changes remain owned by `host-policy-automation.md` and require their own confirmation.
+
+## Cross-skill contracts
+
+- `ai-catapult-init` creates the cascade plan, links it from workflow/handoff, and validates no duplicates.
+- `setup-skills` supplies host adapter operation details for GitHub, Azure DevOps, GitLab, Jira, and Local Markdown.
+- `to-issues` creates or updates child work items using the cascade stable IDs instead of free-form duplicates.
+- `triage` preserves parent/child backlinks when issue state changes.
+- `to-prd` and `brd-prd-traceability.md` provide BRD/PRD links for parent and child items.
+- `traceability.md` records parent/child host URLs or local paths as graph nodes and edges.

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

@@ -0,0 +1,107 @@
+# CI and Branch Policy Module
+
+Read when adding CI files or branch-policy/ruleset checklist artifacts. This module is scaffold guidance, not hosted-policy automation.
+
+## Official docs anchors
+
+- GitHub rulesets: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets
+- GitHub branch protection: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches
+- Azure Repos branch policies: https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies-overview?view=azure-devops
+- Azure Repos policy settings and build validation: https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops
+- Azure Pipelines triggers: https://learn.microsoft.com/en-us/azure/devops/pipelines/build/triggers?view=azure-devops
+
+## Safety boundary
+
+By default, write checklist artifacts into the repo. Do not call GitHub or Azure DevOps APIs/CLIs that mutate branch rules, rulesets, or policies unless the user explicitly requests it and confirms admin credentials/permissions.
+
+Every initialized implementation assumes protected `main` and PR-only delivery. The scaffold may emit provider-specific checklists/config templates for branch rules, but hosted policy mutation remains opt-in and explicit.
+
+## GitHub path
+
+### CI scaffold
+
+- Write `.github/workflows/ci-prek.yml` as a separate workflow.
+- Keep existing `.github/workflows/ci.yml` intact.
+- Include the `validate-rules` prek hook and any detected language-pack checks.
+
+### Branch ruleset/protection checklist
+
+Create `docs/agents/branch-policy-github.md` with:
+
+- Default branch target, usually `main` or `dev`.
+- Required PR before merge.
+- Protected `main` ruleset/protection intent; direct pushes are disallowed.
+- Required status checks, including the AI SDLC prek workflow.
+- Required review count and stale-review dismissal policy.
+- Whether administrators may self-approve PRs through admin approve/admin bypass, and the local policy rationale when allowed; this is valid only when the host/runtime explicitly supports admin approval for the same actor. GitHub hosted PR review rejects same-actor approval, so GitHub requires a distinct admin reviewer or explicit admin bypass/admin merge with actor, authority, reason, checks, and approval mode recorded.
+- Optional linear history, signed commits, merge queue, or deployment requirements.
+- Ruleset/protection owner and whether enforcement is active, evaluate-only, or checklist-only.
+- Links to the official GitHub rulesets and branch protection docs above.
+
+### PR merge gate
+
+For any PR workflow or branch-policy checklist created by this skill, state that merge is allowed only when all of these are true:
+
+- **Architect** agrees the PR still matches ADRs, module boundaries, branch policy, and acceptance criteria.
+- **Reviewer** agrees code quality, safety, documentation, and drift checks have no blocking findings.
+- **Executor** agrees the requested change is complete, cleanup is done, and required checks are green.
+- All actionable PR comments are resolved.
+- Eval coverage: structurally valid eval declaration required. A skill changed in the PR diff that declares an `eval:` key (a shippable capability) must reference a structurally valid evalset — an `.ai/evals/<set>/` directory with `evalset.json`, `rubric.md`, and `judge-config.json`, each parsing and well-formed. Doc-only or unchanged skills are exempt, and an audited-exception token in `.ai/evals/coverage-exceptions.json` (owner, reason, expiry) bypasses the gate for non-shippable changes. This check is offline and deterministic: eval coverage is enforced structurally in CI; eval quality is verified via an out-of-band LM-judge run, never by a model or network call in CI. See `modules/evals.md`.
+- Observability audit: the generated `.ai/observability/audit-checklist.md` token-cost and trajectory-audit checklist has been reviewed for any PR that changes agent behavior. This check is offline and deterministic: the checklist is a generated convention; token-cost and trajectory metering run out-of-band, never as a model or network call in CI. See `modules/documentation-blueprint.md` and ADR-0005.
+- AI-failure-mode review: for any PR containing AI-generated or AI-assisted code, the generated `.ai/reviews/ai-failure-modes.md` checklist has been worked through — hallucinated dependencies, slopsquatting, inadequate error handling, and "looks-right" / subtle correctness gaps. This check is offline and deterministic: the checklist is a generated review convention, not a live CI gate. See `modules/documentation-blueprint.md` (spec §4.B).
+- Local CI and host SCM CI (GitHub Actions, Azure Pipelines, or GitLab CI as applicable) are green.
+- The architect, reviewer, and executor loop reaches explicit agreement. If any role disagrees, comments remain actionable, or checks are not green, do not merge.
+- Auto-merge may be enabled only after actionable comments are resolved, local CI and host SCM CI are green, the architect/reviewer/executor loop agrees, and branch policy permits merge.
+
+## Azure DevOps path
+
+### CI scaffold
+
+Write `azure-pipelines.yml` only when ADO Pipelines is selected:
+
+```yaml
+trigger:
+  branches:
+    include:
+      - main
+
+pr:
+  branches:
+    include:
+      - main
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - checkout: self
+  - script: bash scripts/validate-rules.sh .rules.ts
+    displayName: Validate Archgate rules
+```
+
+### Branch policy/build-validation checklist
+
+Create `docs/agents/branch-policy-ado.md` with:
+
+- Project, repository, and protected branch target.
+- Minimum reviewer count.
+- Linked work-item requirement when desired.
+- Comment resolution requirement.
+- Build validation policy referencing the selected pipeline.
+- Required status/check naming convention.
+- Whether administrators may self-approve PRs through admin approve/admin bypass, and the local policy rationale when allowed; this is valid only when the host/runtime explicitly supports admin approval for the same actor and the merge record captures actor, authority, reason, checks, and approval mode.
+- Distinction between YAML `pr` triggers and Azure Repos branch-policy build validation.
+- Links to the official Microsoft branch policy and pipeline trigger docs above.
+
+## GitLab/local path
+
+Keep existing GitLab/local tracker support. If GitLab CI or local-only checks are selected, write a checklist that mirrors the same intent: protected main/default branch, PR/MR-only delivery, required review, required checks, comment resolution, traceability, and explicit owner.
+
+## Validation CI vs release CI
+
+The `ai-catapult-init` scaffold produces two distinct CI flows. They must be kept separate:
+
+- **Validation CI** (`.github/workflows/ci-prek.yml` and equivalents for Azure Pipelines and GitLab CI) — runs on every push and PR. Owns prek hooks, Archgate structural checks, language-pack checks, golden verification, and lint/typecheck/test. Status checks from validation CI gate PR merges.
+- **Release CI** (`modules/release-versioning.md` provider templates) — runs on push to `main`, on tag push, and via `workflow_dispatch`. Owns the release/versioning strategy, the `release.json` manifest, the tag guardrails, and the optional publish step. Status checks from release CI gate tag creation, not PR merges.
+
+A common mistake is to fold release logic into validation CI (e.g. running semantic-release on every push). This module explicitly rejects that pattern. Release CI must not run on PRs, and validation CI must not produce tags or push to registries.