@ikon85/agent-workflow-kit 0.32.1 → 0.34.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.
+Before any spawn, resolve the provider-neutral Routing intent through the shared resolver and spawn guard, then use the active Claude or Codex adapter. Codex contributes only its dated host attestation through `routingAdapters/codex.mjs`; it does not create a second catalog, Access graph, or Routing policy. A detected transport is not authorization. The Dispatch receipt must show requested and applied route, model/effort enforcement, environment precedence on mismatch, and catalog/access/policy revisions. AFK blocks unverified, unauthorized, overridden, unenforced, or silently degraded routes; a Codex host without model and effort selectors blocks differentiated AFK before spawn, and unreachable routes follow policy handoff/inherit/block exactly.
+- **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,91 @@
+# 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 unless the current host's complete orchestration
+inventory proves Path B.** The dated Codex routing attestation is a separate
+gate: the observed explicit-spawn schema exposes only `task_name`, `message`,
+and `fork_turns`, with no model or effort selector. Therefore
+`routingAdapters/codex.mjs` blocks differentiated AFK before spawn even when
+native start/wait/aggregate evidence is otherwise sufficient for Path B. A
+future host may enable the route only by attesting both orchestration primitives
+and applied model/effort controls; neither is inferred from the surface name.
+
+## 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. Resolve
+the provider-neutral Routing intent immediately before each spawn. Pass the
+decision through `routeDispatcher.mjs` and the active surface adapter. Claude
+uses its native or explicitly policy-approved transport attestation; Codex uses
+only its dated `routingAdapters/codex.mjs` host attestation. Both must prove
+their requested and applied model and effort controls before invocation.
+Detection alone never authorizes a transport.
+
+The spawn guard compares the requested route with the adapter's applied route
+and environment precedence. It emits the shared Dispatch receipt with
+catalog/access/policy revisions. An unverified control, unauthorized transport,
+override mismatch, or unenforced effort blocks AFK before spawn. A genuinely
+unreachable route follows the policy's handoff, inherit, or block result; never
+silently inherit. A host without a proved per-agent selector remains on its
+existing parent-session fallback only when explicit non-AFK policy permits 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,66 @@
+# 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.
+
+Before each `agent()` call, resolve its provider-neutral Routing intent and pass
+the decision through the shared spawn guard and active surface adapter. The
+Claude adapter must attest Workflow model/effort precedence in the current
+environment; a future Codex host may use this path only when its dated
+`routingAdapters/codex.mjs` attestation proves the same controls. Create the
+Dispatch receipt before invocation; any requested/applied mismatch, unverified
+control, or unauthorized transport blocks AFK rather than silently degrading.
+
+## 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/research/SKILL.md

@@ -3,6 +3,12 @@ name: research
 description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
 ---
 
+Before dispatch, resolve a provider-neutral Routing intent through
+`src/lib/routeDispatcher.mjs` and require a Dispatch receipt from the shared
+spawn guard. A detected transport is not authorization; AFK dispatch stops
+unless requested/applied route, model/effort enforcement, environment
+precedence, and catalog/access/policy revisions are proved.
+
 Spin up a **background agent** to do the research, so you keep working while it reads.
 
 Its job:

package/.claude/skills/scale-check/SKILL.md

@@ -87,8 +87,9 @@ skills — this skill only picks the entry point.
 
 ### Program (≥2 criteria)
 
-A multi-wave undertaking: grill it once into a Program-PRD with a wave plan, then
-unfold that plan onto the board after a chat preview gate.
+A multi-wave undertaking: grill it once into a Program-PRD with a wave plan,
+then hand that explicit Program identity to the public Planning facade. The
+facade unfolds the plan onto the board after a chat preview gate.
 
 ```
 New program: <one-sentence outcome from Q2>.
@@ -97,10 +98,11 @@ Tripped altitude criteria: <e.g. C1 staged delivery, C2 multiple subsystems, C4
    structure-bearing decisions (escalate a single bounded choice to `decision-gate`).
 2. `to-prd` — it auto-detects the program mode from the Wellenplan chapter and writes
    a Program-PRD (native anchor over the waves).
-3. `to-waves` — after one complete chat preview, materialize the whole Program with
-   **all waves execute-ready by default**: complete slice contracts, buckets,
-   dependencies and handoffs. Decision Gates, Verify Spikes and Design-Grill waves
-   are explicit planned exceptions; generic late-binding cleanup is not.
+3. `to-issues` — its explicit Program identity selects the internal graph path.
+   After one complete chat preview, materialize the whole Program with **all
+   waves execute-ready by default**: complete slice contracts, buckets,
+   dependencies and handoffs. Decision Gates, Verify Spikes and Design-Grill
+   waves are explicit planned exceptions; generic late-binding cleanup is not.
 ```
 
 ### Feature (0–1 criteria, or any doubt)
