@r3dlex/ai-catapult 0.1.0

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

@@ -0,0 +1,102 @@
+# Memory Layer Module
+
+Read when defining the `.memory/human-override/` and `.memory/self-learned/` schemas for a target repo. The memory layer is local machine-readable knowledge scoped to the repo. Human override is terminal priority and must never be silently rewritten.
+
+## Two layers
+
+| Layer | Path | Authority | Sync | Edit policy |
+| --- | --- | --- | --- | --- |
+| Human override | `.memory/human-override/` | Humans, terminal priority | Never propagated | Append-only by default; never silently rewritten |
+| Self-learned | `.memory/self-learned/` | Agents, local | Per-repo only, never propagated | Append-only with `schema_version`; changelog required |
+
+Both layers are local to the repo. Neither is pushed upstream and neither is inherited by managed sub-repos.
+
+## `.memory/human-override/`
+
+Holds human-authored content that the AI SDLC must respect. The directory is terminal priority: the scaffold never overwrites an existing file in this directory and never deletes a file without explicit confirmation.
+
+Default files:
+
+- `custom-conventions.md` — repo-specific naming, formatting, or commit conventions that override generic defaults.
+- `tribal-knowledge.md` — undocumented but load-bearing facts about the repo, the team, or the build environment.
+
+### Schema rules
+
+- Plain Markdown; frontmatter is optional and only used for `id`, `last_reviewed`, and `owner` fields when present.
+- Files are immutable from the agent's perspective unless the user explicitly asks to edit them.
+- The validator must verify that any generated scaffold that would touch this directory emits a `present-not-overwritten` audit entry and skips the write.
+
+## `.memory/self-learned/`
+
+Holds machine-readable knowledge produced by the scaffold, the validator, or runtime agents. The directory is per-repo only and never propagated.
+
+Default files:
+
+- `error-patterns.json` — recurring error patterns and their fix hints.
+- `module-complexity.json` — module-level complexity and coverage data.
+- `CHANGELOG.md` — chronological list of schema or file changes.
+
+### `error-patterns.json` schema (v1.0)
+
+```json
+{
+  "schema_version": "1.0",
+  "entries": [
+    {
+      "id": "ep-2026-001",
+      "pattern": "ModuleNotFoundError: No module named 'foo'",
+      "context": "Python module resolution failure after a refactor",
+      "detection": "ImportError raised in CI step 'unit-tests'",
+      "fix_hint": "Add 'foo' to pyproject.toml dependencies or pin via uv.lock",
+      "first_seen_at": "2026-05-12T00:00:00Z",
+      "last_seen_at": "2026-06-01T00:00:00Z",
+      "occurrences": 3,
+      "owner": "platform"
+    }
+  ]
+}
+```
+
+### `module-complexity.json` schema (v1.0)
+
+```json
+{
+  "schema_version": "1.0",
+  "entries": [
+    {
+      "path": "src/foo.py",
+      "language": "python",
+      "lines_of_code": 412,
+      "cyclomatic_complexity": 18,
+      "test_coverage": 0.62,
+      "owner": "team-foo",
+      "last_measured_at": "2026-06-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+### Schema rules
+
+- Every self-learned file must declare `schema_version`. Bumping the version requires an entry in `CHANGELOG.md` and a migration note.
+- `CHANGELOG.md` is the canonical change log; do not scatter date markers across individual files.
+- Self-learned files are append-only. New entries are added; existing entries are not edited in place. If a fact becomes wrong, add a new entry with `superseded_by` pointing to the corrective entry.
+- The validator must check that any new self-learned file declares `schema_version` and that the version is supported by the scaffold.
+
+## Privacy and external integration
+
+- The memory layer is local-only. The scaffold never uploads `.memory/` to a remote system.
+- Any external integration (telemetry, dashboards) requires explicit confirmation and an opt-in flag in `.ai/matrix.json` under `memory.external_integration`.
+- `.memory/human-override/` content is never included in external uploads even when integration is enabled.
+- Credentials, secrets, and tokens are never stored in `.memory/`. The validator must reject writes that match credential patterns.
+
+## Migration
+
+When a target repo already has a `.memory/` directory under a different layout, the migration path is:
+
+1. Classify each existing file as `human-override` or `self-learned` based on the migration rules in `modules/migration.md`.
+2. Move or copy the file to the v3 path with a backup under `.ai/drift/backups/<timestamp>/`.
+3. Emit a `present-not-overwritten` audit entry for any file that already exists in the v3 path.
+4. Append a `CHANGELOG.md` entry describing the migration.
+
+Destructive moves (delete-then-copy) require explicit confirmation. Copy-with-keep is the default.

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

@@ -0,0 +1,107 @@
+# Migration Module
+
+Read when migrating a target repo from a legacy AI-SDLC scaffold to the v3 layout, or when classifying legacy artifacts. Migration is a one-time operation that must never silently delete user content.
+
+## Action vocabulary
+
+Each legacy artifact is classified into exactly one of the following actions:
+
+| Action | Meaning | Destructive? |
+| --- | --- | --- |
+| `migrate` | Move the artifact to its v3 path; the source path is removed only after the move is verified. | Yes (removes the source path). |
+| `copy` | Copy the artifact to its v3 path; the source path is left in place and marked deprecated in the migration manifest. | No (keeps the source path). |
+| `deprecate` | Mark the artifact as deprecated at its existing path; do not move or copy. Add a "Deprecated by v3" header pointing to the v3 path. | No. |
+| `supersede` | Replace the artifact at its existing path with a v3 pointer file that references the new location. The original content lives at the v3 path. | No (the pointer is content-preserving). |
+
+`migrate` is the only destructive action. The other three are content-preserving. Destructive actions require explicit confirmation per the rules below.
+
+## Legacy-to-v3 map
+
+| Legacy path | v3 path | Default action | Confirmation? |
+| --- | --- | --- | --- |
+| `.agents/skills/<name>/SKILL.md` (role) | `.ai/system-prompts/<role>.md` | `copy` (default) or `migrate` (when `--destructive` is set) | Only for `migrate`. |
+| `.agents/skills/<name>/REFERENCE.md` (role) | `docs/learning/concept-maps/<name>.md` or `docs/architecture/<...>.md` (depending on content) | `copy` (default) or `migrate` (when `--destructive` is set) | Only for `migrate`. |
+| `.agents/skills/<name>/` (whole directory) | (none — directory contents are split per file) | `supersede` (replace with pointer file at the directory level) | No. |
+| `.rules.ts` | `.ai/rules/technical-bounds.md` (Markdown summary) and `docs/architecture/adr/0001-init.md` (decision record) | `copy` (default) or `migrate` (when `--destructive` is set) | Only for `migrate`. |
+| `docs/adr/<file>.md` | `docs/architecture/adr/<file>.md` | `copy` (default) or `migrate` (when `--destructive` is set) | Only for `migrate`. |
+| AI SDLC marker block in `AGENTS.md` / `CLAUDE.md` / `README.md` | `AGENTS.md` / `CLAUDE.md` / `CONTRIBUTING.md` / `README.md` (entry files) | `supersede` (rewrite the block in v3 form; preserve human prose) | No. |
+| `upstream.lock` | `upstream.lock` (top-level, unchanged) | `deprecate` (add a comment-only header if needed) | No. |
+| `prek.toml` | `prek.toml` (top-level, unchanged) | `deprecate` (add a comment-only header if needed) | No. |
+| `.github/workflows/ci-prek.yml` | `.github/workflows/ci-prek.yml` (unchanged) | `deprecate` (add a comment-only header if needed) | No. |
+| `scripts/archgate.sh`, `scripts/validate-rules.sh`, `scripts/sync-upstream.sh` | (unchanged) | `deprecate` (add a comment-only header if needed) | No. |
+| `.memory/` (any pre-existing content) | `.memory/human-override/` or `.memory/self-learned/` based on classification | `migrate` per file, with `present-not-overwritten` audit when the v3 path already exists | Only for `migrate`. |
+| Legacy marker block `<!-- ai-sdlc-init:start --> ... <!-- ai-sdlc-init:end -->` | (rewrite in v3 form, preserving human prose) | `supersede` | No. |
+| `setup-skills`, `publish-semver` (and other reference-only) legacy references | (unchanged; reference-only) | `deprecate` (add a comment-only header if needed) | No. |
+| `graphify-out` and other deprecated references | (removed by owner-driven PR) | `supersede` (add a `Deprecated by v3` header) | No. |
+
+## Destructive confirmation rule
+
+A `migrate` action is destructive. The migration path requires an explicit confirmation that:
+
+1. Names the legacy path being migrated.
+2. Names the v3 destination path.
+3. Asserts that a backup has been written under `.ai/drift/backups/<timestamp>/` for the legacy path.
+4. Captures a confirmation token tied to the run.
+
+A confirmation token is valid only for the run that produced it. Retrying the same migration plan after a failure requires a fresh confirmation.
+
+## Migration manifest
+
+The migration path writes a manifest to `.ai/drift/migration-manifest.json` with this shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "2026-06-07T00:00:00Z",
+  "actor": "init-ai-repo",
+  "umbrella_root": ".",
+  "actions": [
+    {
+      "source_path": ".agents/skills/karpathy-guidelines/SKILL.md",
+      "destination_path": ".ai/system-prompts/architect.md",
+      "action": "copy",
+      "destructive": false,
+      "confirmation_token": null,
+      "status": "completed"
+    },
+    {
+      "source_path": ".rules.ts",
+      "destination_path": ".ai/rules/technical-bounds.md",
+      "action": "migrate",
+      "destructive": true,
+      "confirmation_token": "ct-2026-06-07-001",
+      "status": "completed",
+      "backup_path": ".ai/drift/backups/2026-06-07T00-00-00Z/.rules.ts"
+    }
+  ],
+  "summary": {
+    "copy": 5,
+    "migrate": 1,
+    "deprecate": 3,
+    "supersede": 2,
+    "skipped": 0,
+    "failed": 0
+  }
+}
+```
+
+`status` is one of `pending`, `in_progress`, `completed`, `failed`, or `skipped`. A `failed` action is rolled back from the backup when one exists; the manifest records the rollback outcome under `rollback`.
+
+## Audit trail
+
+Every migration run appends one JSON object per line to `.ai/drift/migration-audit.jsonl`. The shape mirrors the host-policy audit format in `modules/host-policy-automation.md`, with fields `ts`, `actor`, `mode` (`apply` or `dry-run`), `confirmation_token`, `manifest_sha256`, and a per-action results list.
+
+## Idempotency
+
+Re-running the migration against a target that already has v3 paths is a no-op. The validator emits a `present-not-overwritten` audit entry for any v3 path that already exists and skips the write. The migration manifest is regenerated with `status: skipped` for the affected actions.
+
+## Rollback
+
+A full migration run can be rolled back from `.ai/drift/migration-manifest.json` plus `.ai/drift/backups/<timestamp>/` when the destructive actions are limited to `migrate`. `deprecate` and `supersede` are content-preserving and do not need rollback. `copy` does not remove the source path, so rollback is also unnecessary.
+
+## Safety rules
+
+- The migration path never deletes a file that is not classified `migrate`.
+- The migration path never deletes a file outside the action vocabulary above. There is no `--unsafe-destinations` flag; the migration manifest is the only allowed bypass, and a `migrate` action on a path outside the legacy map requires both the action to be added to the manifest under `exceptions` and a fresh confirmation token.
+- The migration path never writes into `.memory/human-override/` if the file already exists. The path is `present-not-overwritten` and the migration skips the write.
+- The migration path is always confirmation-gated for `migrate` actions. There is no `auto-apply` mode.

