contextdevkit 1.8.0

package/templates/claude/commands/audit/deps-audit.md

@@ -0,0 +1,49 @@
+---
+description: Dependency & supply-chain audit (security-team) — lockfile, pinning, CVEs → backlog.
+---
+
+# 🔐 Deps Audit (security-team)
+
+Run the **security-team's** dependency / supply-chain check, then feed the backlog.
+
+1. **Audit** (writes findings for ingestion):
+   ```
+   node contextkit/tools/scripts/deps-audit.mjs --write
+   ```
+   Detects: missing lockfile (non-reproducible installs), unbounded version
+   ranges, **license-policy** violations (deny-list / allow-list from
+   `contextkit/config.json` → `deps.licenses`), **lockfile drift** (a declared dep
+   missing from the lockfile), and — when the toolchain is present —
+   `npm`/`pnpm`/`yarn audit` CVEs (severity-mapped critical→5 … info→1).
+
+   Generate a CycloneDX **SBOM** (provenance):
+   ```
+   node contextkit/tools/scripts/deps-audit.mjs --sbom   # → contextkit/memory/sbom.json
+   ```
+
+2. **Feed the DevPipeline backlog** — each issue becomes an auto-prioritized task:
+   ```
+   node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/deps-findings.json --type chore
+   ```
+   Idempotent (re-runs don't duplicate). Priorities are **always editable**
+   (`pipeline.mjs prioritize <id> <P>` or `/pipeline`).
+
+3. **Interpret with judgment** (delegate to the `security` agent): which advisories
+   are actually reachable/exploitable in THIS app vs transitive noise? Recommend the
+   fix (upgrade · pin · replace · accept-with-reason). On a Critical/High, the
+   security-team can block the release.
+
+4. **Report**: counts by severity + the top items + what was ingested.
+
+5. **GitHub-native (optional, loop-closer)** — if the repo is on GitHub, pull its
+   **Dependabot + code-scanning alerts** into the same backlog (needs the `gh` CLI,
+   authenticated):
+   ```
+   node contextkit/tools/scripts/gh-alerts.mjs --write
+   node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/gh-alerts-findings.json --type chore
+   ```
+   Set up the scaffolding (`.github/dependabot.yml` + the security workflow) with
+   `/security-setup`.
+
+Stack note: Node is audited deterministically. For Python (`requirements.txt` /
+`pyproject.toml`) the command flags that `pip-audit` / `safety` should run.

package/templates/claude/commands/audit/security-setup.md

@@ -0,0 +1,35 @@
+---
+description: Scaffold GitHub-native security (Dependabot + CodeQL + dependency-review) and sync alerts into the backlog (security-team).
+---
+
+# 🔐 Security Setup (security-team)
+
+Make GitHub's security features first-class: keep deps patched, scan code, and turn
+GitHub's own alerts into owned backlog tasks. Idempotent — safe to re-run.
+
+1. **Confirm the scaffolding** (the installer drops these write-if-missing; create if absent):
+   - `.github/dependabot.yml` — version updates per ecosystem.
+   - `.github/workflows/security.yml` — `dependency-review` (PRs) + `/deps-audit` + CodeQL,
+     all **advisory** by default.
+
+2. **Tune to THIS stack** — detect the ecosystems in the repo (npm / pip / gomod / cargo /
+   maven / ...) and enable the matching `dependabot.yml` blocks; set the CodeQL `language`
+   matrix to the repo's real languages, and drop jobs that don't apply. Keep it advisory —
+   don't make it a required check until the team opts in (that's the enforcement switch).
+
+3. **Close the loop (alerts → backlog)** — pull GitHub's own alerts in and prioritize them:
+   ```
+   node contextkit/tools/scripts/gh-alerts.mjs --write
+   node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/gh-alerts-findings.json --type chore
+   ```
+   Needs an authenticated `gh` CLI (`gh auth login`). Degrades silently if absent — never blocks.
+
+4. **Triage with judgment** (delegate to the `code-security` agent): which alerts are actually
+   reachable/exploitable in THIS app vs transitive noise? Recommend the fix — upgrade · pin ·
+   replace · accept-with-reason. On a Critical/High, the security-team can block the release.
+
+5. **Report**: what was scaffolded, which ecosystems/languages you enabled, and how many
+   alerts were ingested.
+
+Pairs with `/deps-audit` (deterministic local check: lockfile, pinning, license policy, SBOM,
+CVEs). This command adds the GitHub-native layer on top.

