@ikon85/agent-workflow-kit 0.32.1 → 0.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/.agents/skills/ask-matt/SKILL.md +4 -3
  2. package/.agents/skills/audit-skills/SKILL.md +6 -0
  3. package/.agents/skills/board-to-waves/SKILL.md +6 -2
  4. package/.agents/skills/code-review/SKILL.md +6 -0
  5. package/.agents/skills/codebase-design/DESIGN-IT-TWICE.md +11 -1
  6. package/.agents/skills/codex-adapter-sync/SKILL.md +23 -19
  7. package/.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +6 -0
  8. package/.agents/skills/improve-codebase-architecture/SKILL.md +10 -1
  9. package/.agents/skills/kit-update/SKILL.md +13 -0
  10. package/.agents/skills/orchestrate-wave/SKILL.md +54 -54
  11. package/.agents/skills/orchestrate-wave/references/builder-contract.md +16 -3
  12. package/.agents/skills/orchestrate-wave/references/dispatch-subagents.md +91 -0
  13. package/.agents/skills/orchestrate-wave/references/dispatch-workflow.md +66 -0
  14. package/.agents/skills/orchestrate-wave/references/report-contracts.md +42 -0
  15. package/.agents/skills/research/SKILL.md +6 -0
  16. package/.agents/skills/scale-check/SKILL.md +9 -7
  17. package/.agents/skills/setup-workflow/SKILL.md +47 -1
  18. package/.agents/skills/setup-workflow/board-sync.md +7 -2
  19. package/.agents/skills/setup-workflow/workflow-overview.md +1 -2
  20. package/.agents/skills/to-issues/SKILL.md +66 -8
  21. package/.agents/skills/to-waves/SKILL.md +24 -12
  22. package/.claude/skills/ask-matt/SKILL.md +4 -3
  23. package/.claude/skills/audit-skills/SKILL.md +6 -0
  24. package/.claude/skills/board-to-waves/SKILL.md +6 -2
  25. package/.claude/skills/code-review/SKILL.md +6 -0
  26. package/.claude/skills/codebase-design/DESIGN-IT-TWICE.md +8 -0
  27. package/.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +6 -0
  28. package/.claude/skills/improve-codebase-architecture/SKILL.md +6 -0
  29. package/.claude/skills/kit-update/SKILL.md +13 -0
  30. package/.claude/skills/orchestrate-wave/SKILL.md +54 -54
  31. package/.claude/skills/orchestrate-wave/references/builder-contract.md +16 -3
  32. package/.claude/skills/orchestrate-wave/references/dispatch-subagents.md +91 -0
  33. package/.claude/skills/orchestrate-wave/references/dispatch-workflow.md +66 -0
  34. package/.claude/skills/orchestrate-wave/references/report-contracts.md +42 -0
  35. package/.claude/skills/research/SKILL.md +6 -0
  36. package/.claude/skills/scale-check/SKILL.md +9 -7
  37. package/.claude/skills/setup-workflow/SKILL.md +47 -1
  38. package/.claude/skills/setup-workflow/board-sync.md +7 -2
  39. package/.claude/skills/setup-workflow/workflow-overview.md +1 -2
  40. package/.claude/skills/to-issues/SKILL.md +66 -8
  41. package/.claude/skills/to-waves/SKILL.md +24 -12
  42. package/README.md +126 -11
  43. package/agent-workflow-kit.package.json +291 -39
  44. package/docs/adr/0002-capability-gated-orchestration.md +70 -0
  45. package/docs/adr/0005-to-issues-is-the-planning-facade.md +42 -0
  46. package/docs/adr/0006-routing-knowledge-access-and-policy-are-separate.md +91 -0
  47. package/docs/agents/skills/local-ci.md +89 -0
  48. package/docs/agents/wave-anchor-template.md +2 -2
  49. package/docs/methodology.html +1 -1
  50. package/docs/methodology.svg +1 -1
  51. package/docs/workflow.html +2 -2
  52. package/docs/workflow.png +0 -0
  53. package/package.json +1 -1
  54. package/scripts/codex-exec.sh +47 -8
  55. package/scripts/codex-exec.test.mjs +56 -0
  56. package/scripts/test_codex_adapter_sync_contract.py +30 -15
  57. package/scripts/test_orchestrate_wave_contract.py +209 -0
  58. package/scripts/test_program_planning_contract.py +70 -0
  59. package/scripts/test_skill_portability_lint.py +54 -0
  60. package/scripts/test_worktree_setup_base_guard.py +140 -0
  61. package/scripts/worktree-lifecycle/setup.py +40 -0
  62. package/src/cli.mjs +109 -2
  63. package/src/commands/init.mjs +17 -1
  64. package/src/commands/routing-policy-update.mjs +204 -0
  65. package/src/commands/update.mjs +22 -0
  66. package/src/lib/agentSurfaceRegistry.mjs +60 -0
  67. package/src/lib/bundle.mjs +34 -0
  68. package/src/lib/capabilityMatrix.mjs +179 -0
  69. package/src/lib/dispatchReceipt.mjs +162 -0
  70. package/src/lib/frontendWorkloads.mjs +170 -0
  71. package/src/lib/reconcileReconReports.mjs +111 -0
  72. package/src/lib/reportValidator.mjs +186 -0
  73. package/src/lib/routeDispatcher.mjs +158 -0
  74. package/src/lib/routingAccessGraph.mjs +105 -0
  75. package/src/lib/routingAdapters/claude.mjs +62 -0
  76. package/src/lib/routingAdapters/codex.mjs +136 -0
  77. package/src/lib/routingCatalog.mjs +123 -0
  78. package/src/lib/routingEvidenceCache.mjs +222 -0
  79. package/src/lib/routingIntent.mjs +93 -0
  80. package/src/lib/routingPolicy.mjs +67 -0
  81. package/src/lib/routingProfile.mjs +334 -0
  82. package/src/lib/routingResolver.mjs +176 -0
  83. package/src/lib/routingSources/artificialAnalysis.mjs +129 -0
  84. package/src/lib/routingSources/benchlm.mjs +151 -0
  85. package/src/lib/routingSources/codeArena.mjs +162 -0
  86. package/src/lib/routingSources/deepswe.mjs +106 -0
  87. package/src/lib/routingSources/openhands.mjs +102 -0
  88. package/src/lib/routingSources/openhandsFrontend.mjs +135 -0
  89. package/src/lib/waveClaim.mjs +134 -0
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: to-issues
3
- description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
3
+ description: Break a Feature or Program plan, spec, or PRD into independently-grabbable issues on the project issue tracker. This is the single public Planning facade: explicit Feature identity uses tracer-bullet decomposition; explicit Program identity delegates to the internal graph engine.
4
4
  ---
