@ikon85/agent-workflow-kit 0.32.0 → 0.33.0

package/.claude/skills/orchestrate-wave/SKILL.md

@@ -81,10 +81,10 @@ node scripts/readiness.mjs check --skill orchestrate-wave --json
   - **Plan-level error** (integration/verify reveals a wrong LOCKED decision, not a
     slice bug): STOP the wave. No improvised redesign AFK — keep worktrees intact,
     report findings + options.
-  - **On ANY wave STOP/abort:** if this run planted the active-wave claim, remove
-    exactly that claim as part of shutdown. Never delete a claim marker observed
-    during a preflight collision, nor any sibling/foreign wave marker — those are
-    owned by another run. A stale marker owned by this run would block a safe retry.
+  - **On ANY wave STOP/abort:** if this run planted the active-wave claim, release
+    it via `releaseWaveClaim` with this run's owner as part of shutdown — it
+    refuses a foreign payload. Never delete a claim marker observed during a
+    preflight collision. A stale own marker would block a safe retry.
 - **Routing = one axis: how expensive is a wrong result to catch?** Mechanically
   caught (test/screenshot/lint) → default tier at medium/low effort; plausible-but-
   wrong / subtle logic / architecture → top tier at high effort + main-thread
@@ -95,6 +95,24 @@ node scripts/readiness.mjs check --skill orchestrate-wave --json
   first red test). The same axis sets how hard you re-verify. Borderline → default
   tier + re-verify beats blanket top tier.
 