package/templates/claude/commands/audit/seo-audit.md

@@ -0,0 +1,63 @@
+---
+description: SEO + AISO audit — runs the two static analysers and summarises findings. Refuse-on-SPA for landing pages. (ADR-0025)
+argument-hint: [--json] [--seo-only|--aiso-only]
+---
+
+# 🔍 SEO + AISO audit
+
+Run both static analysers against the current project and produce a
+prioritised findings list. The kit treats two index spaces as
+first-class concerns:
+
+- **Classical SEO** — Googlebot, Bingbot, structured data, Core Web
+  Vitals. Audited by `seo-audit.mjs`.
+- **AISO** (AI Search Optimization) — GPTBot, ClaudeBot, PerplexityBot,
+  the `llms.txt` + FAQ-schema family. Audited by `aiso-audit.mjs`.
+
+Authority: [ADR-0025](../../contextkit/memory/decisions/0025-seo-and-aiso-posture.md) + [seo-aiso playbook](../../contextkit/workflows/playbooks/seo-aiso.md).
+
+## What this does
+
+1. Runs `node contextkit/tools/scripts/seo-audit.mjs` and
+   `node contextkit/tools/scripts/aiso-audit.mjs` (or only one, if
+   `--seo-only` / `--aiso-only` is passed).
+2. Reads the findings. If `--json` was passed, prints raw JSON for CI
+   consumption.
+3. Otherwise: groups findings by severity, lists the top 3 next-step
+   fixes ordered by *severity × leverage* (a single fix that resolves
+   multiple findings is worth more than three isolated ones).
+4. Refuse-on-critical: if `SPA_ENTRYPOINT` fires, this command writes a
+   clear refusal pointing at the landing-page playbook and the
+   override path (a project-local ADR).
+
+## Refusal posture
+
+A finding with severity `critical` (currently only `SPA_ENTRYPOINT`) is
+an explicit refusal — the audit exits non-zero and the
+`seo-specialist` agent will refuse PR approval on a landing surface
+until either:
+
+- The framework is changed to one that ships SSR/SSG (Astro, Next
+  App Router, Nuxt, Remix, SvelteKit), OR
+- The project ships a local ADR explicitly carving the surface out
+  ("this is an internal admin tool — no indexability needed").
+
+## When to run
+
+- **Before opening a PR** that touches a landing page or marketing
+  site.
+- **On the design pass** when proposing a new public route.
+- **In CI** — the JSON output is gateable
+  (`node contextkit/tools/scripts/seo-audit.mjs --json > seo.json` +
+  a tiny step that `jq`s for critical severity).
+
+## What it does NOT do
+
+- It does not auto-rewrite HTML. Findings are the deliverable; the
+  human approves the fix (rule 8, ADR-0025).
+- It does not run a headless-browser crawl. Static analyser only
+  (rule 1).
+- It does not measure Core Web Vitals. Use PageSpeed Insights or
+  Lighthouse CI for that. The audit flags *patterns* that hurt
+  CWV (missing image dimensions, JS-rendered hero content) — not the
+  measurements themselves.

package/templates/claude/commands/audit/tech-debt-sweep.md