package/dist/claude-plugin/skills/ai-catapult-init/modules/phases/01-discover-decide.md

@@ -0,0 +1,33 @@
+# Phase 1 — Discover & Decide
+
+## Purpose
+
+Discover the repository's real current state and choose the smallest safe AI-SDLC adoption lane before generating governance or implementation artifacts. This phase is intentionally read-mostly and should be safe to rerun.
+
+## Inputs
+
+- Repository metadata, remotes, branch state, existing CI, package manifests, and language/runtime conventions.
+- Existing `.ai/`, `.memory/`, `AGENTS.md`, `RULES.md`, `PLANS.md`, `CONTRIBUTING.md`, specs, ADRs, and issue tracker configuration.
+- User-selected posture for hosted tickets versus local fallback.
+
+## Outputs
+
+- `.ai/matrix.json`
+- `.ai/init/repo-profile.json`
+- `.ai/init/sdlc-path.md`
+- `.ai/phases/01-discover-decide/README.md` or equivalent phase notes
+
+## Command surfaces
+
+- OMX: `$deep-interview` for ambiguity, `$plan` for straightforward planning, `$ralplan` for consensus planning.
+- OMC: equivalent aliases/commands should call into the same generated artifact contract and must not duplicate semantics.
+
+## Gates
+
+- Do not begin coding until the lane, source of truth, and required planning artifacts are known.
+- If a hosted tracker is configured and authorized, issue/ticket discovery is fail-closed.
+- If hosted tracking is unavailable, local fallback is allowed before coding, but it must be reconciled before final PR merge.
+
+## Idempotence
+
+Reruns update generated discovery files non-destructively and preserve human-owned notes outside managed blocks.

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