@@ -134,7 +136,7 @@ Bug: <what's broken — expected vs. actual>.
 ```
 scale-check: verdict=<Program | Feature | Direct-Slice | Bug>
   criteria tripped=<C1,C2,… | none | n/a (bug/direct)>
-  route=<program grill → to-prd → to-waves (all waves execute-ready by default) | grill-with-docs → to-prd → to-issues | implement | diagnose>
+  route=<program grill → to-prd → to-issues (Program mode; all waves execute-ready by default) | grill-with-docs → to-prd → to-issues (Feature mode) | implement | diagnose>
   start-prompt: <the paste-ready block above, filled in>
 ```
 

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

@@ -28,6 +28,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
 | `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, Workflow Advisories, and Safety Guardrails choices (Sections A4–A7) |
 | `.claude/settings.json` | additive activation of the advisory kit-origin Edit/Write hint (Section A8) |
+| user-local routing profile | familiar agent surfaces + switching autonomy (Section A9; never package- or repository-owned) |
 
 ## Idempotency contract — read before writing anything
 
@@ -60,6 +61,9 @@ Read the current state; don't assume. For every target file, read its first line
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
 - `docs/agents/workflow-capabilities.json`, `.claude/settings.json`, `git config --get core.hooksPath` — existing capability choices/profile plus Worktree Lifecycle, Workflow Advisories, Safety Guardrails, and kit-origin hint wiring to adopt.
 - `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
+- The Kit routing-profile preflight — adopt a valid user-local choice without
+  printing or copying it into the repository. Never infer personal routing
+  policy from instruction files, credentials, or package-owned metadata.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -280,6 +284,41 @@ This is an additive, idempotent settings edit, not a settings rewrite:
    `PreToolUse`, are consumer-owned conflicts: leave the file untouched and
    report the skipped activation. Never replace or normalize them.
 
+### 2h. Section A9 — Agent surfaces and switching autonomy
+
+> Routing setup asks which familiar agent apps you use and whether the Kit may
+> switch between them. Surface adapters establish providers, transports,
+> selectors, and enforcement capabilities; the default interview never asks
+> the user to describe those technical facts.
+
+Read the versioned agent-surface registry and detection result. Show its
+multi-select labels with detected entries preselected; never embed a separate
+list in prompt prose. Then ask only one plain-language autonomy question:
+
+- **Switch automatically** — record `automatic`.
+- **Ask before switching** — record `ask`.
+- **Stay in the current app** — record `current-surface-only`.
+
+When exactly one surface is selected, skip the autonomy question and use
+`current-surface-only`. Show an activation summary with explicit **Back**,
+**Advanced**, **Approve**, and **Safe current surface** actions. Back revisits
+the simple choices. Advanced is the only flow that may collect model
+preferences or optimization overrides, but those values remain a draft and
+return to the activation summary; Advanced alone never writes. Only a later
+Approve or Safe current surface action activates the draft. Safe current
+surface activates the selection with `current-surface-only`.
+
+Store the answer through `src/lib/routingProfile.mjs` in its user-local state
+location, outside the consumer repository and package manifest. Never print
+credentials or derive personal choices from detected transports. A valid
+existing profile is terminal and reports `still valid`; do not prompt again.
+Missing or invalid profiles receive one migration interview. Reconcile a
+materially stale profile, a removed route, or a newly detected meaningful
+surface with a typed delta that names only the changed choice and preserves
+unaffected surfaces, autonomy, and advanced values. Re-read the profile before
+activation and use its fingerprint plus the exclusive profile lock; a
+concurrent user-local change blocks activation and remains byte-preserved.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -309,7 +348,14 @@ Seed `docs/agents/domain.md` from [domain.md](./domain.md).
 
 **Fallback (the single catch-all — no board / >1 / ambiguous / scope error / read failure):** do **not** auto-create a board (`gh project create` alone cannot provision the Status options + workflow fields a board needs). Write `board-sync.md` with `state=stub`, `mode=github-projects-v2`, and inline **instructions**: which fields the workflow profile needs (a Status single-select with your stage options; optionally a Wave number, a Cluster text, a Spec-Path / Plan-Path text), how to create the board in the GitHub UI / `gh`, and "then run `/setup-workflow` again — it will discover and fill the IDs." Retryable.
 