5
5
 
6
6
  # To Issues
@@ -23,6 +23,39 @@ node scripts/readiness.mjs check --skill to-issues --json
23
23
  - `managedBoard=not-applicable`: `STOP` and report that `/to-issues` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
24
24
  <!-- readiness:required-preflight:end -->
25
25
 
26
+ ## Planning facade — select by explicit identity only
27
+
28
+ `to-issues` is the **single public Planning facade**. After the readiness
29
+ preflight and before any remote write, classify the source from its explicit PRD
30
+ identity:
31
+
32
+ - **Feature identity → `planning-mode=feature`.** The body carries
33
+ `<!-- prd: awaiting-decomposition -->` and its one `type:*` label is not the
34
+ configured Program type. Run the existing Feature decomposition path below:
35
+ one slice stays ATOMIC; two or more slices PROMOTE to a wave anchor.
36
+ - **Program identity → `planning-mode=program`.** The body carries
37
+ `<!-- prd: program -->` and its one `type:*` label is the board profile's
38
+ `labels.programType` value. Preserve the source and delegate to the internal
39
+ `to-waves` graph engine. That engine still validates the graph, shows the
40
+ complete Program preview, waits for the single explicit approval, and performs
41
+ zero remote writes before approval.
42
+
43
+ **Missing or contradictory identity is a hard stop before a remote write.**
44
+ Missing means neither marker is present, including a raw issue, file bundle, or
45
+ external PRD without an explicit identity. Contradictory means both markers are
46
+ present, the marker disagrees with the `type:*` label, or the source carries
47
+ multiple type labels. Report the observed markers and type labels, then ask the
48
+ user to establish exactly one identity. A cold-entry source may receive a
49
+ Feature or Program identity only after that explicit choice; rerun this
50
+ classification before any normalization or publication.
51
+
52
+ **Size, prose, and model judgment never select the mode.** A `## Wellenplan`
53
+ heading, estimated file count, wording such as “large program”, or an agent's
54
+ inference may validate or contradict an already explicit identity, but none may
55
+ create or switch it. A Program identity without the graph grammar is a blocking
56
+ contract error, not a fallback to Feature. A Feature identity with Program-only
57
+ graph grammar is likewise contradictory and stops.
58
+
26
59
  ## Process