@@ -0,0 +1,35 @@
+---
+description: Audit the codebase against the constitution — deterministic scan + your interpretation.
+argument-hint: [profile: full | quick]
+---
+
+# 🧹 Tech Debt Sweep
+
+Run the **deterministic scanner** first, then interpret. Profile: **$ARGUMENTS**
+(default `full`; `quick` = red zone only).
+
+1. Run the scanner and write the board:
+   ```
+   node contextkit/tools/scripts/tech-debt-scan.mjs --write          # full
+   node contextkit/tools/scripts/tech-debt-scan.mjs --write --quick   # red zone only
+   ```
+   It checks: file length vs `l5.lineBudget`, SRP "And/Or/E" names, TODO/FIXME
+   markers, and React state-loops — and writes `contextkit/memory/tech-debt-board.md`.
+
+2. **Interpret** the board with judgment the regex can't: which findings are real
+   debt vs acceptable cohesion? Which oversized file genuinely hides multiple
+   responsibilities? Add any smells the scanner can't see (leaky abstractions,
+   duplicated logic, missing error handling) — referencing `CLAUDE.md`.
+
+3. **Feed the DevPipeline backlog** — every finding becomes a tracked task:
+   ```
+   node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/tech-debt-findings.json --type chore
+   ```
+   One backlog task per finding, **auto-prioritized from severity** (RED→P1,
+   yellow→P2, low→P3), **idempotent** (re-running never duplicates).
+
+4. **Report + hand off.** Surface the **top 5** with the one-line fix each — the
+   board `contextkit/memory/tech-debt-board.md` is the full report. Do NOT fix here.
+   Tell the user the items are in the backlog and the priorities are
+   **always editable**: `node contextkit/tools/scripts/pipeline.mjs prioritize <id> <P0-P3>`
+   or `/pipeline`. Offer to open a focused `/dev-start` on the worst one.

package/templates/claude/commands/bug-hunt.md

@@ -0,0 +1,42 @@
+---
+description: Investigator mode — find root cause before writing any new feature code.
+argument-hint: <bug description / symptom>
+---
+
+# 🔍 Mode: Bug Hunt
+
+Symptom under investigation:
+
+> **$ARGUMENTS**
+
+## Posture (strict until root cause is confirmed)
+
+1. **Do NOT write feature code or speculative fixes yet.** First understand the failure.
+
+2. **Gather evidence**: ask the user for (or locate yourself) the exact error message, stack trace,
+   logs, failing input, and reproduction steps. State what you have and what is missing.
+
+3. **Map the flow**: trace the code path from entry point to the failure site. Reference files as
+   `path:line`. Note every place state is transformed.
+
+4. **Rank hypotheses** (most → least likely) with the evidence for each. Be explicit about what
+   would confirm or eliminate each one.
+
+5. **Propose the cheapest decisive experiment** to confirm the top hypothesis (a log line, a unit
+   test, a one-line probe). Run it (or ask the user to) before committing to a fix.
+
+6. **Only after root cause is confirmed**: propose the minimal fix, get approval, then implement.
+   Add a regression test if the stack supports it.
+
+7. **Report + backlog.** Write a short root-cause report (symptom → root cause → fix →
+   regression test). Record the bug — and any *related* issues you surfaced — in the
+   DevPipeline, point by point:
+   ```
+   node contextkit/tools/scripts/pipeline.mjs add --type bug --priority <P0-P3> \
+     --source "bug:<area>" --title "<symptom>"
+   ```
+   Auto-priority: data-loss / security / broken build → P0, broken core path → P1,
+   degraded → P2, cosmetic → P3. If you fixed it this session, `pipeline.mjs move
+   <id> conclusion`. Priorities are **always editable** (`prioritize <id> <P>` / `/pipeline`).
+
+Resist the urge to "just try something." A confirmed root cause beats three plausible guesses.

package/templates/claude/commands/claude-md.md