@@ -0,0 +1,33 @@
+# ai-catapult-init Phase Modules
+
+The canonical `ai-catapult-init` workflow exposes four optimized phases so agents and humans can move quickly while still preserving traceability. Each phase writes durable state under `.ai/phases/<phase>/` and links command output back to specs, plans, and validation evidence.
+
+## Four optimized phases
+
+| Phase | Name | Primary outputs |
+|-------|------|-----------------|
+| 1 | Discover & Decide | `.ai/matrix.json`, `.ai/init/repo-profile.json`, `.ai/init/sdlc-path.md`, `.ai/phases/01-discover-decide/` |
+| 2 | Govern & Plan | `AGENTS.md`, `RULES.md`, `PLANS.md`, `CONTRIBUTING.md`, specs, ADRs, `.ai/work-intake/`, `.ai/plans/`, `.ai/phases/02-govern-plan/` |
+| 3 | Configure & Generate | `.ai/bin/`, `.ai/policies/`, `.ai/commands/omx/`, `.ai/commands/omc/`, `.ai/language-packs/`, `.ai/phases/03-configure-generate/` |
+| 4 | Validate & Handoff | `.ai/validation/report.md`, `.ai/drift/migration-manifest.json`, `.ai/handoff/init-ai-repo-handoff.md`, `.ai/phases/04-validate-handoff/` |
+
+## Eight internal checkpoints
+
+The old eight-step model remains as internal checkpoint metadata, not as the public workflow surface:
+
+1. Detect repo state → Phase 1
+2. Choose SDLC path → Phase 1
+3. Scaffold foundation → Phase 2
+4. Scaffold work intake → Phase 2
+5. Configure host adapters → Phase 3
+6. Configure CI and policy → Phase 3
+7. Select language packs → Phase 3
+8. Validate and emit handoff → Phase 4
+
+## Command-surface schema
+
+Phase 3 generates `.ai/commands/omx/` and `.ai/commands/omc/` entries. The
+shared command-surface schema (fields, `.json` extension, and the omx `$name`
+vs omc `/oh-my-claudecode:name` invocation forms) is defined once in
+[`northstar/modules/command-surface.md`](../../../northstar/modules/command-surface.md);
+this generator and the catalog skills emit identical shapes.

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