27
60
 
28
61
  ### 1. Gather context
@@ -110,7 +143,8 @@ Ask the user:
110
143
 
111
144
  Iterate until the user approves the breakdown.
112
145
 
113
- **Program batch handoff.** When `to-waves` invokes this skill for a Stufe-1p stub,
146
+ **Program batch handoff.** When the internal Program graph engine invokes this
147
+ skill for a Stufe-1p stub,
114
148
  the complete Program preview has already shown and approved every wave's slice
115
149
  contract. Reuse that approval when this pass preserves the approved cut: do not
116
150
  pause again merely because the internal pipeline crossed a skill boundary. Run
@@ -122,9 +156,21 @@ newly discovered gate invalidates the inherited approval and returns to §4.
122
156
 
123
157
  **Cluster/Wave discriminator (identical wording — `to-prd` §2 / `to-issues` §5):** `type:cluster` (label) always stops. A Wave number also stops, **unless** the target carries the `wave-stub` label — a Wave-stamped `wave-stub` issue is a **Stufe-1p Program-stub** (`to-waves`-published, native parent = a Program-PRD) and remains a **valid target**. A Wave-stamped issue **without** `wave-stub` (an already-assigned leaf, or a drifted item) is still a hard stop.
124
158
 
125
- The canonical source is a **Draft-PRD** issue from `to-prd` (carries `plan_revision`, `<!-- prd: awaiting-decomposition -->`, exactly one `type:*` + one `priority:*`, **no** `type:cluster`, and no Wave **unless** the discriminator's `wave-stub` exception applies — a Program-stub's per-wave-start content pass writes this same shape into an already Wave-stamped stub, `to-prd` §2). But `to-issues` is **provenance-independent**: it re-derives readiness from the **artefact** (§3b), never from which tool produced it.
126
-
127
- **Cold entry on an already-existing issue.** The source can also be a **raw issue**, an **external PRD embedded in an issue**, or a **mechanical file bundle** — without the `to-prd` markers. Then a **cold-entry preflight applies before anything is mutated:**
159
+ The canonical Feature source is a **Draft-PRD** issue from `to-prd` (carries
160
+ `plan_revision`, `<!-- prd: awaiting-decomposition -->`, exactly one `type:*` +
161
+ one `priority:*`, **no** `type:cluster`, and no Wave **unless** the
162
+ discriminator's `wave-stub` exception applies — a Program-stub's per-wave-start
163
+ content pass writes this same shape into an already Wave-stamped stub, `to-prd`
164
+ §2). The facade is provenance-independent but not identity-optional: it
165
+ re-derives readiness from the **artefact** (§3b), never from which tool produced
166
+ it, only after the explicit identity classification above selected the mode.
167
+
168
+ **Cold entry on an already-existing issue.** The source can also be a **raw
169
+ issue**, an **external PRD embedded in an issue**, or a **mechanical file
170
+ bundle** — without the `to-prd` markers. That absence first triggers the
171
+ facade's identity hard stop above. Only after the user explicitly establishes
172
+ Feature identity may this **cold-entry preflight apply before anything is
173
+ mutated:**
128
174
  - **Hard-stop per the discriminator above** — `type:cluster` always; Wave only when the issue is **not** a `wave-stub` (the exception is already an intended promote target — `promote` reuses its pre-stamped Wave number, §5a below).
