Release v0.10.0: spec schema 0.2, one compiled model, portable attestation

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "claude-code",
       "source": "./plugins/claude-code",
       "description": "Reference implementation of the Ironclad standard — multi-agent dev harness for Claude Code.",
-      "version": "0.9.4",
+      "version": "0.10.0",
       "author": {
         "name": "qwerfunch"
       },

.gitattributes

@@ -1 +1,2 @@
 spec/index.yaml merge=union
+plugins/claude-code/dist/clad.js whitespace=-trailing-space

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This file is the cross-tool entry point for any AI coding agent working on cladding (OpenAI Codex, Cursor, Cline, Aider, Continue, GitHub Copilot, Gemini CLI, JetBrains Junie, Windsurf, and the other tools that read the [agents.md](https://agents.md/) standard). Claude Code reads this too — there is no separate CLAUDE.md.
+This file is the shared cross-tool entry point for AI coding agents working on cladding (OpenAI Codex, Cursor, Cline, Aider, Continue, GitHub Copilot, Gemini CLI, JetBrains Junie, Windsurf, and other [agents.md](https://agents.md/) hosts). [`CLAUDE.md`](CLAUDE.md) is the Claude Code maintainer addendum; it does not replace this shared contract or `GOVERNANCE.md`.
 
 ## 1. Project
 
@@ -41,11 +41,11 @@ Comment policy in one paragraph: *why* over *what*, full doc-tag set on every ex
 
 ## 5. PR policy
 
-Branch off `develop`, never `main`. Open the PR against `develop`. The maintainer fast-forwards `main` only at explicit release time. Full contract: `GOVERNANCE.md` §4.3.
+Branch off `develop`, never `main`, and open ordinary PRs against `develop`. A release uses a `develop → main` PR merged with a merge commit, followed by the mandatory `main → develop` back-merge. Full contract: `GOVERNANCE.md` §3–4.3 and `CLAUDE.md`.
 
 ## 6. Agent personas
 
-cladding ships five persona definitions under `src/agents/`. **Planning intents** (deciding scope · drafting acceptance criteria · drawing a roadmap) are planner-territory (the persona formerly named `librarian`) and surface through natural language to the host AI tool, not through a fixed CLI verb. `clad run` (formerly `drive`) is for *executing* an already-defined plan as a feature group, not for *making* a plan.
+cladding ships five persona definitions under `src/agents/`. **Planning intents** (deciding scope · drafting acceptance criteria · drawing a roadmap) are planner-territory (the persona formerly named `librarian`) and surface through natural language to the host AI tool, not through a fixed CLI verb. Execution itself is no longer a cladding verb: 0.10.0 retired the headless loop, so `clad serve` publishes the spec and the gates over MCP and the host AI owns carrying an already-defined plan out.
 
 Each file is markdown with a YAML frontmatter that declares two parallel keys:
 
@@ -58,19 +58,20 @@ Non-Claude-Code hosts (Cursor, Cline, Continue, …) should map `capabilities:`
 
 cladding does **not** require an API key by default. The default agent dispatch mode is `host` — cladding runs inside the user's existing AI tool (Claude Code with the Max/Pro subscription, Cursor, Cline, Continue, generic-MCP, …) and the host environment handles the LLM call.
 
-SDK adapters (Anthropic / OpenAI / Gemini) read their respective environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`) only when explicitly selected via `agent.mode = sdk` in `.cladding/config.yaml` or the `CLADDING_AGENT_MODE` env var. Full roadmap: `docs/multi-provider-roadmap.md`.
+The only place cladding itself reads a provider key is the onboarding scan fallback: `src/cli/scan/dispatcher.ts` lazily requires `@anthropic-ai/sdk` with `ANTHROPIC_API_KEY` when no host sampling server is registered. Every other execution path is owned by the host AI. Full roadmap: `docs/multi-provider-roadmap.md`.
 
 ## 8. Soft Shell rule
 
 User-facing output uses business language: feature titles ("Login flow"), stage names ("Drift", "UAT"), plain sentences. Internal identifiers (`F-NNN`, `AC-NNN`, `stage_X.Y`, `HUMAN_REQUIRED` and the rest of the halt enum) belong in the audit log and behind `--internal` / `--json` flags.
 
-Convert every internal id at the user surface boundary via `src/ui/softShell.ts`: `featureLabel(featureId, spec)`, `haltMessage(haltReason, spec)`, `gateLabel(stageId)`. Background: `ironclad-design/03-ux-routing.md` §1.2 and `docs/ux-routing-coverage.md`.
+Convert every internal id at the user surface boundary via `src/ui/softShell.ts`: `featureLabel(featureId, spec)` and `gateLabel(stageId)`. Background: `ironclad-design/03-ux-routing.md` §1.2 and `docs/ux-routing-coverage.md`.
 
 ## 9. Where to look
 
 - `GOVERNANCE.md` — sync policy, versioning, contributor policy, PR contract, v1.0 graduation criteria.
 - `CONTRIBUTING.md` — first-PR walkthrough.
 - `CODE_OF_CONDUCT.md`, `SECURITY.md` — community standards + private security reports.
+- `docs/design/spec-0.2.md` — accepted 0.10.0 continuation router; read it, then load only the task-routed canonical file under `docs/design/spec-0.2/` (implementation is still pending).
 - `docs/code-style.md` — per-language Google Style Guides table + comment policy in full.
 - `docs/ux-routing-coverage.md` — applied-status of `ironclad-design/03-ux-routing.md` prescriptions.
 - `docs/multi-provider-roadmap.md` — host vs sdk adapter model + adapter matrix + how to add one.

CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to Cladding are documented here.
 Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
 Versioning: [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] — Every acceptance criterion has an address a test can claim (2026-09-10)
+
+**In one line:** Spec schema 0.2 — a feature says what it is for before what it does, every acceptance criterion has an address you can point at, a test claims a criterion by naming it in its own title, one compiled model answers questions about how the pieces relate, each level of assurance has a named check profile recorded in a new attestation format, and a reviewed path carries an old project across.
+
+> Heads-up: a project still on the old spec format should commit its work first — the migration refuses to touch a path with uncommitted changes on it — then run `clad migrate --to 0.2` to preview the rewrite, apply it once the decisions it lists have been reviewed, and re-prove the tree with `clad check --tier=pre-push`. One of those decisions asks whether your already-completed features may carry their existing proof forward. Answer no and they carry nothing: each finished feature stays red until one of its test titles names the criterion it covers. That answer is recorded once — changing your mind means undoing the migration and applying it again. The headless loop is gone — start the server with `clad serve` and let your AI host work the feature cycle. Moving the generated files into one folder is opt-in through `clad relocate-generated`; leave it alone and the existing layout keeps working. And the pre-push check rewrites the sealed record of what was verified every time it passes, so commit those files along with your change. One detail worth knowing before you write tests: the tag that says which acceptance criterion a test covers has to come at the very start of the test's title — a tag placed anywhere else in the title is not read, and the criterion it names is still counted as unproven.
+
+### Added
+
+- **Spec schema 0.2.** A feature states its purpose first, every acceptance criterion carries an address you can point at, and a test claims a criterion by naming it in the test title. Behind that: a compiler with typed registries and a typed reader, transactional spec editing, a preview of the migration from 0.1, a kernel that carries proof and portable evidence, and five verification profiles — feedback, checkpoint, completion, push, release — recorded in a third-generation attestation file.
+- **One compiled model now answers the questions that used to be asked of four,** with layers for what the spec declares, what the documents link, what the source references, and which tests the current gate actually observed. The gate now hands the graph a sealed record of test cases instead of raw report bytes.
+- **The count sync covers feature counts too.** `node scripts/test-count.mjs --write` refreshes the README feature totals alongside the test totals.
+- **`clad relocate-generated` moves the generated files under `spec/generated/`.** It previews the move by default; `--apply` performs it as one recoverable transaction. This is opt-in — the layout you have today stays fully supported.
+- **A schema 0.2 workspace explains its own generated files.** `spec/generated/README.md` is projected from the registry of generated artifacts and names where each one lives now and where relocation would put it.
+- **A release gate for the 0.2 validation work.** The validation ledger declares which scenarios block the 0.10.0 release, and `npm run validate:spec-0.2:release` exits nonzero while any of them lacks discriminating evidence. Evidence produced on a reference host counts only when its recorded receipt is signed by an issuer registered in the trust snapshot stored beside it. Both reference-host cycles for this release — one on Claude Code, one on Codex — were driven by automation rather than by a person working at a keyboard, and the confirmation step before each sign-off was answered by that automation on the maintainer's instruction. The signatures and the offline verification are real; what was not exercised, and so is not claimed, is either host's own confirmation form.
+- **The release was measured against the engine it replaces, and against no engine at all.** Three arms ran the same task on the same host and the same model, three times each: an assistant with no engine, released 0.9.4, and this build. On the deterministic table, 0.9.4 lets a warning-level drift finding through a gate that was not asked to be strict, accepts an acceptance criterion with no statement, and accepts the binding field this release no longer reads — this release refuses all three, and lowers the depth ceiling on graph questions, refusing requests above it. Live, both engines carried the work to an honest finish 3 of 3, at a median estimated $1.00 against $1.23 and 21 turns against 27; those are list-price estimates, not amounts billed. Code quality, coverage and a hidden oracle came out the same across all three arms, so this release claims no better code. The record is `docs/ab-evaluation/case-version-abc-094-vs-0100.md`.
+
+### Changed
+
+- **Completeness is judged from structure alone.** Scope and closure derive from structural relations; an unresolved piece of evidence or an oracle reference that does not resolve stays a visible negative fact about its own criterion instead of making every verification profile unresolved.
+- **The authoritative profiles block on warnings.** Completion, push and release refuse on warn-level drift findings; `--strict` remains an explicit escalation on top.
+- **A project's own instructions now say how a test claims a criterion.** The managed sections in `AGENTS.md` and `CLAUDE.md`, the gate's report of a criterion nothing has proven, the guidance it prints when tests are missing, and the message that refuses the old way of binding all name the same thing: on the new spec format, a test claims a criterion by carrying that criterion's tag at the very start of its own title. Until now those surfaces still described the previous format's way of doing it, so a project on the new format was being told to do something the gate no longer reads. A project still on the old format sees its wording unchanged, byte for byte.
+- **An archived feature whose successor is not done yet** reports its surviving modules as information rather than a problem, until that successor completes.
+- **`clad done` reports how independently the work was verified.** In a schema 0.2 workspace it states the independence label recorded for that completion. By default the label only annotates; set `independence_policy: require` and it decides — a sign-off by the person who implemented the feature no longer counts as independent review, and a completion whose authors cannot be identified is refused rather than passed. The old spec format keeps its previous label unchanged.
+
+### Removed
+
+- **The experimental headless loop and its `run` command.** Nothing ever ran it — three and a half months of recorded sessions contain zero runs — and it never learned to write code, so it could only report honest failure. Start the server with `clad serve` and let your AI host work the feature cycle instead; that is the path everything else already used.
+- **The parts that existed only to serve that loop:** the agent adapters, the crash-postmortem recorder, and the progress-line renderer. The host transport the onboarding scan uses is untouched, and so is the Anthropic SDK dependency behind its API-key fallback.
+- **The `run` skill,** and its copies in the Claude Code, Codex, and Antigravity plugin folders.
+
+### Fixed
+
+- **The host support table was refreshed against live runs for this release.** Claude Code, Codex and Cursor answered every check — Cursor, which the readme had not claimed before, is now recorded as working. Gemini still fails, and Antigravity — which the table previously recorded as working — now times out on every check, so the readme no longer claims it as verified.
+- **Graph code no longer reaches into gate code,** restoring the architecture rule that keeps the two apart.
+- **A renamed test keeps its binding.** Bindings carried forward by the migration and then invalidated by a title edit are promoted to live tokens instead of failing silently.
+- **Patched dependencies.** The MCP SDK's transitive `fast-uri`, `qs`, and `side-channel` packages move to their patched releases, so `npm audit` reports no known vulnerabilities. A later batch, reported on 2026-09-09, moves the web framework the MCP server carries and the YAML reader and test runner used by the development tools to their patched releases as well, so the audit stays clean.
+- **A workspace holding a signed review could never record a verification.** The gate sealed the record of what it verified without counting the reviews on disk, while the writer counted them, so the two never matched: the check finished green, wrote nothing, said nothing, and `clad done` refused with a cause it could not name. Both now read the same set, the freshness check reads it too, and a refusal names the guard that refused.
+- **Asking for a different level of assurance for one run now says why it was refused.** Requesting a level the project does not allow — anything below the level it is set to, or a stronger one anywhere except a single feature's completion check — used to end in a red result with no cause printed anywhere, every check apparently green. The refusal now names its reason before anything runs; a run without the option is untouched.
+- **A receipt imported on the command line is now checked against the project's registered signers,** exactly the way it is when your AI host imports one. Until now every receipt was filed as an unverified claim, whether it was genuine, altered, or signed by someone the project never registered — an altered one is now refused and nothing is stored.
+- **An attestation stamped on a working machine now matches the one a clean checkout computes.** A desktop metadata file left behind by a file browser, or an ignored fixture sitting inside a sealed folder, used to be sealed alongside the project's own files, so the record a green local check wrote was already stale on every other machine — most visibly in continuous integration, where the same commit came back red. The record now covers what the repository actually tracks, so a check that passes on your machine passes on a fresh clone. Files kept inside a nested repository or a submodule are not part of that tracked content either, so a module pointing into one is now treated as absent and the check refuses rather than sealing foreign files.
+
 ## [0.9.4] — The gate judges the sources on disk (2026-08-26)
 
 **In one line:** the language check reads your sources instead of your build manifest — projects it wrongly blocked now pass honestly — the module-honesty scan works for any language your spec teaches it, the gate config survives a fresh clone, and cladding now proves its own host hooks fired, records stop and completion outcomes, pins generated CI, and stamps every verified tree with the policy that earned it.

CLAUDE.md

@@ -10,8 +10,8 @@ When adding a new spec entry to `spec/features/` or `spec/scenarios/`:
 
 - **DO NOT** create `spec/features/F-NNN.yaml` (the legacy sequential format) by hand.
 - **DO** use the hash-based model:
-  - Filename: `<slug>-<hash>.yaml` (e.g. `auth-bypass-c4d108e9.yaml`)
-  - Inside the yaml: `id: F-<hash>` plus `slug: <slug>`
+  - Filename: `<slug>-<hash8>.yaml` (e.g. `auth-bypass-c4d108e9.yaml`)
+  - Inside the yaml: `id: F-<hash8>` plus `slug: <slug>`
   - The hash is an 8-character hex string since 0.6.0 (legacy 6-char ids stay valid). Generate with:
     ```bash
     node -e "console.log('F-' + require('node:crypto').randomBytes(4).toString('hex'))"
@@ -101,8 +101,10 @@ implements; whoever authors a unit must not sign off on it (anti-self-cert).
 **Feature cycle — one at a time** — One feature end-to-end before the next:
 author its spec entry (`acceptance_criteria` + `modules`) → implement → author tests
 in a separate context → `clad done <featureId>` (sets `status: done` only when
-`clad check --tier=pre-push --strict` is GREEN). Never author spec entries ahead of
-their code, or hand-write `status: done`. See `docs/feature-cycle.md`.
+`clad check --tier=pre-push --strict` is GREEN). A test claims a criterion by
+starting its title with `[covers:F-…/AC-…]`; `test_refs` are not accepted on
+schema 0.2. Never author spec entries ahead of their code, or hand-write
+`status: done`. See `docs/feature-cycle.md`.
 
 **Hash-based IDs** — Never hand-author `F-NNN` filenames; use the `clad` CLI
 (or `/cladding:init`). Model in `docs/spec-ids-multi-dev.md`.

CONTRIBUTING.md

@@ -18,7 +18,7 @@ Thanks for your interest in helping make code iron-clad.
    ```
    When you change a stage, a detector, or the conformance contract, also run `npm run conformance` to re-verify the 26 fixtures. The runner is a contributor self-audit tool — it depends on dev-only toolchain binaries (`tsc` / `eslint` / `madge` / `secretlint` / `vitest`), so it works after a contributor install (`npm install`), **not** after the end-user install (`npm install -g cladding`).
 5. **Add a CHANGELOG entry** under the next-release heading, in the right [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) section (`Added` / `Changed` / `Deprecated` / `Removed` / `Fixed` / `Security`).
-6. **Open the PR against `develop`.** The maintainer fast-forwards `main` only at release time.
+6. **Open the PR against `develop`.** Releases use a `develop → main` merge-commit PR followed by a mandatory `main → develop` back-merge; see `GOVERNANCE.md` §3.
 
 ## What kind of contributions land easily