@mlmcps/ml-specs 1.0.0

package/ml-specs/commands/repo-estate.md

@@ -0,0 +1,79 @@
+---
+description: Generate or refresh docs/ESTATE.md — the cross-service contract index (who calls, publishes, and consumes what) for a multi-service estate
+argument-hint: (no args) to scan sibling repos, or paths/globs to the peer repos — e.g. ../user-service ../payments-service
+model: sonnet
+---
+
+You are building this repo's **estate index**: the map of the services around it and the contracts
+between them. It is what lets a change that crosses a service boundary be designed against both
+sides without cloning and grepping the whole estate.
+
+Peer repos to scan: **$ARGUMENTS**
+
+The template lives at `${CLAUDE_PLUGIN_ROOT}/templates/docs/ESTATE.template.md`.
+
+## Phase 1 — scope it
+
+1. **Does this repo need an estate index at all?** If it's a standalone app with no outbound
+   service calls and no event producers/consumers, say so and **stop** — do not create the file. A
+   monorepo's internal modules are `docs/ARCHITECTURE.md` shards, not estate peers.
+
+2. **Locate the peers.** In order: the paths given in `$ARGUMENTS`; else sibling directories of this
+   repo's parent that are git repos; else the other working directories available in this session.
+   List what you found and how many you'll scan. If the set is ambiguous or large (>~12 repos), put
+   it to the user with AskUserQuestion — scan the ones they name rather than guessing.
+
+3. **Read-only outside this repo.** You may read peer repos; you may not write to them.
+
+## Phase 2 — learn the edges (not the peers)
+
+You are indexing contracts, not learning each service — that's `/repo-init` inside that repo. Stay
+shallow and cheap: for each peer, the manifest for its stack, its README/`docs/ARCHITECTURE.md` for
+what it owns, and then only the files that carry an edge.
+
+**Delegate the peer reading, one agent per repo.** Spawn **scanner** once per peer repo with
+the `edges` brief, all **in a single message** so they run concurrently — N peers cost about one
+peer's wall-clock instead of N, and their file reads never enter this context. Give each the peer's
+path and the specific contracts you're trying to resolve (step 5), so it looks for counterparts
+rather than surveying the service. Scan this repo's own edges (step 4) inline — you need that
+detail first-hand to brief the peer scanners.
+
+4. **This repo's outbound edges** (highest confidence — you can read the real code):
+   - Synchronous: HTTP/RPC/gRPC clients, `@FeignClient`, generated SDK clients, base URLs from config.
+   - Asynchronous: published events/topics, and the listeners/consumers it subscribes to.
+   - Shared data: tables/collections/schemas or published packages/types shared with a peer.
+   Cite `file:line` for each.
+
+5. **The other side of each edge.** In the peer repo, find the counterpart — the controller/route
+   that serves the call, the producer of the event this repo consumes, the consumer of the event it
+   publishes. Confirmed from real code → cite `file:line`. Not confirmed → write the row anyway and
+   mark it **`(inferred)`** or `_TBD_`. Never invent a peer-side handler to make a table look complete.
+
+6. **Note what the names resolve from.** Queue/topic names and service URLs usually come from config
+   (env, a config server, service discovery), not literals — record where, so the next reader can
+   resolve them.
+
+## Phase 3 — write it
+
+7. Fill the template into `docs/ESTATE.md`. If the file already exists, **merge**: keep human-edited
+   rows and notes, correct what's now wrong, add new edges, and delete edges whose code is gone.
+   Refreshing is also pruning — keep it under ~200 lines. It is an index that links out, not
+   documentation that inlines.
+
+8. Make sure `CLAUDE.md`'s knowledge-layer section points at `docs/ESTATE.md` for cross-service work
+   (add the line if missing). Don't inline any of it into `CLAUDE.md`.
+
+9. **Other repos:** if the user wants the same index in the peer repos, offer it as an explicit
+   follow-up and write it only on their say-so. Never write into another repo unasked.
+
+## Phase 4 — report
+
+10. Report: peers scanned, edges found (sync / async / shared data), how many are confirmed vs
+    `(inferred)`, and the edges you could **not** resolve — those are the real output, because an
+    unresolved edge is where a cross-service change will break. Do NOT commit.
+
+Re-run this after adding a listener, a published topic, or a new cross-service client. Related:
+`/repo-refresh` (this repo's own docs) and `/repo-doctor` (drift check).
+
+The index exists to be *used*: `/repo-impact` reads it to answer "who breaks if this ships?" — which
+is why an unresolved edge here becomes a blind spot there, and why `_TBD_` is better than a guess.

package/ml-specs/commands/repo-impact.md

@@ -0,0 +1,77 @@
+---
+description: Find which other services a change breaks — detects modified published contracts and looks up their consumers in docs/ESTATE.md
+argument-hint: <spec file> to check a spec's ripple, or (no args) to analyse the current branch diff
+model: sonnet
+---
+
+Target: **$ARGUMENTS** (a spec file, or the current branch diff if empty).
+
+You are answering one question: **who else breaks if this ships?** Read-only — report, don't fix.
+
+This is the failure an estate actually dies of. A change that is correct inside its own repo and
+still takes down a consumer is not caught by tests, `/code-review`, or `/spec-verify`, because every
+one of those looks only at this repo.
+
+## Step 0 — establish whether you can answer at all
+
+Read `docs/ESTATE.md`. **If it's missing, or its contract index is mostly `_TBD_`, stop and say so
+plainly**: you cannot distinguish "no consumers" from "no index". Recommend `/repo-estate`, and do
+not produce a clean bill of health — a false "nothing affected" here is worse than no answer,
+because it gets believed.
+
+Note which rows are marked `(inferred)`: those were never confirmed against the peer's real code, so
+any conclusion resting on them is a hypothesis, and must be labelled as one in your report.
+
+If this repo has the toolkit's MCP server wired up, `estate_lookup` answers step 2 directly and
+returns which rows are unconfirmed — use it rather than re-parsing the tables by hand.
+
+## Step 1 — find the contracts this change touches
+
+From the diff (`git diff "$(git merge-base HEAD @{u} 2>/dev/null || echo HEAD~1)"...HEAD`) or from
+the spec's §4, identify changes to anything **someone else can observe**:
+
+- **Published event / message payloads** — a field removed or renamed, a type narrowed, a new
+  required field, a changed routing/topic name, changed ordering or idempotency assumptions.
+- **API responses and requests** — a field removed or renamed, a type change, a new required
+  request field, a changed status code, a changed error shape, a new auth requirement.
+- **Shared data** — a table/collection another service reads, a column dropped or renamed, a
+  changed constraint or index another service's queries depend on.
+- **Published packages/types** — a shared library's exported signature.
+
+Purely internal changes (private helpers, tests, this service's own storage that nobody else reads)
+have no ripple. Say that and stop — most changes are this, and inventing ripple is its own failure.
+
+## Step 2 — resolve the consumers
+
+For each touched contract, find it in the `docs/ESTATE.md` contract index and list the services on
+the other side. For each consumer, classify the change:
+
+| Class | Meaning | What it forces |
+|---|---|---|
+| **Additive** | New optional field, new endpoint, new event type | Nothing — deploy in any order |
+| **Compatible-with-sequence** | Consumer must handle both shapes first | A deploy order, and a spec that names it |
+| **Breaking** | Consumer breaks the moment this ships | A migration path: dual-write/dual-read, version the contract, or coordinate a release |
+
+Assume **something you don't control is already calling this**. In-flight messages and old clients
+outlive a deploy; a change that is safe only if every consumer upgrades simultaneously is breaking.
+
+## Step 3 — check the spec covers it (when given a spec)
+
+The spec's **§7 Rollout & risks** must name each affected consumer and the deploy order, and §4.3 /
+§4.4 must describe the contract on both sides. If it doesn't, that's the finding: the ripple was
+designed but not written down, and the person deploying won't know.
+
+## Report
+
+- **Contracts touched** — each with `file:line` and its class (additive / sequenced / breaking).
+- **Consumers affected** — service, what it consumes, and whether the estate row was confirmed or
+  `(inferred)`.
+- **Required deploy order** — as a numbered sequence that is safe at every intermediate step
+  (usually: consumers accept both shapes → producer changes → old path removed later).
+- **Unresolvable** — contracts you could not find a consumer for, and whether that means "nobody
+  consumes it" or "the index doesn't know". Never merge those two.
+- **Spec gaps** — what §7 needs to say and doesn't.
+
+Next: put any breaking finding into the spec (§4 contracts, §7 rollout) via a **Revisions** row
+before building, or — if the code is already written — treat it as a spec gap in `/spec-verify` and
+resolve it with the user before `/pr`.

package/ml-specs/commands/repo-init.md

@@ -0,0 +1,155 @@
+---
+description: Learn the existing project, then scaffold spec-driven development + all Claude knowledge files (CLAUDE.md, docs/, specs/, CI gate)
+argument-hint: (no args) — run from the root of the repo to learn it and set up
+---
+
+You are bootstrapping the **ml-specs** into the current repository. This is a **learn-first**
+command: study the real codebase, extract how it actually works, then generate every Claude
+knowledge file with those findings baked in. Do not produce generic boilerplate — everything you
+write must reflect THIS project and cite real `file:line`.
+
+**First, check this is the right command.** If the repo already has a hand-written `CLAUDE.md`,
+`docs/`, or an existing spec/RFC/ADR practice, stop and recommend **`/repo-adopt`** instead — it
+merges into what's there rather than assuming a blank slate. Only continue here if the knowledge
+layer is genuinely absent or was generated by this toolkit.
+
+The plugin's templates live under `${CLAUDE_PLUGIN_ROOT}/templates/`.
+
+## Phase 1 — LEARN the project (do this before writing anything)
+
+**Delegate the reading.** This is the most expensive phase in the toolkit, and every file read
+here would otherwise sit in your context for the rest of the run — while you are writing docs, not
+reading code. So spawn **scanner** three times **in a single message**, so the three run
+concurrently, one per brief:
+
+1. `stack` — language, package manager, framework, data layer, test layout, and the repo's real
+   build/test/lint/typecheck commands. Tell it to flag whether this is a monorepo/workspace (npm
+   workspaces, pnpm, Nx/Turborepo/Lerna, Maven multi-module, Gradle subprojects, Go workspaces) and,
+   if so, each package's own stack and commands — packages differ, and one root summary hides that.
+2. `structure` — directory layout, entry points, data layer + migrations, config/env handling, test
+   layout, and the bounded contexts/packages with their dependencies.
+3. `patterns` — the actual house style: naming; end-to-end feature layering; data access &
+   migrations; API/DTO contracts and status codes; error handling; validation, config & secrets;
+   logging; testing shape; and inferable anti-patterns.
+
+Each returns a capped findings block of `file:line` citations, not source. Work from those three
+blocks for the rest of this command.
+
+**If a scanner returns thin or contradictory findings**, re-brief that one scanner with a narrower
+scope rather than reading the codebase yourself — the point is that raw file contents never enter
+this context. Reading a *specific* file yourself is fine when a scanner's `NOTES` asks you to
+adjudicate something; re-doing a whole brief inline is not.
+
+Carry every `(inferred)` marker through to Phase 4 — those are what the human must confirm.
+
+## Phase 2 — GENERATE the Claude knowledge files (memory)
+
+Write these so the agents (`coder`, `developer`, `reviewer`, `spec-author`) have durable project memory. Cite real `file:line`;
+do not overwrite a maintained file without saying so — if one exists, merge, and report what changed.
+
+**Token discipline (these files load into context on every task):** be terse and high-signal.
+Reference `file:line` instead of pasting code. Keep `docs/PATTERNS.md` and `docs/ARCHITECTURE.md`
+under ~200 lines each; keep `CLAUDE.md` a thin index (~150 lines) that LINKS to those docs rather
+than inlining them. In a monorepo, prefer per-package sections/files over one fat document.
+
+4. **`docs/PATTERNS.md` — the learned house style (the key new artifact).** Create `docs/` if
+   missing and fill `${CLAUDE_PLUGIN_ROOT}/templates/docs/PATTERNS.template.md` from your Phase 1
+   findings. Keep only sections that apply; every pattern cites a real example. This is the
+   "code patterns" memory new code must match.
+
+5. **`docs/ARCHITECTURE.md` — the structural map.** Fill
+   `${CLAUDE_PLUGIN_ROOT}/templates/docs/ARCHITECTURE.template.md` with this project's real
+   structure, data/persistence, events, external calls, and cross-cutting concerns — per the
+   detected stack (Java/Spring: controllers, `@SqsListener`, `@FeignClient`, repo flavor; Node:
+   routers/modules, services, ORM models & migrations, DB engine; React: routes/pages, components,
+   state, data-fetching). Don't copy the example verbatim.
+   - **Large application (many modules/contexts, or a monorepo)? Shard it.** Don't write one huge
+     file. Make `docs/ARCHITECTURE.md` a small **router** (blurb + a Structure table whose rows link
+     to per-module shards), and generate one `docs/architecture/<module>.md` (≤~150 lines) per
+     bounded context / package. Add `docs/patterns/<module>.md` only where conventions differ by
+     module. This keeps each task's context to the router + the one relevant shard.
+   - **Map the edges, not just the nodes (essential when modules are interlinked).** Give each shard
+     a `## Depends on / Used by` header listing the modules it calls / is called by, each as a
+     one-line contract pointer (event/API/shared type/table → `file:line`). Fill the router's
+     **module contract index** with the shared contracts and their producers/consumers. If the code
+     is heavily coupled, also generate `docs/architecture/_core.md` for the truly shared contracts.
+     Determine edges from real imports/calls/events/shared schemas — don't guess.
+
+6. **`docs/ESTATE.md` — only for a multi-service estate.** If this repo is part of a larger estate
+   (it calls other services, or produces/consumes events), don't hand-write it here — recommend
+   **`/repo-estate`**, which scans the peer repos and fills
+   `${CLAUDE_PLUGIN_ROOT}/templates/docs/ESTATE.template.md` with the real contract index. For a
+   standalone app, SKIP it entirely.
+
+7. **`CLAUDE.md` — the primary project memory.** If absent, run `/init` first for a base. Then
+   ensure it contains the shared sections from `${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.fragment.md`
+   ("Knowledge layer", "Working agreement", "Spec-driven development", "Quality gates"), AND a
+   concise **"Code patterns & conventions"** section that summarizes `docs/PATTERNS.md` in a few
+   lines and **links** to it (don't inline it), plus the accurate stack / build / run / test
+   commands for THIS repo. Keep CLAUDE.md a thin index — the agents read it first on every task, so
+   the learned patterns must be *discoverable* from it, not *embedded* in it.
+
+## Phase 3 — SCAFFOLD the spec workflow
+
+8. **Spec workflow:** create `specs/` if missing and copy in `README.md`, `TEMPLATE.md`, and
+   `AGENTS.md` from `${CLAUDE_PLUGIN_ROOT}/templates/specs/`. Do not overwrite existing specs.
+   `specs/archive/` is created on demand by `/spec-advance` — don't create it empty here.
+
+9. **Line endings:** if the repo has no `.gitattributes`, copy
+   `${CLAUDE_PLUGIN_ROOT}/templates/gitattributes` to `./.gitattributes`, then run
+   `git add --renormalize .` to clear any CRLF/LF phantom diff. Report how many files normalized.
+
+10. **Commit attribution:** merge `${CLAUDE_PLUGIN_ROOT}/templates/settings.json` into
+    `.claude/settings.json` (create it if absent; if it exists, add the `attribution` key and leave
+    every other key alone). Commit it — that is the point: it applies to every teammate who clones
+    the repo, with no per-machine configuration. It makes commits and PRs name the humans who own
+    the change, which `CLAUDE.md` also states, but here it is enforced by Claude Code rather than
+    being an instruction a model has to remember. If the repo already sets `attribution`, leave the
+    existing value and say so.
+
+11. **Architecture standards (optional):** if `ml-skills` is available — the MCP server, or
+    `npx @mlmcps/ml-skills` — copy `${CLAUDE_PLUGIN_ROOT}/templates/standards/.mlskills.json` to the
+    repo root and run `npx @mlmcps/ml-skills check .` once.
+
+    Report the finding count, and report it as a **baseline, not a failure**. Every standard is
+    seeded `proposed`, which means it can only warn and cannot fail anything — that is deliberate.
+    A gate that fails on day one gets disabled on day two, and a repo that has never been checked
+    will have a backlog. Say what the backlog is, say that nothing is enforced yet, and point at
+    the ratification decision as a separate, human step: `npx @mlmcps/ml-skills ratify`.
+
+    Do **not** ratify a standard here. That means someone read the decisions, agreed to them, and
+    accepted that they can now break the build — none of which an init command can do on a team's
+    behalf.
+
+    If ml-skills is not installed, skip this and say so in one line. It is genuinely optional; the
+    rest of the toolkit works without it.
+
+12. **Knowledge-layer CI gate:** copy `${CLAUDE_PLUGIN_ROOT}/templates/ci/knowledge-check.mjs` to
+    `.github/scripts/` and `${CLAUDE_PLUGIN_ROOT}/templates/ci/knowledge-layer.yml` to
+    `.github/workflows/`. It fails a PR when a doc's `file:line` reference points at code that no
+    longer exists — the mechanical half of `/repo-doctor`, which is the half worth automating.
+    Run it once now and report the result. If the repo isn't on GitHub Actions, say so and give the
+    command to wire into whatever CI it does use.
+
+13. **Optional MCP server:** mention that `${CLAUDE_PLUGIN_ROOT}/templates/mcp/.mcp.json` wires this
+    repo to the toolkit's read-only MCP tools (`estate_lookup`, `knowledge_check`, `spec_list`,
+    `spec_next_number`), which non-Claude tools can use too. Do NOT install it automatically — it
+    needs an absolute path to the plugin checkout. Offer it, and only wire it if the user says yes.
+
+14. **Optional hooks:** mention that `${CLAUDE_PLUGIN_ROOT}/templates/hooks/settings.hooks.example.json`
+    has opt-in automation (post-edit format/lint, a pre-PR test reminder). Do NOT install hooks
+    automatically — the commands are project-specific. If the user wants them, copy the chosen hooks
+    into `.claude/settings.json` and replace the commands with this project's real ones. The
+    plugin's own hooks (knowledge-drift warning, secret scan) are already active on install and
+    need nothing here.
+
+## Phase 4 — REPORT
+
+15. Report what was created/skipped/merged, and what the human should review — especially
+    `docs/PATTERNS.md` and `docs/ARCHITECTURE.md` (verify the learned patterns match intent, and
+    correct anything you marked *inferred*). Do NOT commit — leave changes staged/untracked for review.
+
+The agents (`coder`, `spec-author`, `spec-reviewer`, `developer`, `reviewer`,
+`pr-author`) and commands (`/spec` → `/spec-review` → `/spec-build` → `/spec-verify` →
+`/spec-advance` → `/pr`) come from the plugin itself and need no per-repo files — they read the
+generated `CLAUDE.md` + `docs/` to learn this project.

package/ml-specs/commands/repo-refresh.md

@@ -0,0 +1,58 @@
+---
+description: Re-learn what changed since the last refresh and update the Claude knowledge files (docs/, CLAUDE.md) so the agent's memory matches reality
+argument-hint: (no args) — run from the repo root after the codebase has drifted
+---
+
+The project has evolved since `/repo-init` (or the last refresh). Re-learn it and update the
+generated knowledge files so the coding agents' memory stays accurate. The code is the source of
+truth — a stale summary is worse than none.
+
+This is the LEARN + UPDATE half of `/repo-init` (it does NOT re-scaffold `specs/` or
+`.gitattributes`). The plugin's templates live under `${CLAUDE_PLUGIN_ROOT}/templates/`.
+
+Steps:
+
+1. **Scope the re-learn to what actually moved.** A refresh is not a re-init: most of the repo is
+   unchanged, and re-learning all of it is the single most wasteful path in this toolkit. Find the
+   changed surface first — it's cheap and mechanical:
+
+   ```
+   git log -1 --format=%H -- CLAUDE.md docs/            # when the knowledge layer was last updated
+   git diff --name-only <that-sha>..HEAD -- . ':(exclude)docs/*' ':(exclude)*.md'
+   ```
+
+   If that returns nothing, the docs are current — say so and stop. If it returns more than roughly
+   half the repo's source files (or the last-doc commit is unreachable), fall back to a full
+   re-learn and say that you did.
+
+2. **Re-learn, in parallel, scoped to those paths.** Spawn **scanner** agents **in a single
+   message** — one `patterns` and one `structure` brief, each scoped to the changed paths, plus a
+   `stack` brief **only if** the manifest/build file or lockfile is among them (otherwise the stack
+   hasn't moved and re-detecting it is pure cost). Each returns `file:line` findings, not source, so
+   the changed code never lands in this context.
+
+3. **Diff against the existing docs.** Read the current `docs/PATTERNS.md`, `docs/ARCHITECTURE.md`,
+   and the "Code patterns & conventions" section of `CLAUDE.md`. Identify what changed: new
+   modules/endpoints/components, new or changed data models & migrations, new conventions, removed
+   patterns, new dependencies, changed commands.
+
+4. **Update the files in place** (don't blow away human edits — merge and preserve hand-written
+   notes; only correct what's now wrong or missing). Refreshing is also pruning: **delete stale
+   patterns and trim bloat** so each doc stays under its ~200-line budget and `CLAUDE.md` stays a
+   thin index — replace drifted sections, don't just append. Smaller, current memory = fewer tokens
+   every task.
+   - `docs/PATTERNS.md` — refresh the house style from current code.
+   - `docs/ARCHITECTURE.md` — refresh structure, data/persistence, events, external calls.
+   - `CLAUDE.md` — fix the stack/build/run/test commands and the "Code patterns & conventions"
+     summary if they've drifted.
+   - `docs/ESTATE.md` — do NOT rewrite it here. If this repo's cross-service contracts changed
+     (a new client, listener, or published topic), say so and recommend `/repo-estate`, which reads
+     the peer repos to resolve both sides of each edge.
+   - **Sharded (large app):** update ONLY the `docs/architecture/<module>.md` (and
+     `docs/patterns/<module>.md`) shards for modules that changed; add a shard + router row for a
+     new module; remove the row + shard for a deleted one. Don't rewrite untouched shards.
+
+5. **Report a concise changelog** of what you updated (and what you intentionally left), and what
+   the human should review. Do NOT commit — leave changes staged/untracked for review.
+
+If no knowledge files exist yet, tell the user to run `/repo-init` first.

package/ml-specs/commands/repo-rollout.md

@@ -0,0 +1,84 @@
+---
+description: Onboard the toolkit across an estate — survey the repos cheaply, then init/adopt them in reviewed waves rather than all at once
+argument-hint: <parent dir containing the repos, or an explicit list> — e.g. ~/work or ../svc-a ../svc-b
+model: sonnet
+---
+
+Target repos: **$ARGUMENTS**
+
+You are rolling the toolkit out across many repos. The whole job is **aiming the expensive part**.
+
+`/repo-init` is the most costly operation in this toolkit — a full codebase scan. Running it across
+an estate unattended produces a large bill and, worse, a pile of knowledge layers nobody reviewed,
+which is the exact failure the toolkit exists to prevent. So: survey cheaply, onboard deliberately,
+and let the first repo teach you what the rest need.
+
+**Never commit in another repo. Never onboard more than one repo before a human has seen the first
+one's output.**
+
+## Phase 1 — survey (cheap, mechanical, read-only)
+
+1. Run the survey script — no model needed, so this costs almost nothing:
+
+   ```
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/survey-estate.mjs <parent-or-repos>
+   ```
+
+   It classifies each repo as **init** (no knowledge layer, active), **adopt** (has hand-written
+   docs or another tool's agent instructions — `/repo-init` would clobber them), **refresh** (already
+   onboarded), **review** (dormant, or no recognisable manifest), or **skip**. It also counts
+   cross-service edge signals.
+
+2. Relay the table and the per-repo reasons. Flag anything with uncommitted changes — onboard on a
+   clean tree, or the toolkit's diff is tangled with someone's work in progress.
+
+## Phase 2 — agree the order with the human
+
+3. Order by **what onboarding unlocks**, not alphabetically. Repos with the most cross-service edge
+   signals come first: their `docs/ARCHITECTURE.md` is what `/repo-estate` needs to resolve the *other*
+   side of a contract, so onboarding them makes `/repo-impact` answerable for their peers too. A leaf
+   service with no edges can wait.
+
+4. Put the plan to the user with AskUserQuestion: which repos are in the first wave (recommend 1–3),
+   and confirm the **review** ones — dormant or unrecognised repos are a human call, not yours. State
+   the rough cost: one `/repo-init` per repo, larger repos costing more.
+
+## Phase 3 — onboard, one repo at a time
+
+5. **The first repo is a calibration run.** Onboard exactly one, then **stop** and have the human read
+   its generated `CLAUDE.md`, `docs/PATTERNS.md`, and `docs/ARCHITECTURE.md`. Almost always something
+   is systematically off — a convention mislabelled, the wrong build command, too much detail in the
+   thin index. Fixing that once, before repo two, is the difference between 17 good knowledge layers
+   and 17 copies of the same mistake.
+
+6. For each repo in the wave, in its own directory:
+   - `action: init` → run `/repo-init`'s procedure there.
+   - `action: adopt` → run `/repo-adopt`'s procedure instead. **Never `/repo-init` a repo with existing
+     docs** — clobbering documentation a team wrote is how a tool gets banned.
+   - Leave every change **uncommitted**. Report the file list per repo. The human commits.
+   - If a repo turns out to be something other than a service (a library, a config repo, an
+     archive), stop and say so rather than generating a knowledge layer for it.
+
+7. Between repos, carry forward what you learned: if repo one's `PATTERNS.md` needed the same
+   correction twice, apply it from the start in repo three.
+
+## Phase 4 — make the estate index real
+
+8. Once **two or more** repos are onboarded, run `/repo-estate` from one of them. Before this, the
+   contract index is mostly `_TBD_` and `/repo-impact` correctly refuses to answer; after it, both
+   start returning real consumers. This is the payoff for the whole rollout — don't skip it because
+   the individual repos "look done".
+
+## Phase 5 — report
+
+9. Report: repos onboarded, repos deliberately skipped **and why**, repos still pending, what the
+   human must review first (the `(inferred)` patterns), and the next wave. Be explicit about what
+   was NOT done — a rollout that silently stops at 4 of 17 and reads as finished is worse than one
+   that says "13 remain".
+
+10. Re-running this command is how you resume: the survey re-derives every repo's state from what's
+    on disk, so onboarded repos show as `refresh` and drop out of the queue. There is no ledger to
+    go stale.
+
+Related: `/repo-init` (one repo, greenfield) · `/repo-adopt` (one repo, existing docs) ·
+`/repo-estate` (the contract index) · `/repo-doctor` (drift, per repo).

package/ml-specs/commands/repo-status.md

@@ -0,0 +1,59 @@
+---
+description: Dashboard of the specs under specs/ — lifecycle status, acceptance-criteria progress, and branch — read-only, summarizes rather than dumping
+argument-hint: (no args) for the default view · `all` for every row · a status (e.g. `Draft`) to filter
+model: haiku
+---
+
+Give the user a read-only view of **what's in flight**. Do NOT edit anything.
+
+Filter/mode: **$ARGUMENTS**
+
+## Get the data cheaply
+
+If this repo has the toolkit's MCP server wired up, call **`spec_list`** — it parses every spec
+locally and returns structured data, which is far cheaper than reading the files into context.
+Otherwise read `specs/NNNN-*.md` headers yourself (ignore `README.md`, `TEMPLATE.md`, `AGENTS.md`;
+`specs/archive/` is a count, not rows).
+
+Per spec: number & slug, Status, acceptance criteria checked/total, and Branch — the header's
+**Branch** row if present, else a best-effort match against `git branch --all` shown with `?` to
+mark it a guess.
+
+## Choose the view by size — this matters
+
+A mature repo can hold **hundreds** of specs. Rendering every row is unreadable and expensive, and
+it buries the handful of things that actually need a decision.
+
+- **≤ 25 specs, or the user asked for `all`** → the full table, sorted by number:
+
+  | Spec | Status | AC | Branch |
+  |------|--------|----|--------|
+  | 0001-add-coupon-expiry | Implemented | 4/4 | feat/0001-coupon-expiry |
+
+- **More than that** → **summarize, don't dump.** Lead with counts by status and overall
+  acceptance-criteria completion, then table **only the specs that need attention** (below).
+  Say how many rows you're not showing and how to see them (`/repo-status all`, or
+  `/repo-status Draft` to filter).
+
+## Needs attention
+
+This is the actual output — the rest is context. Table only these:
+
+- `Implemented` with unchecked criteria, or a §6 test named that doesn't exist on disk.
+- `Draft`/`Approved` with no branch (nothing started), or a branch with `Draft` status (work
+  started before the contract was agreed).
+- `Verified` whose branch is already merged → should be `/spec-advance … Archived`.
+- **A Status that isn't one of `Draft`/`Approved`/`Implemented`/`Verified`/`Archived`** — free-text
+  prose in that field means `/spec-advance` and `spec_list` can't read it. Report the count; if it's
+  more than a few, point at `scripts/fix-specs.mjs`, which normalizes them in one pass and preserves
+  the prose.
+- **Duplicate spec numbers** — two files sharing an id is a merge hazard. Same script repairs it.
+
+## Close
+
+End with the single most useful next action for whatever is most in-flight — `/spec-review` a draft,
+`/spec-advance` an approved-in-conversation one, `/spec-build` an `Approved` one, `/spec-verify` an
+`Implemented` one, `/pr` a `Verified` one, `/spec-advance … Archived` a merged one. One line, not a
+menu.
+
+Read-only. Every status *write* goes through `/spec-advance`, never this command.

package/ml-specs/commands/spec-advance.md

@@ -0,0 +1,81 @@
+---
+description: Advance a spec's lifecycle status (Draft → Approved → Implemented → Verified → Archived) — each transition gated on real evidence, archives merged specs
+argument-hint: <path to spec file> [target status] — e.g. specs/0001-foo.md Verified
+model: sonnet
+---
+
+Spec: **$ARGUMENTS** (path, then optionally the target status — if no status is given, advance to
+the next one in the lifecycle).
+
+This is the **only** command that writes a spec's Status. It exists because a status is a claim
+about reality, and a claim nobody checks is worth nothing: `Verified` must mean the suite actually
+ran green, not that an agent felt done.
+
+## What you may edit
+
+The spec's **header table** (Status, Branch, Date), its **Revisions** table, and its
+**acceptance-criteria checkboxes** — nothing else. Never touch code, never commit, never edit
+another spec.
+
+## Procedure
+
+1. Read the spec. Record its current Status and the current branch
+   (`git rev-parse --abbrev-ref HEAD`). Determine the target status: the argument if given,
+   otherwise the next one in `Draft → Approved → Implemented → Verified → Archived`.
+
+2. **Run the mechanical half of the gate first:**
+
+   ```
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/spec-gate.mjs <spec-file> --to <target>
+   ```
+
+   It checks exactly what a script can check exactly: lifecycle ordering, leftover `<placeholder>`
+   text, whether every acceptance criterion is ticked, whether **every test file named in the §6
+   table actually exists on disk**, and whether the recorded branch is merged. It prints `PASS` /
+   `FAIL` / `MANUAL` per gate and exits non-zero on any `FAIL`. Trust its `FAIL`s — do not re-derive
+   them by hand, and do not argue with them.
+
+3. **Then judge the `MANUAL` gates yourself — below. Gather that evidence yourself; do not take the
+   user's or another agent's word for it.** These are the ones no script can settle: whether the
+   human approved in this conversation, whether a §8 question is blocking, whether `/spec-verify`
+   was clean, and whether the §6.1 suite actually ran green.
+
+   For the `Verified` gate, one of those is now mechanical too — call **`verify_evidence`** on the
+   `ml-skills` MCP server with `base` set to the branch this work forked from, and read its
+   `verdict` rather than re-deriving one. It already draws the distinction this transition turns
+   on: `fail` blocks, `pass` clears, `partial` means a requested checker never ran, and
+   **`inconclusive` means clean but nothing was ratified, so nothing could have failed**. Only
+   `pass` clears this gate on its own; on `partial` or `inconclusive`, record the transition only
+   with the gap stated in the same breath. Fall back to `npx @mlmcps/ml-skills check . --json` (or
+   `check_repo`) if the tool is unavailable: there, `summary.errors` must be 0 and
+   `summary.proposedSkills` names the standards that were **incapable** of failing. If most
+   standards are unratified, say so when you record the
+   the person reading the status later deserves to know which one they are getting.
+
+   If ml-skills is not installed, that gate is **unavailable**, not passed. Record it as such.
+
+4. **If the evidence isn't there, do not write the status.** Report exactly which gate failed, what
+   is missing, and the one command that produces it. A refused transition is a successful run of
+   this command.
+
+5. If it passes: update Status, set/refresh the **Branch** row from the current branch, update the
+   **Date**, and tick any acceptance criteria you confirmed. Report the transition in one line.
+
+## The gates
+
+| Transition | Required evidence |
+|---|---|
+| `Draft` → `Approved` | The human approves **in this conversation** — ask if they haven't. Section 8 holds no blocking questions (an answer that would change an API shape, data model, error code, scope boundary, or compatibility). No `<placeholder>` text left in filled sections. If the spec hasn't had an adversarial pass, run `/spec-review` first. |
+| `Approved` → `Implemented` | Every acceptance criterion is checked, and each row of the §6 test-plan table names a test file/method that **exists on disk** — `spec-gate.mjs` checks both; a named-but-missing test is the most common lie here. Normally `/spec-build` makes this transition itself. |
+| `Implemented` → `Verified` | A clean **`/spec-verify`** — the `reviewer` agent marked every criterion satisfied, with a functional/E2E test for each user-facing or contract-level one — **and** the §6.1 full suite green end to end, **and** no new error-severity finding from the architecture standards (`ml-skills check`, if the repo has a `.mlskills.json`). If any of those did not happen in this session, run them now; if a suite or the standards check can't be run here, say so and refuse the transition. Never set `Verified` on assertion. |
+| `Verified` → `Archived` | The spec's branch is merged into the default branch — `spec-gate.mjs` checks `git branch --merged`; if the PR merged but the local branch is behind, fetch first rather than overriding it. Then `git mv` the file to `specs/archive/NNNN-slug.md` — keep the number, create `specs/archive/` if absent — and fix any relative links that pointed at it. Numbers are never reused. |
+
+**Moving backwards** (e.g. `Implemented` → `Draft` because the contract changed) is allowed and
+sometimes correct. It needs no evidence gate, but it **must** add a **Revisions** row saying what
+changed and why, and it un-ticks the acceptance criteria that no longer hold.
+
+**Skipping a status** is not allowed — run the gates in order. If the user asks to jump straight to
+`Verified`, walk each intervening gate and report the first one that fails.
+
+Next step after a successful transition: `Approved` → `/spec-build <spec-file>` ·
+`Implemented` → `/spec-verify <spec-file>` · `Verified` → `/pr <spec-file>` · `Archived` → done.