129
175
  - **Normalize labels** (mirroring `to-prd`'s normalization): exactly **one `type:*` + one `priority:*`**; `needs-info`/`ready-for-agent` **stripped** until the final bucket assignment (§5c).
130
176
  - **Synthesize missing `to-prd` markers in place** (never assume them): `plan_revision r1` at the body head, render the Tier-2 anchor body from the template. Surface `source`/`synthesized` in the §7 audit.
@@ -389,7 +435,8 @@ Reference the blocking ticket(s), or "None - can start immediately".
389
435
  <!-- mirror-xform:start codex-escalation -->
390
436
  ```
391
437
  Welle <N> · Slice <X> (<closes #x | refs #<prd#>, Parent #<prd#>>). Read #<prd#> for decisions.
392
- Start skill: 🧭 Design Grill → /grill-with-docs-codex · 🔬 Verify Spike → /verify-spike · 📐 Trade-off/Research → /decision-gate · AFK → /implement · HITL → /grill-me → /implement. Recommended model: <Model [Effort]>.
438
+ Start skill: 🧭 Design Grill → /grill-with-docs-codex · 🔬 Verify Spike → /verify-spike · 📐 Trade-off/Research → /decision-gate · AFK → /implement · HITL → /grill-me → /implement.
439
+ Routing intent: `routing-intent: <judgment | development | mechanical>` · `reasoning-intent: <deep | balanced | light>`. The dispatching surface resolves the current executable route; never persist that provider route here.
393
440
  Worktree: your project's worktree helper, or `git worktree add`
394
441
  Scope (<N> files) — REQUIRED FIELD, blast-radius estimate at cut time; the build session checks it against its own recon findings, >2x deviation → STOP:
395
442
  - <concrete file + change>
@@ -397,6 +444,12 @@ Live-verify: <user outcome, DB/UI value with comparison>
397
444
  PR: <closes #x | Part of #<prd#> — NEVER closes on the anchor>.
398
445
  ```
399
446
  <!-- mirror-xform:end -->
447
+
448
+ At execution time, consume that provider-neutral intent only through
449
+ `src/lib/routeDispatcher.mjs` and its shared spawn guard. The active Claude or
450
+ Codex adapter must produce Dispatch receipt v2 with requested/applied route,
451
+ model/effort enforcement, precedence, and catalog/access/policy revisions
452
+ before an AFK subagent starts; the durable issue never claims that proof.
400
453
  </issue-template>
401
454
 
402
455
  **Blast-radius reconciliation (build session):** the stamped `**Blast-Radius:**` is the estimate *at the cut* — the build session compares it against its own recon finding. A real finding **> 2× the estimate → STOP + report** (re-cut at the anchor), do NOT keep building silently.
@@ -430,12 +483,17 @@ It asserts, for the rooted local graph:
430
483
 
431
484
  If the source was a `wave-stub` stub, briefly confirm the label is gone (the publish mechanic strips it automatically — see §5): `gh issue view <anchor-or-leaf#> --json labels -q '.labels[].name'` shows **no** `wave-stub`. (Not part of `execute-ready-check.py` — its own quick check.)
432
485
 
433
- `--mode audit` is **non-blocking** — a mismatch is a **loud warning** here; the **hard block** is `.claude/hooks/drift-guard.py` at handoff-creation. Emit a visible audit two-liner:
486
+ `--mode audit` is **non-blocking** — a mismatch is a **loud warning** here; the
487
+ **hard block** is `.claude/hooks/drift-guard.py` at handoff-creation. Emit a
488
+ visible audit that names the selected facade mode:
434
489
 
435
490
  ```
436
- to-issues: anchor=#<X> mode=<promote|atomic> slices=<n> rev <old>→<new>
491
+ to-issues: planning-mode=feature anchor=#<X> mode=<promote|atomic> slices=<n> rev <old>→<new>
437
492
  source=<draft-prd|raw-issue|external-prd|bundle> synthesized=<marker-list | none>
438
493
  AFK=[#a #b] HITL=[#c] · drift=<none | …> shape=<ok | warn:…>
439
494
  ```
440
495
 
496
+ The Program graph engine emits `planning-mode=program` in its own counted audit
497
+ after the complete preview gate; the facade relays that audit unchanged.
498
+
441
499
  Do NOT close or modify any parent issue beyond the promote stamp.
@@ -1,17 +1,25 @@
1
1
  ---
2
2
  name: to-waves
3
3
  disable-model-invocation: true
4
- description: "Turn a Program-PRD's wave plan into fully planned, execute-ready wave anchors and slice leaves after one complete chat preview. Validates the graph, publishes every wave, runs the to-prd/spec-self-critique/to-issues maturity contract for each wave, models unresolved work as explicit gates, and audits counted readiness. Idempotent and crash-recoverable. Use on a Program-PRD over several waves. NOT for a single-wave feature (to-issues) or backlog clustering (board-to-waves)."
4
+ description: "Internal Program graph engine behind the public to-issues Planning facade. Turns an explicitly identified Program-PRD into execute-ready wave anchors and slice leaves after one complete chat preview. Kept as a disabled compatibility entrypoint for existing explicit invocations; normal routing always selects to-issues."
5
5
  ---
6
6
 
7
- # to-waves — Unfold a Program-PRD's wave plan onto the board
7
+ # to-waves — Internal Program graph engine
8
+
9
+ This skill is an **Internal Program graph engine**, selected by `to-issues` only
10
+ when the source carries explicit, coherent Program identity. It is not a second
11
+ public Planning route. The disabled `/to-waves` invocation remains only as a
12
+ compatibility entrypoint for existing callers and tests; it applies this same
13
+ contract and should direct future normal use to `/to-issues`.
8
14
 
9
15
  Takes a **Program-PRD** — the native Sub-Issue anchor over a multi-wave program
10
16
  (Programm → Phase → Welle → Slice) — and turns its `## Wellenplan` chapter into
11
17
  **fully planned wave anchors + slice leaves** on the board. Pipeline position:
12
- `scale-check → grill → to-prd (program mode) → to-waves`, with the per-wave
13
- `to-prd → spec-self-critique → to-issues` maturity pass owned inside this run.
14
- The **grill and to-prd sit upstream**; to-waves runs once the Program-PRD exists.
18
+ `scale-check → grill → to-prd (program mode) → to-issues`, with this internal
19
+ engine owning the per-wave `to-prd → spec-self-critique → to-issues` maturity
20
+ pass inside this run.
21
+ The **grill and to-prd sit upstream**; the facade dispatches here once the
22
+ Program-PRD exists and its identity is coherent.
15
23
  It **never invents structure** — it only unfolds what the plan already decided.
16
24
 
17
25
  <!-- readiness:required-preflight:start -->
@@ -24,8 +32,8 @@ node scripts/readiness.mjs check --skill to-waves --json
24
32
  ```
25
33
 
26
34
  - `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
27
- - `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `issueTracker`, `managedBoard`, and `specCompleteness` failures — including distinct `missing`, `pending`, and `invalid` states — stay visible, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-waves`.** Do not fall back to bare tracker or board commands.
28
- - `managedBoard=not-applicable`: `STOP` and report that `/to-waves` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
35
+ - `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `issueTracker`, `managedBoard`, and `specCompleteness` failures — including distinct `missing`, `pending`, and `invalid` states — stay visible, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-issues`.** Do not fall back to bare tracker or board commands.
36
+ - `managedBoard=not-applicable`: `STOP` and report that Program planning through `/to-issues` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
29
37
  <!-- readiness:required-preflight:end -->
30
38
 
31
39
  Board constants (project node, field/status IDs) + helpers live **consumer-side**:
@@ -43,10 +51,14 @@ is the parser.
43
51
 
44
52
  ## 1. Input — a Program-PRD
45
53
 
46
- The target is a Program-PRD issue: it carries the `<!-- prd: program -->` marker (or
47
- the program-type label) and a `## Wellenplan` table. Passed in / from context. If the
48
- issue is a plain feature-PRD or a Welle-Anchor, stop a feature-PRD is `to-issues`'
49
- target, an anchor is already a single wave.
54
+ The target is a Program-PRD issue: it carries both the
55
+ `<!-- prd: program -->` marker and the configured Program-type label, plus a
56
+ `## Wellenplan` table. Passed in from the facade or explicit compatibility
57
+ invocation. If either identity half is missing, they disagree, or Feature
58
+ identity is also present, stop before preview or write and return to
59
+ `to-issues`; never infer Program mode from the table, prose, size, or model
60
+ judgment. A plain Feature-PRD remains on the facade's Feature path; a
61
+ Wave-Anchor is already a single wave.
50
62
 
51
63
  ## 2. Parse + validate — the graph preflight
52
64
 
@@ -316,7 +328,7 @@ python3 scripts/board-sync.py program-sync <prd#>
316
328
  ## Audit block (visible output)
317
329
 
318
330
  ```
319
- to-waves: prd=#<n> preview=<approved|rejected>
331
+ to-issues: planning-mode=program engine=to-waves prd=#<n> preview=<approved|rejected>
320
332
  created=<stubs X von Y, leaves X von Y> adopted=<#a #b … | none>
321
333
  stamped=<N von M Wave/Phase> phase=<stamped | skipped (profile lacks fields.phase)>
322
334
  matured=<X von Y> execute-ready=<X von Y Wellen ausführungsreif>
package/README.md CHANGED
@@ -85,9 +85,11 @@ into the *same shaped artefact*: a Draft-PRD that, once sliced, becomes either o
85
85
  atomic issue or a wave anchor with child slices. What counts downstream is the
86
86
  **shape of the artefact, never where it came from** — so each step can be entered
87
87
  cold and *extracts or synthesizes* what's missing instead of assuming an earlier
88
- step ran. The routing key is just *"is there an issue yet?"*: a loose artefact
88
+ step ran. The entry key is just *"is there an issue yet?"*: a loose artefact
89
89
  (no issue) enters at `to-prd`; an existing issue or file-bundle enters at
90
- `to-issues` directly.
90
+ `to-issues` directly. Inside that facade, the explicit PRD identity — Feature or
91
+ Program — is the only mode selector; a cold source must establish one before a
92
+ remote write.
91
93
 
92
94
  - **Grill as deep as the work deserves — it's optional.** `grill-me` /
93
95
  `grill-with-docs` interrogate the intent (and your domain docs) until the real
@@ -98,13 +100,15 @@ step ran. The routing key is just *"is there an issue yet?"*: a loose artefact
98
100
  Draft-PRD issue, *extracting* the template sections from what already exists. A
99
101
  required section it genuinely can't derive becomes an honest **Open points**
100
102
  block, never a silent "looks complete" placeholder.
101
- - **`to-issues`** slices the PRD into tracer-bullet verticals and picks the shape:
102
- **1 slice one atomic issue** the PR closes; **≥2 slices a wave anchor** with
103
- linked child slices. It re-derives readiness from the artefact itself, so it works
104
- just as well started straight on a raw issue or file-bundle — any unresolved
105
- *Open points* travel through as a build-blocking gate (the profile's
106
- configurable `vorBau` heading, see [Configuration](#configuration)) that never
107
- vanishes silently.
103
+ - **`to-issues`** is the single public Planning facade. Explicit Feature
104
+ identity selects tracer-bullet decomposition and picks the shape: **1 slice
105
+ one atomic issue** the PR closes; **≥2 slices a wave anchor** with linked
106
+ child slices. Explicit Program identity selects the existing internal graph
107
+ engine and preserves its complete chat preview before any board write.
108
+ Missing or contradictory identity stops before a write; size, prose, and model
109
+ judgment never select the mode. Any unresolved *Open points* travel through as
110
+ a build-blocking gate (the profile's configurable `vorBau` heading, see
111
+ [Configuration](#configuration)) that never vanishes silently.
108
112
  - **`board-to-waves`** clusters an existing backlog into themed campaigns when you
109
113
  need to *find* the next wave rather than start fresh.
110
114
  - **`triage`** keeps the inbox sane with a consistent label vocabulary.
@@ -211,7 +215,8 @@ hands a well-defined object to the level below:
211
215
 
212
216
  Two roads lead to the same wave. **Top-down:** `scale-check` names the size in
213
217
  a few plain questions; a big undertaking gets grilled once into a Program PRD
214
- with a wave plan, and `to-waves` unfolds it into named waves after you approve
218
+ with a wave plan, and `to-issues` selects its internal Program graph path from
219
+ that explicit identity. It unfolds the plan into named waves after you approve
215
220
  a full preview in chat — zero board writes until you say yes. **Bottom-up:**
216
221
  `board-to-waves` clusters loose issues into a wave candidate, which earns a
217
222
  real number only when you promote it. Either road lands in the *identical*
@@ -222,7 +227,7 @@ When the slices are file-disjoint and their specs are locked, **`orchestrate-wav
222
227
  lands the whole anchor end-to-end — often AFK: it dispatches an implementer per
223
228
  slice into its own worktree, integrates serially, verifies centrally, and lands
224
229
  the wave. It's the execute-and-land node of the wave ladder (`scale-check` →
225
- `to-waves` / `board-to-waves` → `orchestrate-wave`); a single slice still just
230
+ `to-issues` / `board-to-waves` → `orchestrate-wave`); a single slice still just
226
231
  goes to `implement`.