@@ -0,0 +1,120 @@
+# README Documentation Module
+
+Read when initializing, augmenting, or rewriting a repo's `README.md` so the result is user-focused GitHub documentation rather than an internal governance dump. The module applies a both-by-mode strategy: a full template for new or sparse repos, and a safe augmentation/rewrite for existing READMEs.
+
+## Both-by-mode
+
+| Mode | Trigger | Behavior |
+| --- | --- | --- |
+| Template | Repo is new, empty, or the existing `README.md` is sparse/stub. | Generate a full GitHub-style README from the section catalogue below. |
+| Augmentation | Repo already has a meaningful `README.md` (one or more populated sections matching the catalogue). | Preserve project-specific facts, augment gaps with template sections, never overwrite existing content without backup/audit. |
+
+Sparseness classification MUST run before any write. Do not pick a mode from vibes.
+
+## Sparse-vs-existing classification
+
+Classify the existing `README.md` as **sparse** if any of the following are true, otherwise treat it as **existing**:
+
+- File does not exist, or
+- File size is below the size threshold (default 600 bytes), or
+- File contains only a top-level heading plus a placeholder line (e.g. `# project-name`, `WIP`, `TBD`, `Coming soon`, `TODO: write README`), or
+- File lacks every required template section listed below (after case-insensitive heading match).
+
+Classify as **existing** if it has at least one of: real quick start code block, real feature list, real installation instructions, real usage example, real project description beyond a placeholder.
+
+## Required template sections (template mode)
+
+A full template README contains, in order:
+
+1. **Hero / title / tagline** — repo name, one-sentence value proposition, optional one-line audience.
+2. **Real applicable badges** — license, build/CI, release/version, package registry, code coverage, downloads/stars when public and applicable. Badges must come from real host/package/license data; never invent.
+3. **Quick start** — install, configure, run the first success path. Keep it copy-paste runnable.
+4. **Requirements** — runtime, language, OS, network or credentials needed.
+5. **Setup and first success path** — minimum steps to verify a working install.
+6. **Update path** — how to upgrade, migrate, or pull latest without losing state.
+7. **Why / who / features / workflows / mental model** — explain the problem, audience, key features, and how the pieces fit.
+8. **Community** — maintainers, contributors, code of conduct, contributing link, support channels.
+9. **License / support** — license file link, support policy, sponsorship or commercial support if applicable.
+10. **Real star history (when applicable)** — link to public star history (e.g. star-history.com) only when the repo is public and the link resolves; do not fabricate.
+11. **Concise AI-SDLC governance block** — one short block linking to `AGENTS.md`, `CONTRIBUTING.md`, ADRs, and the BRD/PRD traceability chain. Do not dump the entire governance payload into the README.
+
+Sections 1, 3, 7, 8, 9, and 11 are mandatory in template mode. Sections 2, 4, 5, 6, and 10 are mandatory when their prerequisites are met (e.g. real star history only when public).
+
+## Augmentation behavior (existing mode)
+
+- Run a backup step before any rewrite. See "Backup and audit manifest" below.
+- Preserve every existing section verbatim unless the user explicitly asks for reorganization.
+- Detect missing catalogue sections and append them in the right order, separated by horizontal rules, without disturbing existing content.
+- Detect duplicate or near-duplicate sections (e.g. two installation blocks); consolidate by adding a pointer to the canonical section, but do not delete user content without an explicit confirmation step.
+- Reject augmentation when the existing README contains private/internal markers unless the host is private; surface a confirmation prompt before any rewrite.
+
+## Real proof-signal gating
+
+A proof signal is any badge, count, link, or claim that depends on external state (host stars, package downloads, license file, build status, release version). All proof signals MUST satisfy these rules:
+
+- **Real data only.** Pull badges and counts from real, currently resolving sources. Reject hardcoded badge URLs, fake star counts, fabricated downloads, or invented release versions.
+- **Public-only leakage guard.** Star history, downloads, public contributors, and social links appear only when the repo is public. Private/internal repos get a neutral version badge at most.
+- **License accuracy.** The license badge must match the actual `LICENSE` file in the repo. Do not assume a default.
+- **No marketing tone for internal or library-only repos.** Internal tooling and small libraries get accurate, restrained documentation; no "blazing fast", "production ready", or other unverified adjectives.
+- **Validation.** Tests MUST reject invented claims, fake badges, fake star history, and any private/internal marker that leaks into a public README.
+
+## Public/private host awareness
+
+- Detect host visibility from the host API or explicit user input. Default to private if the host cannot be reached.
+- Public repos: full template, real star history, public contributors, social links allowed.
+- Private/internal repos: suppress star history, downloads counts, public contributor lists, and any social proof; keep license, build, and version badges only when real and applicable.
+- Non-GitHub hosts: gracefully degrade. Use the host's own badge/CI mechanisms or omit the section with a comment that the host does not provide it.
+
+## Backup and audit manifest
+
+Before any augmentation or rewrite:
+
+1. Copy the existing `README.md` (and any related doc snippets) to a timestamped backup path. Default pattern: `.ai/drift/readme-backups/README-<ISO8601-timestamp>.bak`.
+2. Emit an audit manifest at `.ai/drift/readme-backups/audit-<ISO8601-timestamp>.json` with:
+   - Source path, source SHA, byte size, line count, section heading list.
+   - Detected mode (template or augmentation), reason.
+   - Planned additions (section title, intended content summary).
+   - Planned modifications (section title, before/after summary).
+   - Planned deletions (none in v1; the augmenter never deletes without explicit confirmation).
+   - Operator-visible confirmation prompt and the user's response.
+3. Refuse to write when the audit manifest is missing or when the source SHA changed between backup and write.
+4. Tests MUST assert that a backup path and audit manifest both exist for every augmentation/rewrite and that the audit manifest's section list matches the actual pre-write README.
+
+## Concise AI-SDLC governance block
+
+Append a short, link-only block at the end of the README. The block must:
+
+- Link to `AGENTS.md` (or `CLAUDE.md` when only that exists), `CONTRIBUTING.md`, `docs/architecture/adr/`, and any BRD/PRD traceability doc that exists.
+- Stay under 10 lines.
+- Use neutral wording: "This repository follows the AI-SDLC methodology. See [AGENTS.md] for the operating contract, [docs/architecture/adr/] for architectural decisions, and [BRD/PRD] for traceability."
+- Never inline `.rules.ts`, ADR bodies, BRD/PRD bodies, or full governance payloads.
+
+## Safety rules
+
+- Truth preservation. No invented claims, fake badges, fake star history, fake contributor counts, or private/internal leakage.
+- Backup before rewrite. Augmentation and template-over-existing flows MUST produce a backup and audit manifest before any write.
+- Idempotent marker writes. The AI-SDLC block is keyed on a marker comment; do not duplicate when the marker is already present.
+- Do not delete user content. The augmenter never removes user-written content without explicit confirmation. The pointer/merge strategy above is the default.
+- Validation runs after every write. The `validation.md` module's `tests/test-skills.sh` and `scripts/verify-golden-dir.sh` commands must pass for the affected fixtures.
+
+## Verification commands
+
+Run from `skills/` after touching the module, the module map, the SKILL, or the README fixtures:
+
+```sh
+tests/test-skills.sh
+tests/test-scripts.sh
+tests/run-tests.sh
+bash scripts/archgate.sh --mode structural --rules .rules.ts --format json
+./scripts/verify-golden-dir.sh . reference/golden-root
+./scripts/verify-golden-dir.sh . reference/golden-skills
+```
+
+The README-specific golden fixtures live under `reference/fixtures/readme/` and cover:
+
+- `sparse-repo/` — empty repo triggers template mode.
+- `existing-repo/` — populated README triggers augmentation mode.
+- `private-repo/` — host visibility is private, public proof signals are suppressed.
+- `fake-badges/` — invented claims and fake badges are rejected.
+- `private-leak/` — private/internal markers are rejected in public READMEs.
+- `fact-retention/` — augmentation preserves project-specific facts and emits a backup/audit manifest.

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