@@ -0,0 +1,36 @@
+---
+description: Ensure every app/module has its own scoped CLAUDE.md, then fill each with real local rules.
+argument-hint: [find | scaffold]
+---
+
+# 📁 Modular CLAUDE.md
+
+Like a well-run monorepo (root `CLAUDE.md` + `apps/api/CLAUDE.md` +
+`apps/web/CLAUDE.md` …), each app / independent module should carry its **own**
+scoped `CLAUDE.md`. Claude Code loads the closest one, so local rules live next to
+the code — clearer, more accurate guidance per area.
+
+1. **Detect** module roots:
+   ```
+   node contextkit/tools/scripts/claude-md.mjs find
+   ```
+   It finds split dirs (`backend/`, `frontend/`, `api/`, `web/`, `mobile/`, …) and
+   monorepo group children (`apps/*`, `packages/*`, `modules/*`, `services/*`) that
+   look independently buildable, and shows which lack a `CLAUDE.md`.
+
+2. **Scaffold** the missing ones (stubs, won't overwrite):
+   ```
+   node contextkit/tools/scripts/claude-md.mjs scaffold
+   ```
+
+3. **Fill each one with real, local content** (this is the important part — don't
+   leave the TODOs). For every scoped `CLAUDE.md`, read that module and write:
+   - what it is + its single responsibility (backend/frontend/lib/service);
+   - its local stack/tooling;
+   - **local conventions** that differ from the root (folder layout, where logic
+     goes, the public surface to keep stable);
+   - boundaries (depends on / consumed by).
+   Keep it lean and inheriting the root constitution — don't duplicate it.
+
+Run on `$ARGUMENTS` (default: do `find`, then offer `scaffold` + fill). For a
+single-package project with no sub-modules, the root `CLAUDE.md` is enough — say so.

package/templates/claude/commands/close-version.md

@@ -0,0 +1,25 @@
+---
+description: Close the current version in the CHANGELOG ([Unreleased] → [X.Y.Z]) and tag it.
+argument-hint: <version e.g. 0.2.0>
+---
+
+Close version **$ARGUMENTS** in `docs/CHANGELOG.md`.
+
+1. Read `docs/CHANGELOG.md`. Confirm `[Unreleased]` has content. If empty, stop and tell the user
+   there is nothing to release.
+
+2. Rename the `## [Unreleased]` heading to `## [$ARGUMENTS] - <today YYYY-MM-DD>` and insert a fresh
+   empty `## [Unreleased]` block above it (with placeholder "Add your changes here.").
+
+3. Summarize to the user what is being released.
+
+4. Offer (do NOT run without confirmation) the tag + release commands:
+   ```
+   git add docs/CHANGELOG.md
+   git commit -m "chore(release): v$ARGUMENTS"
+   git tag v$ARGUMENTS
+   ```
+   And, if a GitHub remote exists and `gh` is available, offer `gh release create v$ARGUMENTS`.
+
+If ContextDevKit is at Level 5 and a `qa` gate marker is configured beyond T0, surface any failing
+quality signals before closing.

package/templates/claude/commands/context-refresh.md

@@ -0,0 +1,19 @@
+---
+description: Regenerate the dynamic full-project snapshot (.context-snapshot.md).
+---
+
+> ⚠️ **Deprecated (1.0):** prefer **/audit** (or the auto boot context). This
+> still regenerates the on-demand snapshot.
+
+Regenerate the on-demand project snapshot:
+
+```
+node contextkit/tools/scripts/generate-context.mjs
+```
+
+This writes `.context-snapshot.md` (gitignored) containing the folder tree, detected stack, latest
+session, CHANGELOG `[Unreleased]`, and a glossary excerpt.
+
+Use it before a large refactor (so you can see the whole project at once), or to paste into another
+AI that lacks the boot hook. After running, read `.context-snapshot.md` and give the user a 3-line
+summary of what it captured.

package/templates/claude/commands/context-stats.md

@@ -0,0 +1,15 @@
+---
+description: Show platform telemetry — sessions, drift rate, ADRs, agents, weekly cadence.
+---
+
+Show how healthy the ContextDevKit practice is on this project:
+
+```
+node contextkit/tools/scripts/stats.mjs
+```
+
+Present the output to the user and add a one-line read: is the **drift rate**
+trending down (good — sessions are being registered)? Is the cadence steady? Are
+ADRs being written for big decisions? Suggest a concrete habit if a metric looks
+off (e.g. high drift → remember `/log-session`; zero ADRs on a big change →
+`/new-adr`).

package/templates/claude/commands/dashboard.md

@@ -0,0 +1,66 @@
+---
+description: Visual dashboard — pipeline lanes + ADRs + sessions + roadmap + CHANGELOG. Snapshot HTML by default; live SSE-driven view with --watch.
+argument-hint: [--watch] [--port=N] [--out=PATH]
+---
+
+# 📊 Dashboard
+
+A single-file HTML view of the project's current state. Pipeline lanes
+(backlog / working / testing / concluded), the ADR catalogue, recent
+sessions, the roadmap, and the `[Unreleased]` CHANGELOG — all rendered
+from the existing files. Zero deps; pure `node:` stdlib.
+
+## Two modes — one command
+
+### Snapshot (default)
+
+```
+node contextkit/tools/scripts/dashboard.mjs                    # writes ./dashboard.html
+node contextkit/tools/scripts/dashboard.mjs --out=tmp/state.html
+```
+
+Writes a self-contained HTML file and exits. Inline CSS + JS, no external
+assets — opens by double-click, works offline, survives without the kit
+installed. Use this for share-by-email or commit-to-PR-preview.
+
+### Live (`--watch`)
+
+```
+node contextkit/tools/scripts/dashboard.mjs --watch            # serves http://127.0.0.1:4242
+node contextkit/tools/scripts/dashboard.mjs --watch --port=8080
+CONTEXTDEVKIT_DASHBOARD_PORT=5555 node contextkit/tools/scripts/dashboard.mjs --watch
+```
+
+Spawns a tiny `node:http` server bound to **127.0.0.1 only** (no network
+access). The page subscribes to `/events` via Server-Sent Events; an
+`fs.watch` on `contextkit/` (200 ms debounced) triggers a rebuild and pushes
+the new data object. The client patches the DOM in place — no full
+reload. Ctrl+C to stop.
+
+## What it shows
+
+- **Counts strip** — totals per lane.
+- **Pipeline (4-column kanban)** — every ticket as a card with id, type
+  badge, priority badge, SLA, source. Sorted by id within each lane.
+- **Recent ADRs** — the 12 newest, status colour-coded.
+- **Recent sessions** — the 10 newest, with branch.
+- **`[Unreleased]` CHANGELOG** — collapsible.
+- **Roadmap** — collapsible, only if `contextkit/memory/roadmap.md` exists.
+
+## What it does NOT do
+
+- **No edit-in-place.** Read-only by design.
+- **No remote access.** 127.0.0.1 only — no `0.0.0.0`, no auth, no TLS.
+- **No multi-project.** Use `/fleet` for the portfolio view.
+- **No JS framework.** Inline vanilla JS in the page; no React, no Vite,
+  no `node_modules` to install.
+- **No persistent state.** Every render re-reads the files.
+
+## When to use it
+
+- **During a session** — `--watch` in a second pane, edits in the editor,
+  the board updates as you move tickets between lanes.
+- **End of session** — snapshot to attach to a `/log-session` summary or
+  a PR description.
+- **Reviewing someone else's progress** — open the snapshot file they
+  committed (no install required).

package/templates/claude/commands/distill-apply.md

@@ -0,0 +1,19 @@
+---
+description: L5 — apply a reviewed .distillation-proposal.md to CLAUDE.md and record an ADR for the cycle.
+---
+
+# 🧬 Distill apply
+
+Materialize the proposal produced by `/distill-sessions`.
+
+1. Read `.distillation-proposal.md`. If it is missing, stop and tell the user to
+   run `/distill-sessions` first.
+2. Show the user the exact `CLAUDE.md` edits you are about to make and get
+   confirmation. Respect the constitution — keep `CLAUDE.md` lean.
+3. Apply the edits to `CLAUDE.md`.
+4. Create an ADR (`/new-adr`-style) recording the distillation cycle: which
+   sessions informed it and what changed in the constitution, so the *why* is
+   captured. ADRs are immutable once accepted.
+5. Delete `.distillation-proposal.md` (it is consumed).
+6. Stage `CLAUDE.md` + the new ADR together so the decision and its rationale
+   land in the **same commit**. Then run `/log-session`.

package/templates/claude/commands/distill-sessions.md

@@ -0,0 +1,26 @@
+---
+description: L5 — analyze recent sessions and propose refinements to CLAUDE.md (writes a proposal, applies nothing).
+---
+
+# 🧬 Distill sessions (propose)
+
+Analyze the recent session history and propose improvements to `CLAUDE.md` — but
+**apply nothing**. This is the review step; `/distill-apply` materializes it.
+
+1. Get a **compact digest** of the last N sessions instead of reading the raw
+   logs [ADR-0027]: `node contextkit/tools/scripts/session-digest.mjs --last N`
+   (N from `contextkit/config.json` → `l5.distill.observeWindow`, default 10),
+   newest first. Reason over the digests; open a full file in
+   `contextkit/memory/sessions/` only when a digest flags a pattern you must
+   inspect verbatim.
+2. Look for **recurring signals**: corrections the user gave repeatedly, rules
+   re-explained across sessions, conventions that emerged but aren't written
+   down, friction that a CLAUDE.md rule would prevent, and decisions that should
+   be promoted to an ADR.
+3. Draft a concrete diff to `CLAUDE.md` (and note any ADRs worth creating).
+   Prefer small, high-signal additions over bloat — CLAUDE.md must stay short.
+4. Write the proposal to `.distillation-proposal.md` (gitignored) with: the
+   evidence (which sessions, what pattern), the proposed CLAUDE.md edits as a
+   clear before/after, and any suggested ADRs.
+5. Summarize to the user and tell them to review it, then run `/distill-apply` to
+   commit the change. Do not edit `CLAUDE.md` in this command.

package/templates/claude/commands/fleet.md

@@ -0,0 +1,47 @@
+---
+description: Fleet mode — one control plane over many ContextDevKit repos (portfolio stats, cross-repo audit, CLAUDE.md rule-drift).
+argument-hint: [list | add <path> | remove <path> | stats | audit | propagate <rule-file>]
+---
+
+# 🛰️ Fleet (control plane over many repos)
+
+Operate on a **portfolio** of ContextDevKit repos at once. The registry lives outside
+any repo — `~/.contextdevkit/fleet.json` (override `CONTEXT_FLEET_FILE`). Helper:
+`contextkit/tools/scripts/fleet.mjs`.
+
+Act on **$ARGUMENTS**:
+
+## list / add / remove
+```
+node contextkit/tools/scripts/fleet.mjs add <path-to-repo>
+node contextkit/tools/scripts/fleet.mjs list
+```
+Register the repos you want the fleet to cover (absolute paths are stored).
+
+## stats — portfolio health
+```
+node contextkit/tools/scripts/fleet.mjs stats          # or --json
+```
+Runs each repo's `stats.mjs` and aggregates: level, registered sessions, ADRs,
+agents, drift rate per repo + totals. Call out the repos that look unhealthy
+(high drift, no recent sessions, stuck at a low level).
+
+## audit — findings across the portfolio
+```
+node contextkit/tools/scripts/fleet.mjs audit          # or --json
+```
+Runs each repo's `deep-analysis.mjs` and aggregates finding counts. Surface the
+repos carrying the most debt/risk; suggest where to run `/deep-analysis` or
+`/deps-audit` next.
+
+## propagate — CLAUDE.md rule drift (detect-only)
+```
+node contextkit/tools/scripts/fleet.mjs propagate <rule-file>
+```
+Reports which repos' `CLAUDE.md` **lack** a given rule block. Fleet **does not
+auto-edit** — for each MISSING repo, add the rule with judgment (it may need
+adapting per stack), ideally via that repo's own session + PR.
+
+## Report
+Summarize the portfolio: totals, the 1–3 repos needing attention, and the
+concrete next action per repo. Keep it advisory — the fleet informs, you decide.

package/templates/claude/commands/forge/forge-audit.md

@@ -0,0 +1,16 @@
+---
+description: Tally the audit log for a forged Agent Package — call counts by outcome, fallback rate, cost summary. Read-only. (agent-forge squad)
+argument-hint: <agent>[@<version>] [--json]
+---
+
+# 🛠️ Mode: agent-forge — audit
+
+Run `node contextkit/squads/agent-forge/cli/forge-ops.mjs audit $ARGUMENTS`.
+
+Reads `audit/<agent>.jsonl` (the runtime adapter writes it per
+`governance/compliance.policy.yaml.audit.destination`) and reports totals.
+
+## Interpret
+- Many `refused` → review the prompt; the agent is over-refusing.
+- High `fallbacks` → the primary provider is unstable; consider `/forge-route` to re-evaluate.
+- Cost drift vs `forge-budget` → flag and recommend `/forge-policy` review.

package/templates/claude/commands/forge/forge-budget.md

@@ -0,0 +1,16 @@
+---
+description: Aggregate monthly target + hard-cap across every forged Agent Package — the consolidated cost view. Read-only. (agent-forge squad)
+argument-hint: [--root <dir>] [--json]
+---
+
+# 🛠️ Mode: agent-forge — budget
+
+Run `node contextkit/squads/agent-forge/cli/forge-ops.mjs budget $ARGUMENTS`.
+
+Sums `spec.cost.monthly_budget_usd` across every package and surfaces the
+per-agent breakdown. The hard cap = target × 1.5 per the governance default.
+
+## Surface to the dev
+- If the aggregate hard cap exceeds the project's monthly LLM budget, this is
+  the time to surface it — recommend lowering `cost.target_usd_per_call` on the
+  agents driving the budget or moving sub-tasks to `cheap_path`.

package/templates/claude/commands/forge/forge-deprecate.md

@@ -0,0 +1,16 @@
+---
+description: Stamp `metadata.deprecated_at` into a forged Agent Package's manifest and recommend an ADR for the reason. Atomic write; dry-run by default. (agent-forge squad)
+argument-hint: <agent>[@<version>] [--write]
+---
+
+# 🛠️ Mode: agent-forge — deprecate
+
+Run `node contextkit/squads/agent-forge/cli/forge-admin.mjs deprecate $ARGUMENTS`.
+
+Marks the version as deprecated without deleting it. Clients can still
+consume the package; the marker tells them to migrate to the successor.
+
+## After
+1. Recommend `/new-adr "deprecate <agent>@<version>"` with the migration path.
+2. If a successor exists, link it: `metadata.superseded_by: <agent>@<new>`.
+3. Add a CHANGELOG entry in the package's own `CHANGELOG.md`.

package/templates/claude/commands/forge/forge-doctor.md

@@ -0,0 +1,17 @@
+---
+description: Integrity check across every forged Agent Package — required files present, no {{TOKEN}} placeholders left in governance YAMLs. Read-only; exits non-zero on any problem. (agent-forge squad)
+argument-hint: [--root <dir>] [--json]
+---
+
+# 🛠️ Mode: agent-forge — doctor
+
+Run `node contextkit/squads/agent-forge/cli/forge-ops.mjs doctor $ARGUMENTS`.
+
+Walks every package, asserts the 11 expected files exist, and verifies the 3
+governance policies are *populated* (no `{{TOKEN}}` placeholders). Exits 1 if
+anything is wrong.
+
+## When issues appear
+- Missing files → re-run `/forge-new` for the agent, or restore from git.
+- Placeholder tokens in governance → the package was hand-edited or shipped
+  before Fase 3 — re-forge it or run `/forge-policy` to see what's missing.

package/templates/claude/commands/forge/forge-eval.md

@@ -0,0 +1,16 @@
+---
+description: Run the eval gate (golden + red-team) for one forged Agent Package against its thresholds. Default provider is a deterministic mock for CI; --provider chaos exercises an upstream-503. (agent-forge squad)
+argument-hint: <agent>[@<version>] [--provider mock|chaos] [--json]
+---
+
+# 🛠️ Mode: agent-forge — eval
+
+Run `node contextkit/squads/agent-forge/cli/forge-eval-cli.mjs eval $ARGUMENTS`.
+
+This is the Fase 3 gate, re-runnable on demand. Exits 1 on any threshold
+breach so it can chain into a CI step.
+
+## When the verdict is FAIL
+- Surface every failure reason verbatim.
+- Do NOT recommend a `--write` or deploy until the dev fixes the underlying issue.
+- A red-team `pii_leak` failure when `pii_present: true` is non-negotiable — escalate.

package/templates/claude/commands/forge/forge-fallback-test.md

@@ -0,0 +1,17 @@
+---
+description: Chaos-test the fallback path for one forged Agent Package by simulating a primary 503 on the first call. Verifies the eval scaffold survives upstream failures. (agent-forge squad)
+argument-hint: <agent>[@<version>] [--json]
+---
+
+# 🛠️ Mode: agent-forge — fallback test
+
+Run `node contextkit/squads/agent-forge/cli/forge-eval-cli.mjs fallback-test $ARGUMENTS`.
+
+The chaos provider raises a 503 once, then behaves normally. The runner
+demonstrates that the eval scaffold tolerates the failure. The actual
+fallback-chain wiring lives in the client's runtime adapter — Fase 5 will
+exercise it end-to-end with the real adapter.
+
+## After
+- If the test reports a fall-back, surface the new primary model. Compare with
+  `governance/fallback-chain.yaml.chain[0]` — they should match.

package/templates/claude/commands/forge/forge-killswitch.md

@@ -0,0 +1,17 @@
+---
+description: Toggle quality.policy.yaml's `kill_switch.enabled` (on|off) for one forged Agent Package. Atomic write; dry-run by default. (agent-forge squad)
+argument-hint: <agent>[@<version>] <on|off> [--write]
+---
+
+# 🛠️ Mode: agent-forge — kill switch
+
+Run `node contextkit/squads/agent-forge/cli/forge-admin.mjs killswitch $ARGUMENTS`.
+
+When `on`, the runtime adapter refuses every call until manually reset. Use
+this DURING an incident, not as a planned change.
+
+## Refuse conditions
+- The dev wants to permanently disable the kill switch for "ergonomics".
+  Refuse — the kill switch is the agent's last line of defense (ADR-0012 §6).
+- A request to switch on without recording an incident note. Recommend
+  `/log-session` after toggling.

package/templates/claude/commands/forge/forge-list.md

@@ -0,0 +1,17 @@
+---
+description: List every forged Agent Package under agent-packages/ (or --root <dir>) with version + routed primary model + eval-stamp status. Read-only. (agent-forge squad)
+argument-hint: [--root <dir>] [--json]
+---
+
+# 🛠️ Mode: agent-forge — list packages
+
+Run `node contextkit/squads/agent-forge/cli/forge-ops.mjs list $ARGUMENTS`.
+
+Read-only. Walks the registry, doesn't need the `yaml` dep for discovery — but
+`primary model` + `eval-stamp` columns require it (ADR-0013). If `yaml` is
+missing, the listing still shows names + versions; suggest `npm i yaml` for
+the rest.
+
+## Post-output
+- Flag any package whose `eval-stamp` shows `⚠️ unevaluated` and recommend `/forge-eval <agent>`.
+- If two versions of the same agent are listed, recommend `/forge-deprecate <agent>@<old>`.