227
232
 
228
233
  ![The Program-to-Phase-to-Wave-to-Slice altitude ladder, and the two routes — a planned top-down Program route and a grown bottom-up board route — that both fund the same Wave-and-Slices build spine.](docs/methodology.svg)
@@ -349,8 +354,118 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
349
354
  `--force` (overwrite pre-existing untracked files on `init`), `--yes` / `-y`
350
355
  (accept non-interactive update decisions).
351
356
 
357
+ ## Upgrade notes
358
+
359
+ ### 0.33.0 — capability-gated orchestration
360
+
361
+ `kit-update` reconciles this release for you. These notes matter only if you
362
+ maintain a **local fork of `orchestrate-wave`**: the blocks below changed
363
+ behaviour, so a forked copy must re-apply them by hand or it keeps orchestrating
364
+ the old way. Decision record:
365
+ [`docs/adr/0002-capability-gated-orchestration.md`](docs/adr/0002-capability-gated-orchestration.md).
366
+
367
+ - **Capability matrix, fail-closed.** The dispatch mechanic is selected from
368
+ host-supplied capability evidence, degrading A → B → C. Missing or `unknown`
369
+ evidence never proves a capability, and Path C (direct, serial) is always
370
+ available.
371
+ - **No emulation of a missing primitive.** A host without a scripted workflow
372
+ runtime gets the simpler recipe, never a hand-rolled imitation of one.
373
+ - **Codex Path B is native subagents.** Explicit per-slice spawns joined by an
374
+ explicit wait — dormant until a host supplies the complete normalized
375
+ inventory.
376
+ - **JSON-schema reports plus independent verification.** Every path returns
377
+ schema-valid recon and builder reports and crosses the same main-thread
378
+ boundary; a builder's own PASS is a hypothesis until `semanticVerify` confirms
379
+ it against independently collected Git facts.
380
+ - **Per-batch, post-hub worktree provisioning.** Worktrees are created serially
381
+ in the main thread from the integrated base after the hub lands, under an
382
+ atomic compare-and-set wave claim; reuse on a stale base now STOPs.
383
+ - **Heartbeat during long gates.** Long-running gates report status rather than
384
+ waiting silently.
385
+
352
386
  ## Release notes