@@ -0,0 +1,188 @@
+# Release Versioning Module
+
+Read when initializing, configuring, or auditing a repo's release tagging, versioning, and CI/CD release workflows. This module covers strategy selection (Hybrid default, with SemVer and CalVer variants), provider-specific release workflows (GitHub Actions, Azure Pipelines, GitLab CI), tag guardrails, and the release metadata manifest. It is scaffold guidance only; the CI/CD release workflows it emits assume protected main and PR-only delivery, default to active-on-main after PR merge, and keep tag creation guardrail-gated. **No production deploys or history rewrites** are included in the first pass.
+
+## Strategy selection
+
+The default strategy is **Hybrid**: a semantic base (SemVer-derived or CalVer-derived) plus a timestamp/trace metadata envelope recorded in a release manifest. Pure SemVer and pure CalVer are still supported strategy variants. Every strategy records a `version_impact` audit decision inferred from trusted sources before tag creation is considered.
+
+| Strategy | When to read |
+| --- | --- |
+| **Hybrid (default)** | Use for AI-assisted delivery where every release needs an auditable trace to the source commit, CI run, and tag-creation decision. |
+| **SemVer** | Use when the project follows strict semantic versioning with conventional commits and a single source of truth for breaking-change signaling. |
+| **CalVer** | Use when the project is date-driven and version communicates release cadence rather than compatibility. |
+
+The strategy selector writes a `release.json` manifest at the repo root (or `.ai/release.json` if the project prefers hidden). The manifest is the audit anchor; the tag is derived from the manifest strategy and the version-impact decision is recorded alongside the guardrails.
+
+## Version-impact decision rule
+
+When BRD/PRD, product spec, acceptance criteria, ADRs, tickets, commits, or operator input disagree about release impact, use **highest-signal-wins**:
+
+1. Explicit PRD/spec/acceptance-criteria/ADR compatibility statements.
+2. Ticket or work-item `Version impact` fields copied from the PRD/spec chain.
+3. Conventional-commit or diff inference.
+4. Operator defaults or unknown impact.
+
+Record the selected signal and rationale in the manifest audit fields. Never downgrade a PRD/spec breaking-change signal because commit messages look non-breaking.
+
+## Release manifest (`release.json`)
+
+A complete release manifest contains, at minimum:
+
+```json
+{
+  "schema_version": "1.0",
+  "strategy": "hybrid|semver|calver",
+  "tag": "v1.4.0+2026.06.08.trace-7f3a",
+  "base_version": "1.4.0",
+  "base_sha": "<full 40-char git SHA>",
+  "timestamp_utc": "2026-06-08T12:34:56Z",
+  "trace_id": "<CI run id or local UUIDv4>",
+  "provider": "github-actions|azure-pipelines|gitlab-ci",
+  "delivery_policy": {
+    "protected_main": "required",
+    "pr_before_main": "required",
+    "pr_review_loop": "required",
+    "actionable_comments_resolved": "required",
+    "local_ci": "required",
+    "host_ci": "required",
+    "provider_policy_mutation": "checklist_only"
+  },
+  "guardrails": {
+    "green_ci": "pass|fail|skipped",
+    "conventional_commits": "pass|fail|skipped",
+    "secrets_permissions_preflight": "pass|fail|skipped",
+    "no_dirty_generated_state": "pass|fail|skipped",
+    "protected_tag_policy": "pass|fail|skipped"
+  },
+  "guardrail_reasons": {
+    "<key>": "<one-line explanation on fail; empty on pass>"
+  },
+  "tag_creation": "blocked|allowed",
+  "tag_creation_reason": "<one-line explanation>"
+}
+```
+
+For Hybrid, the tag format is `<base>+<utc-date>.<trace-token>`. For SemVer, the tag format is `v<MAJOR>.<MINOR>.<PATCH>`. For CalVer, the tag format is `v<YYYY>.<MM>.<DD>` or `v<YYYY>.<0X>` depending on cadence.
+
+The manifest is the only authoritative record. Tag creation is a derived provider-API action that happens only when every guardrail is `pass` or `skipped`, `tag_creation` is `allowed`, protected main is in force, the change reached main through a PR, the architect/reviewer/executor review loop resolved actionable comments, and local CI plus host CI are green. Provider branch/ruleset/tag policy mutation remains checklist-only unless the user explicitly authorizes an admin action.
+
+## Version-impact source matrix
+
+Automatic inference is allowed and expected: explicit `versionImpact` metadata in a PRD/spec is optional, not required. The selector records every source it can inspect and chooses the highest trusted signal using this precedence: `major > minor > patch > none`.
+
+| Source | Major signal | Minor signal | Patch signal | None signal |
+| --- | --- | --- | --- | --- |
+| PRD/spec prose | breaking change, incompatible behavior, required migration, removed public API | new user-visible capability or feature | bug fix, regression fix, compatibility fix | docs-only, no release impact |
+| Optional explicit metadata | `versionImpact: major` | `versionImpact: minor` | `versionImpact: patch` | `versionImpact: none` |
+| Conventional commits | `BREAKING CHANGE:` footer or `type!:` marker | `feat:` | `fix:` | `docs:`, `chore:`, `test:` |
+| PR labels | `release:major`, `breaking-change` | `release:minor`, `feature` | `release:patch`, `bugfix` | `release:none`, `no-release` |
+| Breaking-change markers | Migration required, compatibility break marker | n/a | n/a | n/a |
+| Linked issue/ticket type | epic/breaking/migration | feature/story | bug/defect | docs/task |
+
+Lower/higher ordinary signals are not conflicts; the highest signal wins and lower signals are retained in `version_impact_sources`. Explicit incompatible claims are conflicts: for example, an explicit `versionImpact: none` with PRD prose that says a breaking migration is required must populate `version_impact_conflicts` and block tag creation or require manual review before a tag is created.
+
+## Tag guardrails
+
+Five guardrails gate every tag-creation attempt. All five must pass (or be `skipped` with a documented reason) before any tag is created.
+
+1. **Green CI required** — the latest CI run on the candidate SHA must report `success`. The release workflow must not bypass or override the CI status.
+2. **Conventional commits required** — every commit in the candidate range must match the conventional commit grammar (`feat:`, `fix:`, `BREAKING CHANGE:`, etc.). Non-conventional commits block the tag.
+3. **Secrets/permissions preflight required** — required secrets/registry tokens must be present and the workflow's `permissions` block must be explicit (no default broad grants). The preflight must not log secret values; it logs only the key names and presence/absence.
+4. **No dirty generated state required** — the working tree must not contain uncommitted changes to generated artifacts (e.g. `dist/`, `build/`, golden fixtures). Generated files must be either committed or gitignored.
+5. **Protected tag policy required** — the tag must be created via the CI-controlled release identity, not via a local push. The provider must reject local tag pushes for protected tag patterns (`v*`, `release/*`).
+
+A guardrail that fails produces a `guardrail_reasons` entry naming the failure. The release workflow must surface the failed guardrail to the operator and exit non-zero without creating the tag.
+
+Version-impact conflicts are an additional fail-closed gate. They do not replace the five guardrails above; if conflicts are present, `tag_creation` is `blocked` even when the five guardrails pass or are skipped.
+
+## Provider release workflows
+
+The module emits provider-specific executable templates. Each template implements the same strategy contract (Hybrid default; SemVer/CalVer variants), the same five guardrails, and the canonical protected main / PR-only delivery policy. Templates default to **active on main after PR merge** (the release workflow runs on push to `main` and manual dispatch, with tag handling provider-specific), but tag creation is blocked by the guardrail gate. Release CI must not replace validation CI; PR validation and comment resolution happen before merge.
+
+### GitHub Actions (`.github/workflows/release.yml`)
+
+- Triggers: `push` to `main`, `workflow_dispatch`; no `pull_request` release trigger.
+- Permissions: explicit `permissions:` block scoped to the minimum needed for tag creation and publishing (`contents: write` for protected-tag API refs, `id-token: write` for OIDC, and any package-specific scopes such as `packages: write`). No default broad `write-all`.
+- Steps: checkout → setup language toolchain → install publish-semver-derived helpers → run guardrail preflight → run strategy selector → emit `release.json` → compute tag → push tag via GH API (not local) → optionally publish via publish-semver.
+- Reuses `publish-semver` for ecosystem-specific publishing semantics (npm, PyPI, crates.io, Maven Central, etc.).
+- Fails closed on any guardrail failure.
+
+### Azure Pipelines (`azure-pipelines-release.yml`)
+
+- Triggers: `trigger` on `main`, `pr: none` for release (validation PR checks are separate), manual via `parameters`.
+- Variables: explicit `variables:` block; sensitive values from an Azure DevOps variable group (linked secret store). `secrets/permissions` preflight runs as the first task.
+- Steps: checkout → use Node/Python/Rust task → install publish-semver helpers → run guardrail preflight → run strategy selector → emit `release.json` → create tag via Azure Repos API with the CI identity, not a local push or personal access token → optionally publish.
+- Fails closed on any guardrail failure.
+
+### GitLab CI (`.gitlab-ci-release.yml`)
+
+- Stages: `validate` → `release`.
+- Triggers: `rules:` on push to `main`, on tag pipeline, manual via `when: manual`; no merge-request release trigger.
+- Variables: explicit; protected CI/CD variables masked; `secrets/permissions` preflight runs first.
+- Steps: checkout → install toolchain → install publish-semver helpers → run guardrail preflight → run strategy selector → emit `release.json` → create protected tag via the GitLab Releases API (not a local push) → optionally publish.
+- Fails closed on any guardrail failure.
+
+The provider release templates are checked in but do not run unless the user explicitly enables them. Enabling is a checklist/decision, not a hidden mutation.
+
+## Protected main and PR-only delivery
+
+Every repo initialized with this release module assumes protected main and PR-only delivery:
+
+- Branch/ruleset/tag protection is emitted as checklist-only provider configuration unless the user explicitly authorizes host admin mutation.
+- Every implementation change reaches main through a PR. Admin users may self-approve where policy permits only through an explicit admin approve/admin bypass lane that the host/runtime supports; otherwise use a distinct approver. The PR still exists and remains auditable, and the merge record captures actor, authority, reason, checks, and approval mode.
+- The PR review loop must resolve all actionable comments using architect, reviewer, and executor roles before merge.
+- Local CI and host SCM CI must be green before merge. Release CI then runs from the protected main SHA and may create tags only through provider APIs.
+
+## Tag creation, protected tags, and audit
+
+- **Protected tags.** Each provider has a tag-protection mechanism: GitHub `rulesets` for tag patterns, Azure DevOps branch/tag policies, GitLab `protected tags`. The module emits a checklist for tag protection per provider but does not call provider APIs to apply it.
+- **CI-controlled release identity.** Tag creation runs inside the CI job with the CI-provided identity through provider APIs, not from a developer machine and not via local `git push`. The audit trail in the `release.json` manifest records the CI run id as `trace_id`, the runner provider as `provider`, and the protected-main / PR-only `delivery_policy`.
+- **No history rewrites.** The module does not include tag deletion, force-push, or commit-history rewriting. If a bad tag is pushed, the recovery path is to push a new tag (e.g. `v1.4.1`) and emit a manifest entry explaining the prior tag's retirement; the prior tag is not deleted.
+- **No production deploys.** The release workflows stop at tag creation and (optional) package publish. They do not deploy to production environments, run database migrations, or invoke cloud provisioning. Production deployment is a separate downstream concern.
+
+## Credential and registry boundary
+
+- **Package/registry publishing is conditional.** The release workflow only attempts to publish when (a) the project has a recognized package manifest (e.g. `package.json`, `pyproject.toml`, `Cargo.toml`, `pom.xml`) and (b) the required publishing credentials are present and scoped.
+- **Full automation allowed when permissions allow.** If the host and registry permit and the operator has confirmed the scope, the release workflow may publish automatically after tag creation. If the host rejects or the scope is missing, the workflow stops after tag creation and surfaces a clear next-step message.
+- **No secret value logging.** Preflight logs only the names of the secrets it found and the scopes it detected. Secret values are never echoed to logs.
+
+## Reuse of `publish-semver`
+
+This module reuses the `publish-semver` skill (installed under `~/.codex/skills/publish-semver/`) for ecosystem-specific publishing semantics — npm, PyPI, crates.io, Maven Central, NuGet, pub.dev, Hex, Erlang Hex, and Gradle/Maven Central via Azure DevOps. The release workflow invokes `publish-semver` to do the actual publish step; this module owns the strategy, manifest, version-impact source selection, and guardrails, not the publish semantics. The `publish-semver` conventional-commit mapping (`fix` patch, `feat` minor, breaking major) is one input source in the matrix, not the only authority.
+
+## Safety rules
+
+- **Truth preservation.** The `release.json` manifest is the only authoritative record. Provider APIs may tag; the manifest is what auditors read.
+- **No fake tags.** Tags must come from a real guardrail-passed release run. No manual tag pushes for protected tag patterns.
+- **No production deploys in this module.** Production deploys are out of scope and live in a downstream module.
+- **No history rewrites.** Tag retirement is forward-only; the prior tag is recorded as retired, not deleted.
+- **Idempotent manifest writes.** A re-run with the same input must produce a byte-identical manifest (timestamps and trace ids come from the CI run, not the wall clock; the CI run id is stable per run).
+- **Verification commands run after every provider-template change.** See the verification section below.
+
+## Verification commands
+
+Run from `skills/` after touching this module, the module map, the SKILL, `ci-policy.md`, or any provider release template:
+
+```sh
+tests/test-skills.sh
+tests/test-scripts.sh
+tests/run-tests.sh
+bash scripts/archgate.sh --mode structural --rules .rules.ts --format json
+./scripts/verify-golden-dir.sh . reference/golden-root
+./scripts/verify-golden-dir.sh . reference/golden-skills
+```
+
+The release-versioning-specific golden fixtures live under `reference/fixtures/release/` and cover:
+
+- `hybrid-default/` — Hybrid strategy selector emits a Hybrid-shaped manifest with base+timestamp+trace.
+- `semver-only/` — SemVer strategy selector emits a pure-SemVer manifest.
+- `calver-only/` — CalVer strategy selector emits a CalVer-shaped manifest.
+- `guardrail-fail/` — at least one guardrail fails; the manifest records the failure and `tag_creation: "blocked"`.
+- `protected-tag/` — the provider template declares protected-tag semantics; local-push paths are explicitly rejected.
+- `version-impact/` — PRD/spec version-impact signals are recorded and win over lower-priority inferred signals.
+- `no-history-rewrite/` — the template contains no `git push --force`, no tag deletion, no commit-history rewrite.
+- `no-production-deploy/` — the template contains no `azure webapp deploy`, no `kubectl apply`, no `aws s3 sync` style production steps.
+- `secrets-preflight/` — the preflight logs key names only, never values.
+- `version-impact-highest-signal/` — PRD/spec prose can raise a fix-only commit to major or minor by highest-signal precedence.
+- `version-impact-conflict/` — explicit incompatible claims are recorded in `version_impact_conflicts` and block tag creation/review.