-**Optional — Phase field + saved Views (Program route only):** never auto-discovered or auto-created, unlike the fields above — a Phase field's option set is plan-specific. If this project plans to use the Program route (`scale-check` → `to-waves` → `validate-graph`), point the user at the seeded [board-sync.md](./board-sync.md)'s "Optional: the Program route" section for the `gh project field-create` command, the optional `fields.phase` / `labels.programType` profile keys, and the two saved Views to create by hand.
+**Optional — Phase field + saved Views (Program route only):** never
+auto-discovered or auto-created, unlike the fields above — a Phase field's
+option set is plan-specific. If this project plans to use the Program route
+(`scale-check` → `to-issues` with explicit Program identity → internal graph
+validation), point the user at the seeded [board-sync.md](./board-sync.md)'s
+"Optional: the Program route" section for the `gh project field-create`
+command, the optional `fields.phase` / `labels.programType` profile keys, and
+the two saved Views to create by hand.
 
 ### 6. Section E — Spec-layer seeds (non-interactive)
 

package/.claude/skills/setup-workflow/board-sync.md

@@ -16,7 +16,7 @@ How the board-managed workflow skills (`to-prd`, `to-issues`, `board-to-waves`,
 | Cluster | text | optional | thematic cluster tag |
 | Spec-Path | text | optional | link from an issue to its spec doc |
 | Plan-Path | text | optional | link from an issue to its plan doc |
-| Phase | single-select | optional | groups waves into phases for the Program route (`to-waves`/`validate-graph`) — only needed if this project uses it |
+| Phase | single-select | optional | groups waves into phases for the Program route (`to-issues` Program mode / internal graph validation) — only needed if this project uses it |
 
 ## Machine profile (SSOT) — `scripts/board_config.py` reads this
 
@@ -112,7 +112,12 @@ their titles unchanged; set it once to match your board's language.
 
 ## Optional: the Program route (Phase field + saved Views)
 
-Skip this section entirely unless this project actually plans to use the Program route (`scale-check` → `to-waves` → `validate-graph`) — `fields.phase` / `labels.programType` are never auto-discovered or auto-created (a Phase field's option set is plan-specific, not something `/setup-workflow` can guess), and a profile without them keeps loading unchanged.
+Skip this section entirely unless this project actually plans to use the Program
+route (`scale-check` → `to-issues` with explicit Program identity → internal
+graph validation) — `fields.phase` / `labels.programType` are never
+auto-discovered or auto-created (a Phase field's option set is plan-specific,
+not something `/setup-workflow` can guess), and a profile without them keeps
+loading unchanged.
 
 1. **Create the Phase field:** `gh project field-create <number> --owner <owner> --name Phase --data-type SINGLE_SELECT --single-select-options "P1,P2,P3"` (name the options after this project's actual phases).
 2. **Fill `fields.phase`** in the `<!-- board-sync:profile -->` block above with the same `{id, options}` shape as `fields.status` — read both back via `gh project field-list <number> --owner <owner> --format json`.

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

@@ -8,8 +8,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **A new build whose size is unclear** (a new app, a big cross-cutting feature, an unclear where-to-start): run `scale-check` — a short plain-language dialog that routes it to a program, a feature, a single slice, or a bug, and hands back a paste-ready start prompt.
 - **New capability or unclear change:** start with `grill-with-docs` when the domain language or decisions need sharpening, then publish the agreed shape with `to-prd`.
 - **A slice hinges on an unresolved fact or trade-off before it can be built:** clear it first — a binary yes/no question against real code/runtime/platform with `verify-spike`, a bounded "which option" choice with `decision-gate`.
-- **Existing plan, PRD, or ready issue:** use `to-issues` to split it into independently buildable tracer-bullet slices.
-- **A Program-PRD with a wave plan:** use `to-waves` to unfold it into named wave stubs + slice leaves on the board, after a chat preview gate that shows the whole plan before any write.
+- **Existing plan, PRD, or ready issue:** use `to-issues`, the single Planning facade. Explicit Feature identity selects tracer-bullet decomposition; explicit Program identity selects the internal graph path and its complete preview before any write.
 - **A backlog of open issues needs clustering into themed waves:** use `board-to-waves`.
 - **A whole wave anchor (file-disjoint slices, specs already locked) to build, verify and land end-to-end — often AFK:** use `orchestrate-wave` — it dispatches implementers per slice, integrates serially, verifies centrally, and lands. (A single slice just goes to `implement`.)
 - **Bugs or requests piling up that you didn't create:** use `triage` to move them into agent-ready issues.