353
387
 
388
+ ### 0.34.0
389
+
390
+ - added: `src/commands/routing-policy-update.mjs`
391
+ - added: `src/lib/agentSurfaceRegistry.mjs`
392
+ - added: `src/lib/dispatchReceipt.mjs`
393
+ - added: `src/lib/frontendWorkloads.mjs`
394
+ - added: `src/lib/routeDispatcher.mjs`
395
+ - added: `src/lib/routingAccessGraph.mjs`
396
+ - added: `src/lib/routingAdapters/claude.mjs`
397
+ - added: `src/lib/routingAdapters/codex.mjs`
398
+ - added: `src/lib/routingCatalog.mjs`
399
+ - added: `src/lib/routingEvidenceCache.mjs`
400
+ - added: `src/lib/routingIntent.mjs`
401
+ - added: `src/lib/routingPolicy.mjs`
402
+ - added: `src/lib/routingProfile.mjs`
403
+ - added: `src/lib/routingResolver.mjs`
404
+ - added: `src/lib/routingSources/artificialAnalysis.mjs`
405
+ - added: `src/lib/routingSources/benchlm.mjs`
406
+ - added: `src/lib/routingSources/codeArena.mjs`
407
+ - added: `src/lib/routingSources/deepswe.mjs`
408
+ - added: `src/lib/routingSources/openhands.mjs`
409
+ - added: `src/lib/routingSources/openhandsFrontend.mjs`
410
+ - changed: `.agents/skills/ask-matt/SKILL.md`
411
+ - changed: `.agents/skills/audit-skills/SKILL.md`
412
+ - changed: `.agents/skills/board-to-waves/SKILL.md`
413
+ - changed: `.agents/skills/code-review/SKILL.md`
414
+ - changed: `.agents/skills/codebase-design/DESIGN-IT-TWICE.md`
415
+ - changed: `.agents/skills/codex-adapter-sync/SKILL.md`
416
+ - changed: `.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md`
417
+ - changed: `.agents/skills/improve-codebase-architecture/SKILL.md`
418
+ - changed: `.agents/skills/kit-update/SKILL.md`
419
+ - changed: `.agents/skills/orchestrate-wave/SKILL.md`
420
+ - changed: `.agents/skills/orchestrate-wave/references/dispatch-subagents.md`
421
+ - changed: `.agents/skills/orchestrate-wave/references/dispatch-workflow.md`
422
+ - changed: `.agents/skills/research/SKILL.md`
423
+ - changed: `.agents/skills/scale-check/SKILL.md`
424
+ - changed: `.agents/skills/setup-workflow/SKILL.md`
425
+ - changed: `.agents/skills/setup-workflow/board-sync.md`
426
+ - changed: `.agents/skills/setup-workflow/workflow-overview.md`
427
+ - changed: `.agents/skills/to-issues/SKILL.md`
428
+ - changed: `.agents/skills/to-waves/SKILL.md`
429
+ - changed: `.claude/skills/ask-matt/SKILL.md`
430
+ - changed: `.claude/skills/audit-skills/SKILL.md`
431
+ - changed: `.claude/skills/board-to-waves/SKILL.md`
432
+ - changed: `.claude/skills/code-review/SKILL.md`
433
+ - changed: `.claude/skills/codebase-design/DESIGN-IT-TWICE.md`
434
+ - changed: `.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md`
435
+ - changed: `.claude/skills/improve-codebase-architecture/SKILL.md`
436
+ - changed: `.claude/skills/kit-update/SKILL.md`
437
+ - changed: `.claude/skills/orchestrate-wave/SKILL.md`
438
+ - changed: `.claude/skills/orchestrate-wave/references/dispatch-subagents.md`
439
+ - changed: `.claude/skills/orchestrate-wave/references/dispatch-workflow.md`
440
+ - changed: `.claude/skills/research/SKILL.md`
441
+ - changed: `.claude/skills/scale-check/SKILL.md`
442
+ - changed: `.claude/skills/setup-workflow/SKILL.md`
443
+ - changed: `.claude/skills/setup-workflow/board-sync.md`
444
+ - changed: `.claude/skills/setup-workflow/workflow-overview.md`
445
+ - changed: `.claude/skills/to-issues/SKILL.md`
446
+ - changed: `.claude/skills/to-waves/SKILL.md`
447
+ - changed: `docs/agents/wave-anchor-template.md`
448
+ - changed: `scripts/codex-exec.sh`
449
+ - changed: `src/lib/capabilityMatrix.mjs`
450
+
451
+ ### 0.33.0
452
+
453
+ - added: `.agents/skills/orchestrate-wave/references/dispatch-subagents.md`
454
+ - added: `.agents/skills/orchestrate-wave/references/dispatch-workflow.md`
455
+ - added: `.agents/skills/orchestrate-wave/references/report-contracts.md`
456
+ - added: `.claude/skills/orchestrate-wave/references/dispatch-subagents.md`
457
+ - added: `.claude/skills/orchestrate-wave/references/dispatch-workflow.md`
458
+ - added: `.claude/skills/orchestrate-wave/references/report-contracts.md`
459
+ - added: `src/lib/capabilityMatrix.mjs`
460
+ - added: `src/lib/reconcileReconReports.mjs`
461
+ - added: `src/lib/reportValidator.mjs`
462
+ - added: `src/lib/waveClaim.mjs`
463
+ - changed: `.agents/skills/orchestrate-wave/SKILL.md`
464
+ - changed: `.agents/skills/orchestrate-wave/references/builder-contract.md`
465
+ - changed: `.claude/skills/orchestrate-wave/SKILL.md`
466
+ - changed: `.claude/skills/orchestrate-wave/references/builder-contract.md`
467
+ - changed: `scripts/worktree-lifecycle/setup.py`
468
+
354
469
  ### 0.32.1
355
470
 
356
471
  - changed: `.agents/skills/census-update/SKILL.md`