+## Orchestration mechanics
+
+Pass only host-supplied inventory through `capabilityAdapter.claude` or `.codex`,
+then call the selector. It returns exactly one target; missing or `unknown` evidence
+degrades A → B → C. A model claim is not evidence; do not emulate a missing primitive.
+
+- **Path A:** requires the literal `Workflow` tool, callable and permitted, plus
+  individually proven named phases, run identity, runtime output validation,
+  journal, and resume. Then read [its recipe](references/dispatch-workflow.md).
+- **Path B:** requires proven native spawn, wait, and aggregate plus effective
+  concurrency and thread capacity ≥2. Then read [its recipe](references/dispatch-subagents.md).
+- **Path C:** keep recon and building direct and serial in the main thread. Produce
+  the same FILE → SLICES evidence, create each worktree from the integrated base,
+  apply the builder contract, validate the result, then continue. Load no reference.
+
+Phases 0 and 3–6 always remain in the main thread. Visible fan-out progress may
+replace the ~30-second heartbeat; otherwise the standing heartbeat remains required.
+
 ## Phase 0 — Setup
 
 1. **Read everything**: the anchor body, every sub-issue body (each has a Handoff
@@ -106,15 +124,15 @@ node scripts/readiness.mjs check --skill orchestrate-wave --json
    preflight's single degraded summary is the only warning. Never guess a project
    command, tunnel, login, or verify recipe.
 3. **Preflight — refuse a wave already in flight, otherwise claim it.** Before
-   dispatch, inspect all three same-machine collision signals: **(a)** an existing
-   `wave-active/<anchor>` tag; **(b)** any slice branch ahead of the wave's current
-   base (`git rev-list --count <base>..<slice-branch>` > 0); **(c)** uncommitted
-   changes in any slice worktree (`git -C <worktree> status --porcelain` non-empty).
-   A hit not created by this run means another session may be building the wave:
-   **STOP**, report the exact tag/branch/worktree, and do not touch it. If clean,
-   record that this run owns the claim and plant a LOCAL annotated tag:
-   `git tag -a wave-active/<anchor> -m "orchestrating since <UTC timestamp>;
-   slices: <slice-branches>"`. It is local coordination state — never push it.
+   dispatch, inspect the two same-machine work signals: **(a)** any slice branch
+   ahead of the wave's current base (`git rev-list --count <base>..<slice-branch>`
+   > 0); **(b)** uncommitted changes in any slice worktree (`git -C <worktree>
+   status --porcelain` non-empty). Acquire the claim itself through `claimWave`
+   from `src/lib/waveClaim.mjs`: a compare-and-set on the `wave-active/<anchor>`
+   LOCAL annotated tag, so two sessions racing one wave cannot both win. Either
+   `acquired: false` or a work signal you did not create means another session
+   owns the wave — **STOP**, report the returned `claim.owner` plus the exact
+   branch/worktree, touch nothing. Local coordination state — never push the tag.
 4. **Wave worktree**: reuse the planning worktree (never re-create; the handoff
    points there). Bring its branch to current `main`:
    `git -C <wave> merge --ff-only origin/main` (if your repo guards destructive
@@ -132,17 +150,10 @@ preflight clean + this run's local claim planted · wave branch ff'd to
 
 ## Phase 1 — Disjointness recon (the load-bearing step)
 
-Zero merge conflicts later depends entirely on getting this right.
-
-- Delegate to a read-only investigator agent: for EACH slice the exact file path of
-  every named component + resolve ambiguous targets, then a **FILE → SLICES** table
-  listing every file that appears in ≥2 slices.
-- Build the **overlap graph**. Identify the **conflict hub** (the slice whose new
-  artifacts other slices reuse). **Build the hub first**, merge it, THEN the
-  dependents stop conflicting.
-- Cut into **waves of fully file-disjoint slices**. Edited-by-≥2 = serialize across
-  waves; only-shared-via-import = safe. A new primitive edited by one slice but
-  *consumed* by others is NOT a conflict.
+Phase 1 uses the selected orchestration mechanics. Resolve every named component,
+produce the **FILE → SLICES** table and overlap graph, then build the conflict hub
+before its dependents. Cut fully file-disjoint waves; shared imports are safe, but
+files edited by multiple slices serialize across waves.
 - **Native blocking edges are the frontier authority.** Read the anchor's
   buildable frontier from the tracker's native issue dependencies:
   `python3 scripts/board-sync.py frontier <anchor#>` → `FREI` / `BLOCKED by #…` /
@@ -151,15 +162,11 @@ Zero merge conflicts later depends entirely on getting this right.
   body text or table order alone. The frontier must AGREE with your Phase-1
   dependency order; a contradiction is a plan finding to reconcile before dispatch,
   not a detail.
-- **Reconcile contradictory sub-issue ACs against the plan BEFORE dispatch — the
-  plan is authority.** `to-issues` cuts slices independently, so a shared
-  append-only file (a query-key registry, a barrel, a shared types module) is often
-  claimed by *every* slice, with duplicate/clashing adds. **The hub slice OWNS the
-  shared-mutable file: it pre-adds ALL the wave's keys/types/helpers; dependents
-  CONSUME only and never touch it.** Embed verbatim in each dependent's contract:
-  "X already exists in `<file>` — do NOT add it, consume only." (Real case: all 14
-  sub-issues claimed the same registry adds + 4 contradictions — hub expanded to
-  own all 20 keys, batch merged conflict-free.)
+- **Reconcile contradictory sub-issue ACs against the plan BEFORE dispatch.** Safe
+  declaration-only registries may be predeclared by one hub; eager/validated
+  registries that read targets must serialize helper-owning slices through
+  dependency edges, each appending only its own existing artifact after creation.
+  Both preserve one owner per shared edit and the no-conflict invariant.
 - **Retirement slices require a valid topological deletion order.** Before
   dispatching slices that delete a legacy cluster, map every to-delete module's
   production importers and build the cluster's internal import graph. Order the
@@ -168,25 +175,19 @@ Zero merge conflicts later depends entirely on getting this right.
   deletions form a cycle, separate each-slice-green steps are impossible: combine
   the whole cycle into ONE atomic slice instead of landing dangling imports.
 
-**Done when:** FILE→SLICES table exists · every ≥2-slice file has exactly ONE
-owning slice · disjoint waves cut in dependency order · every dependent contract
-carries its verbatim consume-only lines.
+**Done when:** FILE→SLICES table exists · each shared file has either one
+declaration-only owner with verbatim consume-only dependents, or an explicit serialized
+owner sequence for eager/validated additions where each owner appends only its own existing artifact · disjoint waves cut in dependency order.
 
 ## Phase 2 — Dispatch one wave in parallel (isolated worktree per implementer)
 
-Phase 2+3 repeat **per disjoint wave** from Phase 1 — the conflict-hub wave first.
-Within ONE wave, all slices dispatch at once. **Dispatch only `FREI` slices** —
-re-read the native frontier (`frontier <anchor#>`) before each wave; a
-gate-before-build edge clears only when its blocker actually lands (never
-"unblock" by editing body text — remove the edge via `dep-remove` if the plan
-genuinely changed). Two per-slice calls first: **(a)
-inline vs delegate** — a tiny mechanical bit (a rename, a 1-2-line tweak) you do
-yourself — and **(b) tier + effort** (Standing rules → Routing). For each
-delegated slice:
-
-- **One worktree per agent** off the wave-branch HEAD, own index so parallel agents
-  never share a git index. Use your project's worktree-setup command (`§Setup`),
-  else plain `git worktree add <path> -b feat/<anchor>-<slug>`.
+Phase 2 uses the selected orchestration mechanics, repeating with Phase 3 per
+disjoint wave, conflict hub first. Dispatch only `FREI` slices: re-read
+`frontier <anchor#>` before each wave and clear changed edges only via `dep-remove`.
+Before each slice, bind **(a) inline vs delegate** and **(b) tier + effort** under
+Standing rules. Tiny mechanical work may stay inline.
+For Path A/B, create one worktree per agent from wave HEAD, using `§Setup` or
+`git worktree add <path> -b feat/<anchor>-<slug>`.
 - **Build the prompt from [`references/builder-contract.md`](references/builder-contract.md)**
   — fill the slots with the slice's VERBATIM What+AC, plan decision, recon
   file:line map and consume-only lines; never paraphrase (paraphrase drift has
@@ -201,8 +202,7 @@ package tests + green fast gate (`§Builder Commands`) — or a STOP item you re
 
 ## Phase 3 — Serial integration
 
-In the wave worktree: `git merge --no-ff <slice-branch>` per slice (disjoint →
-conflict-free). After EACH wave, on the integrated branch:
+In the wave worktree, `git merge --no-ff <slice-branch>` per slice. After EACH wave:
 
 - Typecheck both packages + the **FULL suite** — catches sibling/consumer test
   breaks the agent ownership didn't cover (hardcoded count/tab asserts). Exact
@@ -307,9 +307,9 @@ written · merge order documented.
   your own processes, targeted by the worktree's assigned ports, never blind).
   Remove temp verify scripts (a login helper, DB-check scripts).
 - **Remove only this run's claim marker.** If this run planted
-  `wave-active/<anchor>`, delete that exact local tag after success or abort. Never
-  delete a claim marker observed during a preflight collision or any other
-  `wave-active/*` marker; ownership, not a broad pattern, authorizes cleanup.
+  `wave-active/<anchor>`, call `releaseWaveClaim` with this run's owner after
+  success or abort; its owner check, not a broad `wave-active/*` pattern,
+  authorizes cleanup, and a foreign marker is left untouched.
 - **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions
   log, gitignored at worktree-root) and propagate each build-time assumption marker
   to the sibling issue it carries. A hand-driven multi-PR / migration landing does

package/.claude/skills/orchestrate-wave/references/builder-contract.md

@@ -56,13 +56,26 @@ invocation for each in this prompt so the builder cannot guess a wrong one.
    completed command result. Never end your turn while a command is still running.
 
 ## Report back (concise)
-Files touched · decisions taken · test results (exact completed command results
-and exit status) · commit SHA · STOP items · what the orchestrator should visually
-verify.
+Return exactly ONE JSON object against the builder report contract — no prose
+around it, no second object. Cover: files touched · decisions taken · test
+results (exact completed command results and exit status) · commit SHA · STOP
+items · what the orchestrator should visually verify.
 ```
 
 Orchestrator notes:
 
+- **The report contract is identical on every orchestration path.** Whether the
+  builder was dispatched by a scripted workflow, by native subagents, or run
+  directly and serially, it reports the same shape. `src/lib/reportValidator.mjs`
+  is the source of truth; [`references/report-contracts.md`](report-contracts.md)
+  is its machine-checked mirror for hosts that must inline a schema. Fill the
+  report section above with the builder schema from whichever of the two the
+  host can reach — never a hand-written variant.
+- **Validation is always the main thread's.** Schema-validate the returned
+  object, then call `semanticVerify` with independently collected Git facts. A
+  builder's own claim of success is a hypothesis; a payload that does not parse
+  or fails either check is a missing report, not a PASS.
+
 - `{{CONSUME_ONLY_LINES}}` come from the Phase-1 reconciliation, e.g.
   "X already exists in `<file>` — do NOT add it, consume only."
 - For dependent slices, fill hub artifact paths from the hub agent's report

package/.claude/skills/orchestrate-wave/references/dispatch-subagents.md

@@ -0,0 +1,79 @@
+# Path B — Native subagent dispatch
+
+Load this recipe only when the capability selector returns Path B. That result
+requires proven native spawn, wait, and aggregate primitives plus effective
+concurrency and thread capacity ≥2. Route from proven capabilities only, never
+from a surface name, and do not emulate a missing primitive.
+
+This recipe is **dormant on the current Codex host.** A verify spike against
+codex-cli 0.144.6 (2026-07-21) proved native start plus bounded wait, and an
+effective concurrency of 4, but the host exposes tool entries carrying only a
+name and a description: no tool schema, no callable or permitted flags, no
+thread capacity. The adapter therefore emits `unknown` for those fields and the
+selector fails closed to Path C. Only a future host that supplies the complete
+normalized inventory selects this path.
+
+## Main-thread preparation
+
+1. Read the canonical `RECON_REPORT_SCHEMA` and `BUILDER_REPORT_SCHEMA` values
+   from `src/lib/reportValidator.mjs`. They are the same contract every
+   orchestration path reports against.
+2. Embed the relevant schema verbatim in each subagent prompt, together with the
+   instruction to return **exactly ONE JSON object** and nothing else — no
+   prose, no fences, no second object. The host does not enforce output shape,
+   so the contract lives in the prompt and the check lives in the main thread.
+3. Acquire the wave claim and create every worktree from the integrated base
+   through `claimWave` in `src/lib/waveClaim.mjs` before any spawn. Claim and
+   worktree creation stay serial in the main thread; only the agents fan out.
+
+## Round 1 — Recon
+
+Spawn **one read-only explorer per slice**, all in one batch so they run
+concurrently, then join them with an **explicit wait** on the spawned set —
+never a sleep, a poll loop, or an implicit continue. Aggregate only after the
+wait returns.
+
+Each explorer returns one recon report. Validate every returned payload against
+the recon schema in the main thread: a payload that does not parse, carries
+extra top-level keys, or fails the schema **is not a PASS** — it is a missing
+report. Re-spawn that single explorer with the failure quoted back to it; never
+accept a prose summary in place of the object.
+
+## Main-thread reconcile boundary
+
+Pass the complete, validated recon set to `reconcileReconReports`. A
+reconciliation failure stops the wave. A successful result is the only boundary
+that permits builders to start; use its overlap graph and dependency edges to
+cut safe dispatch batches. Multiple editors are safe only when dependency
+reachability totally orders them; shared-mutable files still require exactly one
+edit owner.
+
+Every orchestration path crosses this same main-thread reconciliation boundary.
+Reconciliation is never delegated to a subagent.
+
+## Round 2 — Build
+
+For the current reconciled batch, spawn **one builder per slice**, again as one
+concurrent batch joined by an explicit wait. Give each builder the verbatim
+builder contract, its reconciled allowlist, and its required commands. The host
+exposes no per-agent role, model, or reasoning selector, so routing falls back
+to the parent session configuration — record the tier you intended in the
+prompt itself rather than assuming the host honoured it.
+
+Each builder returns exactly one builder report. Validate it against the builder
+schema and then run `semanticVerify` on it in the main thread. A subagent's own
+claim of success is a hypothesis, never the gate.
+
+## B1 fan-out is out of scope
+
+The **B1** shape — a single fan-out over a work list (`spawn_agents_on_csv`)
+plus a host-enforced per-agent `output_schema` — is explicitly excluded. The
+same spike found the callable spawn schema exposes only `task_name`, `message`,
+and `fork_turns`: no work-list fan-out and no output-schema parameter. This
+recipe therefore documents the **B2** shape only: explicit per-slice spawns
+joined by an explicit wait, with validation owned by the main thread.
+
+Re-opening B1 requires its own version-pinned verify spike — tracked as an open
+spike issue on the kit's own tracker — before any recipe or adapter change.
+Never infer the capability from a release note; prove it against the pinned
+runtime first.

package/.claude/skills/orchestrate-wave/references/dispatch-workflow.md

@@ -0,0 +1,58 @@
+# Path A — Scripted Workflow dispatch
+
+Load this recipe only when the capability selector returns Path A. That result
+requires the literal `Workflow` tool and every required primitive. Route from
+proven capabilities only, never from a surface name, and do not emulate
+Workflow. The current Codex host lacks complete capability evidence and selects
+Path C; a future host selects whichever path its evidence proves.
+
+## Main-thread preparation
+
+1. Read the canonical `RECON_REPORT_SCHEMA` and `BUILDER_REPORT_SCHEMA` values
+   from `src/lib/reportValidator.mjs`.
+2. Serialize each value as an inline schema literal in its generated Workflow
+   script. Workflow scripts cannot import modules, so never put an `import()`,
+   `require`, `process`, or `fetch` workaround in them.
+3. Build deterministic run arguments. Pass run identity, slice IDs, prompts,
+   models, effort levels, and timestamps through `args`; never call
+   `Date.now()` or `Math.random()` in a script.
+
+## Run 1 — Recon
+
+Declare the named recon phase in `meta.phases`. Within it, make one `agent()`
+call per slice, with explicit `model`, `effort`, and `phase` options. Give every
+call the inline recon schema so the Workflow runtime rejects prose or malformed
+output before aggregation.
+
+Use the run identity supplied in `args` and retain the Workflow-managed
+`journal.jsonl`. The main thread waits for the Recon run to finish and collects
+its schema-valid reports. It must not dispatch a builder yet.
+
+## Main-thread reconcile boundary
+
+Pass the complete Recon-run result to `reconcileReconReports`. A reconciliation
+failure stops the wave. A successful result is the only boundary that permits
+the Build run to start; use its overlap graph and dependency edges to cut safe
+dispatch batches. Multiple editors are safe only when dependency reachability
+totally orders them; shared-mutable files still require exactly one edit owner.
+
+Every orchestration path, including Paths B and C, must cross this same
+main-thread reconciliation boundary. Reconciliation is not Workflow-script
+logic.
+
+## Run 2 — Build
+
+Generate a separate Build run with its own named entry in `meta.phases`. For the
+current reconciled batch, make one `agent()` call per slice with explicit
+`model`, `effort`, and `phase` options and the inline builder schema. Preserve
+the reconciled allowlist and required commands in each verbatim builder prompt;
+the main thread still performs `semanticVerify` on every returned report.
+
+## Resume exactly once
+
+Resume an interrupted Recon or Build run with its recorded `resumeFromRunId`
+and the same deterministic `args`. Workflow returns cached results for completed
+agents: accept those results and dispatch only unfinished calls. Never create a
+replacement run for completed work, and never replay a completed builder. This
+makes each builder phase execute exactly once while the retained
+`journal.jsonl` remains the recovery and progress record.

package/.claude/skills/orchestrate-wave/references/report-contracts.md

@@ -0,0 +1,42 @@
+# Wave Report Contracts
+
+`src/lib/reportValidator.mjs` is the source of truth. The JSON blocks below are
+machine-checked mirrors for hosts that must inline a schema and cannot import the
+module. Do not edit a block without changing the exported constant first.
+
+## Recon report
+
+Required fields: <!-- fields:recon -->sliceId, plannedFiles, dependencyEdges
+
+`plannedFiles[].role` is `edit`, `consume`, or `sharedMutable`.
+`dependencyEdges` records directed slice dependencies as `from`/`to` IDs.
+
+<!-- schema:recon:start -->
+```json
+{"type":"object","required":["sliceId","plannedFiles","dependencyEdges"],"additionalProperties":false,"properties":{"sliceId":{"type":"string","pattern":"^[0-9]+$"},"plannedFiles":{"type":"array","items":{"type":"object","required":["path","role"],"additionalProperties":false,"properties":{"path":{"type":"string"},"role":{"type":"string","enum":["edit","consume","sharedMutable"]}}}},"dependencyEdges":{"type":"array","items":{"type":"object","required":["from","to"],"additionalProperties":false,"properties":{"from":{"type":"string","pattern":"^[0-9]+$"},"to":{"type":"string","pattern":"^[0-9]+$"}}}}}}
+```
+<!-- schema:recon:end -->
+
+## Builder report
+
+Required fields: <!-- fields:builder -->status, filesTouched, testDecisions, commands, commitSha, stopItems, visualVerify
+
+`status` discriminates the `oneOf`: PASS requires a full Git object ID and an
+empty `stopItems`; STOP requires at least one stop item and permits a null SHA.
+Schema validation intentionally accepts nonzero command exits. The orchestrator
+must additionally call `semanticVerify` before accepting PASS.
+
+<!-- schema:builder:start -->
+```json
+{"type":"object","required":["status","filesTouched","testDecisions","commands","commitSha","stopItems","visualVerify"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["pass","stop"]},"filesTouched":{"type":"array","items":{"type":"string"}},"testDecisions":{"type":"array","items":{"type":"string"}},"commands":{"type":"array","items":{"type":"object","required":["command","exitCode","summary"],"additionalProperties":false,"properties":{"command":{"type":"string"},"exitCode":{"type":"integer"},"summary":{"type":"string"}}}},"commitSha":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{40}$|^[0-9a-f]{64}$"},{"type":"null"}]},"stopItems":{"type":"array","items":{"type":"string"}},"visualVerify":{"type":"string"}},"oneOf":[{"required":["status","commitSha","stopItems"],"properties":{"status":{"const":"pass"},"commitSha":{"type":"string","pattern":"^[0-9a-f]{40}$|^[0-9a-f]{64}$"},"stopItems":{"type":"array","maxItems":0}}},{"required":["status","commitSha","stopItems"],"properties":{"status":{"const":"stop"},"commitSha":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{40}$|^[0-9a-f]{64}$"},{"type":"null"}]},"stopItems":{"type":"array","minItems":1}}}]}
+```
+<!-- schema:builder:end -->
+
+## Semantic facts
+
+Call `semanticVerify(report, { gitFacts, allowlist, requiredCommands })` with
+independently collected Git facts: `objectFormat` (`sha1` or `sha256`), the
+resolved `commitSha`, `baseIsAncestorOfCommit`, and `changedFiles`. The ancestry
+fact means the integration base is an ancestor of the builder commit. The helper
+verifies the full SHA against the repository object format and resolved commit, diff subset,
+required command presence, command exits for PASS, and PASS/STOP exclusivity.

package/.claude/skills/setup-workflow/census.md

@@ -66,13 +66,20 @@ delegates this route to the shipped `census-update` contract and its focused
 `scripts/test_census_update_contract.test.mjs` proof; it does not reproduce
 activation, snapshots, or enforcement. Setup itself never calls `activateCensus`.
 
-Disable follows the ordered contract: remove the kit-owned hook, remove the
-kit-owned gate, then atomically replace only the profile's `enabled` value with
-`false`, preserving unknown keys, and verify `disabled` through
-`resolveCensusState`. Enforcement removal must finish before any profile
-mutation. Treat the choice document, local scanners, their tests, the profile,
-and the active snapshot as consumer-owned evidence. List those files and ask
-for separate deletion approval; without that approval, retain them.
+Activation owns durable enforcement: every focused test declared by the active
+profile must remain transitively reachable through one shared project-local
+census check entry point from both local CI and pre-push. `census-update`
+reconciles that narrow kit-owned census wiring idempotently and requires an
+executable wiring proof before it can report `current`; setup does not pre-wire
+the optional bootstrap state.
+
+Disable follows the ordered contract: remove only the kit-owned census wiring
+(including the kit-owned hook and gate block), then atomically replace only the
+profile's `enabled` value with `false`, preserving unknown keys, and verify
+`disabled` through `resolveCensusState`. Enforcement removal must finish before
+any profile mutation. Treat the choice document, local scanners, their tests,
+the profile, and the active snapshot as consumer-owned evidence. List those
+files and ask for separate deletion approval; without that approval, retain them.
 Setup never deletes consumer-owned files as part of disable.
 
 ## Setup report

package/README.md

@@ -305,7 +305,10 @@ any language works — map each role once, rename an option with one profile edi
 `init` records a sha256 of every file it installs. That's the line between the
 two: **edit any skill or script freely** — `update` detects your edits and backs
 them up rather than clobbering them. Your **project layer** (`docs/agents/*`, the
-board profile, `CLAUDE.md`) is created once and never touched by `update`.
+board profile, `CLAUDE.md`, `AGENTS.md`) remains consumer-owned. `update` may
+only apply a previewed, schema-driven, idempotent compatibility migration that
+fills missing evidence without rewriting an existing value; it verifies and
+rolls that migration back with the rest of the candidate.
 
 ## Updating & removing
 
@@ -346,8 +349,65 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 `--force` (overwrite pre-existing untracked files on `init`), `--yes` / `-y`
 (accept non-interactive update decisions).
 
+## Upgrade notes
+
+### 0.33.0 — capability-gated orchestration
+
+`kit-update` reconciles this release for you. These notes matter only if you
+maintain a **local fork of `orchestrate-wave`**: the blocks below changed
+behaviour, so a forked copy must re-apply them by hand or it keeps orchestrating
+the old way. Decision record:
+[`docs/adr/0002-capability-gated-orchestration.md`](docs/adr/0002-capability-gated-orchestration.md).
+
+- **Capability matrix, fail-closed.** The dispatch mechanic is selected from
+  host-supplied capability evidence, degrading A → B → C. Missing or `unknown`
+  evidence never proves a capability, and Path C (direct, serial) is always
+  available.
+- **No emulation of a missing primitive.** A host without a scripted workflow
+  runtime gets the simpler recipe, never a hand-rolled imitation of one.
+- **Codex Path B is native subagents.** Explicit per-slice spawns joined by an
+  explicit wait — dormant until a host supplies the complete normalized
+  inventory.
+- **JSON-schema reports plus independent verification.** Every path returns
+  schema-valid recon and builder reports and crosses the same main-thread
+  boundary; a builder's own PASS is a hypothesis until `semanticVerify` confirms
+  it against independently collected Git facts.
+- **Per-batch, post-hub worktree provisioning.** Worktrees are created serially
+  in the main thread from the integrated base after the hub lands, under an
+  atomic compare-and-set wave claim; reuse on a stale base now STOPs.
+- **Heartbeat during long gates.** Long-running gates report status rather than
+  waiting silently.
+
 ## Release notes
 
+### 0.33.0
+
+- added: `.agents/skills/orchestrate-wave/references/dispatch-subagents.md`
+- added: `.agents/skills/orchestrate-wave/references/dispatch-workflow.md`
+- added: `.agents/skills/orchestrate-wave/references/report-contracts.md`
+- added: `.claude/skills/orchestrate-wave/references/dispatch-subagents.md`
+- added: `.claude/skills/orchestrate-wave/references/dispatch-workflow.md`
+- added: `.claude/skills/orchestrate-wave/references/report-contracts.md`
+- added: `src/lib/capabilityMatrix.mjs`
+- added: `src/lib/reconcileReconReports.mjs`
+- added: `src/lib/reportValidator.mjs`
+- added: `src/lib/waveClaim.mjs`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.agents/skills/orchestrate-wave/references/builder-contract.md`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/orchestrate-wave/references/builder-contract.md`
+- changed: `scripts/worktree-lifecycle/setup.py`
+
+### 0.32.1
+
+- changed: `.agents/skills/census-update/SKILL.md`
+- changed: `.agents/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/census.md`
+- changed: `.claude/skills/census-update/SKILL.md`
+- changed: `.claude/skills/kit-update/SKILL.md`
+- changed: `.claude/skills/setup-workflow/census.md`
+- changed: `scripts/readiness.mjs`
+
 ### 0.32.0
 
 - changed: `.agents/skills/audit-skills/SKILL.md`