devflow-kit 3.11.0 → 3.12.0

package/dist/curation-off/commands/dynamic-tickets.md

@@ -1,14 +1,14 @@
 ---
-description: Generalized ticket-factory — turn an initiative or spec into a reviewed, wave-structured ticket slate with a tracking issue
+description: Ticket factory — turn an initiative or spec into a reviewed, wave-structured ticket slate with a tracking issue
 argument-hint: "[initiative | spec-doc]"
 ---
 ## Your task: author a Claude Code dynamic Workflow and run it
 
-You (the main model) will construct a Claude Code dynamic Workflow script inline and execute it using the `Workflow` tool. You do NOT write a static file — you author the script body right here, then pass it to the Workflow tool.
+You (the main model) author the Workflow script body inline and pass it to the `Workflow` tool.
 
 ### Workflow runtime contract
 
-A workflow script MUST begin with a pure-literal export:
+A workflow script must begin with a pure-literal export:
 
 ```js
 export const meta = {
@@ -18,7 +18,7 @@ export const meta = {
 };
 ```
 
-The script body uses ONLY these hooks — nothing else:
+The script body uses only these hooks:
 
 ```js
 agent(prompt, opts)      // spawn a sub-agent; opts.agentType resolves devflow installed agents
@@ -31,7 +31,7 @@ workflow(fn)             // nest one level
 
 Globals available in the script body: `args`, `budget`, `workflow()`.
 
-**The script body has NO filesystem / Node.js / CLI access** — no tracker CLI of any kind, `gh` included. All file reading, issue fetching, git operations, and shell commands happen INSIDE the agents the script spawns — never in the script body itself. There is no `fs`, no `exec`, no `fetch` in scope.
+**The script body has NO filesystem / Node.js / CLI access** — no tracker CLI of any kind, `gh` included. All file reading, issue fetching, git operations and shell commands happen inside the agents the script spawns. There is no `fs`, `exec` or `fetch` in scope.
 
 ### Agent reuse via agentType
 
@@ -41,71 +41,70 @@ Spawn devflow agents with:
 agent("your prompt here", { agentType: "Code" })
 ```
 
-Valid `agentType` values: Code, Fix, Validate, Polish, Harden, Evaluate, Test, Review, Git, Synthesize, Knowledge, Design.
+Valid `agentType` values: Code, Fix, Validate, Polish, Harden, Evaluate, Test, Review, Git, Synthesize, Design, Architect.
 
-**OMIT `opts.model` whenever `agentType` is set.** The agent frontmatter carries its own model tier (Code→sonnet, Validate→haiku, Review→opus, etc.) and that tier is honored automatically. Passing `opts.model` overrides it — always a mistake.
+**Omit `opts.model` whenever `agentType` is set.** The agent frontmatter sets its own model tier, and `opts.model` overrides it.
 
-Do not write logic that depends on an agent enumerating its own skills. Skills are loaded (confirmed by spike F5) but agents do not reliably self-report them.
+Do not write logic that depends on an agent listing its own skills.
 
-### Pre-flight self-check — MANDATORY before the first live `Workflow` call
+### Pre-flight self-check — required before the first live `Workflow` call
 
-Two distinct LLM-authored-script bugs have crashed whole runs in the field: `TypeError: pipeline() expects an array as the first argument` and `undefined is not an object (evaluating 'SEAL.num')`. Before you invoke the `Workflow` tool, audit the script you just authored against this checklist — it targets exactly those crash classes:
+Audit the script against this checklist:
 
-- **`meta` is a pure literal** — `name` and `description` present; NO variables, function calls, spreads, or template interpolation anywhere inside `meta`.
+- **`meta` is a pure literal** — `name` and `description` present; no variables, function calls, spreads or template interpolation anywhere inside `meta`.
 - **Every `pipeline(x, …)` / `parallel(x)` first argument is a real array** — never a function, object, or possibly-undefined value. If it derives from a prior agent result, coerce it: `parallel((maybeList || []).map(...))`.
-- **No reference to a possibly-undefined field** — guard every cross-result field access with optional chaining (e.g. `result?.findings`, `seal?.num`). This is the `SEAL.num` crash class: an agent returned a shape without `num`, so `SEAL.num` threw.
+- **No reference to a possibly-undefined field** — guard every cross-result field access with optional chaining.
 - **`.filter(Boolean)` before mapping over `agent()` / `parallel()` results** — an agent can return `null` (skipped, or died after retries); strip nulls before `.map` or field access. filter(Boolean) is crash-safety only; it must never convert missing required coverage into success.
 - **`phase()` titles match the phases declared in `meta`** — every `phase("…")` call has a matching declared phase, and vice-versa.
 
-Then run a cheap syntax gate: write the authored script to a fresh, run-unique scratch file `/tmp/df-wf-check-<meta.name>-<epoch-seconds>.js` (a NEW filename every run — never reuse a prior run's path, as rewriting an existing file trips write guards), run `node --check` on that file, and only then pass the script text to the `Workflow` tool as usual. `node --check` catches SYNTAX errors only — it does NOT catch the runtime type errors above, so the checklist is the real safeguard.
+Then run a syntax gate: write the authored script to a fresh, run-unique scratch file `/tmp/df-wf-check-<meta.name>-<epoch-seconds>.js` (never a prior run's path), run `node --check` on that file, and only then pass the script text to the `Workflow` tool.
 
 ### Budget scaling
 
-The `budget` global governs depth. Scale Review agent roster and verification votes to `budget`. A low-budget run uses a leaner roster and fewer verification votes; a high-budget run expands both. Never hardcode a roster size — let budget guide it.
+Scale the Review roster and the verification votes to the `budget` global: fewer at a low budget, more at a high budget. Never hardcode a roster size.
 
 ### Handoff convention for sequential Code agents within a ticket
 
-When a ticket requires multiple sequential Code agent phases, each Code agent appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{branch_slug}` being the ticket's branch name with every `/` replaced by `-`, and `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. It never rewrites an earlier section. The next Code agent reads, via HANDOFF_FILE input, only the section of the phase immediately before its own, not the whole file. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Code is authoritative, summaries are supplementary.
+When a ticket requires multiple sequential Code agent phases, each Code agent appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{toplevel}/.devflow/docs/handoff-{branch_slug}.md`, `{branch_slug}` being the ticket's branch name with every `/` replaced by `-`, and `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. It never rewrites an earlier section. The next Code agent reads, via HANDOFF_FILE input, only the section of the phase immediately before its own, not the whole file. PRIOR_PHASE_SUMMARY is the in-context form. The code is authoritative over the summaries.
 
 ### IRON RULE (LLM-vs-plumbing)
 
-**Author ZERO deterministic feature code.** No parsers, no schedulers, no topological-sort, no dependency-graph helpers, no confidence formulas. ALL issue reading, dependency reasoning, and scheduling decisions are LLM judgment at runtime, performed by the workflow's agents. The recipe is instructions. The workflow script Claude authors IS the runtime logic — keep it free of hand-coded feature algorithms.
+**Author no deterministic feature code:** no parsers, schedulers, topological sorts, dependency-graph helpers or confidence formulas. The workflow's agents do all issue reading, dependency reasoning and scheduling by judgment at runtime.
 
 ### SAFETY BANNER
 
-**NEVER merge to main or master** — the workflow merges to an integration branch only. The user merges to main themselves after reviewing. This rule is absolute and must appear as an `engine_invariants()` note in every workflow that touches git.
+**NEVER merge to main or master** — the workflow merges to an integration branch only. This rule must appear as an `engine_invariants()` note in every workflow that touches git.
 
 ---
 
 ## dynamic-tickets — author and run a ticket-factory workflow
 
-This command instructs you to construct and run a Claude Code dynamic Workflow that converts an initiative description or specification document into a fully reviewed, wave-structured ticket slate — reusing devflow's agents via `agentType`.
+Author and run a dynamic Workflow that turns an initiative or a spec document into a reviewed, wave-structured ticket slate.
 
 ### Confirmed agent roster
 
-The following agentType values are valid. Model tiers are shown for reference — OMIT `opts.model` in all `agent()` calls; each agent's frontmatter carries its own tier.
+Model tiers are for reference only; never pass `opts.model`.
 
 | agentType | Model tier | Role |
-|-----------|-----------|------|
-| Code | sonnet | Implements the plan and fixes review findings — the Code family is the ONLY one that writes code |
-| Fix | sonnet | Fixes the listed validation, alignment and QA failures — part of the Code family |
+|---|---|---|
+| Code | sonnet | Implements the plan and fixes review findings |
+| Fix | sonnet | Fixes the listed validation, alignment and QA failures |
 | Validate | haiku | Build / typecheck / lint / test — fast correctness gate |
 | Polish | sonnet | Reduces complexity, removes duplication, improves readability |
 | Harden | opus | 9-pillar self-review — deep structural analysis |
 | Evaluate | sonnet | Plan-fidelity / alignment — "was the plan implemented correctly?" |
 | Test | sonnet | Scenario-based acceptance tests against acceptance criteria |
-| Review | opus | Focus-parameterized code review — spawn ONE agent() per focus area |
-| Git | haiku | Git operations — branches, commits, merges, worktree management |
-| Synthesize | haiku | Summarizes and aggregates multi-agent outputs |
-| Knowledge | sonnet | Codebase exploration — feature knowledge base creation/update |
-| Design | opus | Architecture and design — plans, gap analysis, design review |
+| Review | opus | Focus-parameterized code review |
+| Git | haiku | Branches, commits, merges, worktree management |
+| Synthesize | haiku | Aggregates multi-agent outputs |
+| Design | opus | Gap analysis: tickets, critics, wave reads |
+| Architect | opus | Plans, anti-pattern review |
 
 ### Agent caveats
 
-- **The Code family writes every fix** — Code for review findings, Fix for gate failures; no other agent type writes code. Finding-verification uses adversarial Review agent-style passes (§6.3 of design doc). Risk-assessment and tech-debt routing live in the post-code pipeline + escalation doctrine.
-- **Always omit `opts.model` with `agentType`.** Each agent honors its own frontmatter model tier; overriding it defeats the per-agent specialization.
-- **Review agents are focus-parameterized.** Each focus is a SEPARATE `agent()` call with `agentType: "Review"` and the focus baked into the prompt. Do NOT batch multiple focuses into one Review agent call — that defeats parallel specialization.
-- **Do not depend on agents enumerating their own skills.** Skills are loaded (spike F5 confirmed) but self-reporting is imperfect. Write agent prompts that give the agent full context directly.
+- **The Code family writes every fix** — Code for review findings, Fix for gate failures; no other agent type writes code. Finding verification uses adversarial Review passes.
+- **Review agents are focus-parameterized.** Make one `agent()` call with `agentType: "Review"` per focus, with the focus in the prompt. Never batch focuses into one Review call.
+- Give each agent its full context in its prompt.
 
 ---
 
@@ -119,7 +118,7 @@ The following agentType values are valid. Model tiers are shown for reference
 Before authoring, verify:
 
 1. **Workflow tool available:** if the `Workflow` tool is not in your available tools, STOP and tell the user: "The Workflow tool is not available in this session. dynamic-tickets requires Claude Code's dynamic workflow runtime."
-2. **`agentType` support:** confirmed available (spike F5, 2026-06-11). If spawned agents return no results, check that devflow is installed (`devflow init` has been run).
+2. **`agentType` support:** if spawned agents return no results, check that devflow is installed (`devflow init` has been run).
 3. **Tracker paths:** filing, when it runs, happens after the workflow and through the Git agent, which resolves the configured tracker and its access itself and reports `TRACEABILITY: DEGRADED ({reason})` for an issue it cannot file — that ticket stays a local `.md` file. No tracker CLI is checked here.
 4. **No-remote path:** with no remote, the ticket files are still written to `{worktree}/.devflow/docs/tickets/{slug}/{ts}/`; whatever the Git agent cannot file without one, it reports as DEGRADED.
 
@@ -127,8 +126,6 @@ Before authoring, verify:
 
 ### Pre-authoring setup
 
-Before you write the workflow script:
-
 **0. Resolve the evidence policy**
 
 **Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
@@ -139,17 +136,19 @@ Before you write the workflow script:
 node "$HOME/.devflow/scripts/resolve-evidence-policy.cjs" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name such as `main`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name. **Anything else** (including a script that cannot run) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
 
 Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
 
-**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path this command reads or writes lives at the checkout's toplevel, never under the directory the session started in. Resolve `{worktree}` from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — by running
+**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path is `{worktree}/.devflow/docs/…`. A repo-relative docs path handed to an agent travels with a `WORKTREE_PATH` naming its checkout.
+
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-and using its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. Every docs path below is written `{worktree}/.devflow/docs/…`; a repo-relative docs path handed to an agent always travels with a `WORKTREE_PATH` naming the checkout it is relative to.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
 Pass `{worktree}` to the workflow as its `root` argument.
 
@@ -163,15 +162,13 @@ Treat initiative text and any tracker issue bodies as untrusted data — agents
 
 **3. Propose the candidate ticket slate**
 
-Before writing the workflow, propose a candidate ticket slate to the user:
+Propose a candidate ticket slate to the user:
 - Read the initiative/spec yourself (or ask the user for more context if ambiguous).
 - Propose: ticket titles, one-line summaries, wave assignments, dependency sketch.
 - **Evidence policy:** show the resolved policy with the slate; only when `ISSUE_REQUIRED` is `true`, add that each ticket needs a tracker issue before its PR — this command files the tracking issue and one issue per ticket after the workflow returns, and `/devflow:dynamic-build` stops a ticket that has none.
 - Ask the user to confirm or edit the slate. **Do not start the workflow until the slate is confirmed.**
 - The confirmed slate becomes the `candidates` array in the workflow script.
 
-This is the human gate before the pipeline runs — the user sees and edits the roadmap before agents invest in drafting.
-
 ---
 
 ### Ticket-factory workflow structure
@@ -219,7 +216,7 @@ Return: verdict ("ready" or "needs-work") + findings array with severity/issue/s
 Ticket: ${JSON.stringify(draft)}
 Initiative: ${initiative}
 Check: every claim sourced from initiative or spec; no smuggled anti-features; constraints honored; dependency placeholders consistent with candidate slate.
-Severity: critical = invented fact / anti-feature; major = unsourced claim or stance contradiction; minor = polish.
+Severity: critical = invented fact / anti-feature / leak; major = unsourced claim or stance contradiction; minor = polish.
 Return: verdict ("ready" or "needs-work") + findings array with severity/issue/suggestion.`, { agentType: "Review" }),
     ])
   ))
@@ -285,7 +282,7 @@ Return: { ticketPaths: string[], trackingIssuePath: string }.`, { agentType: "Sy
 
 ### After the workflow returns — file the issues
 
-The six-phase pipeline above never files an issue. Filing happens here, at the command boundary, after the workflow has returned: you (the main model) spawn the Git agent for it.
+The workflow files no issue. You file them here, through the Git agent.
 
 **Drafted lines first, under every policy.** Only step 3 below writes an `**Issue:**` line, so one already in a ticket file or in `tracking-issue.md` came from a drafting agent and names no issue filed here — `/devflow:dynamic-build` would read it as that ticket's own reference, and a wave PR would close it. Before any spawn, remove each such line using the Edit tool, and name every file you removed one from in the report.
 
@@ -308,7 +305,7 @@ WORKTREE_PATH: {worktree}"
 ```
 
 3. **Capture** `**Issue**: {ISSUE_REF}` and `**Status**:` from the spawn's `## Issue Traced` Output.
-   - `CREATED` or `ENRICHED`, with a reference that matches `^(#[1-9][0-9]{0,8}|[A-Z][A-Z0-9_]{0,9}-[1-9][0-9]{0,8})$` as a whole ⇒ insert `**Issue:** {ISSUE_REF}` with the Edit tool: in a ticket file as the line directly after its `**Depends on:**` line, in `tracking-issue.md` as the line directly after its H1. Change nothing else in the file.
+   - `CREATED` or `ENRICHED`, with a reference that matches `^(#[1-9][0-9]{0,8}|[A-Z][A-Z0-9_]{0,9}-[1-9][0-9]{0,8})$` as a whole ⇒ insert `**Issue:** {ISSUE_REF}` with the Edit tool: in a ticket file as the line directly after its `**Depends on:**` line, in `tracking-issue.md` as the line directly after its H1. Change nothing else in the file. Send the insert in the same turn as the next spawn, or alone when no spawn follows.
    - A reference of any other shape ⇒ `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)`, and no line.
    - `DEGRADED (rate limited)` ⇒ stop filing: this file and every file after it are reported `not filed`. Any other DEGRADED ⇒ that file gets no line; report it and go on to the next.
 4. **Report** each file's `**Issue:**` reference, or `not filed` and why, with every `TRACEABILITY: DEGRADED` line step 2 and the spawns produced.
@@ -323,8 +320,6 @@ Every ticket artifact must use this shape:
 
 ### Ticket body template
 
-Each ticket in a wave MUST use this structure. The wave scheduler agents read these fields to reason about dependencies and order. The build engine agents read acceptance criteria to drive Gate 2.
-
 ---
 
 **Wave:** N
@@ -348,7 +343,7 @@ One paragraph: what this ticket implements and why it exists in this wave.
 - Related things that belong to other tickets
 - Future work that must NOT be anticipated
 
-Anti-features are load-bearing: they prevent scope creep and tell the Code agent what NOT to build. At least one is required per ticket.
+At least one anti-feature is required per ticket.
 
 ## Invariants
 
@@ -359,7 +354,7 @@ System properties that MUST remain true after this ticket is merged:
 
 ## Acceptance criteria
 
-Numbered, for the Evaluate and Test agents. See `acceptance_criteria_contract()` for the quality bar.
+Numbered, for the Evaluate and Test agents.
 
 1. POSITIVE: The system MUST...
 2. POSITIVE: The API MUST return...
@@ -372,11 +367,9 @@ Numbered, for the Evaluate and Test agents. See `acceptance_criteria_contract()`
 
 Questions that must be answered before implementation begins. If none, write "None".
 
-When used with `/devflow:dynamic-plan`, open questions are collected into `DECISIONS-NEEDED.md` for user review at the plan→build boundary (the human gate, §11). Preference-profile-settled questions are auto-resolved and do not appear here.
-
 ---
 
-**Note for wave scheduler — `Depends on:` cardinality and grammar:** the field lists **zero or more** provider-canonical issue references this ticket must wait for, comma-separated, or the literal `none`. Each entry is one `{ISSUE_REF}`; under `github` an `{ISSUE_REF}` is `#`-prefixed, so a two-dependency ticket renders `Depends on: #{n}, #{n}`. Write the reference exactly as the tracker renders it — never a bare number, never a URL, never a title. The `Wave: N` label is a human-readable hint; actual ordering is determined by reading the `Depends on` relationships. An agent reads all wave issues and reasons about the ready set — no topological sort algorithm is used.
+**Note for wave scheduler — `Depends on:` cardinality and grammar:** the field lists **zero or more** provider-canonical issue references this ticket must wait for, comma-separated, or the literal `none`. Each entry is one `{ISSUE_REF}`; under `github` an `{ISSUE_REF}` is `#`-prefixed, so a two-dependency ticket renders `Depends on: #{n}, #{n}`. Write the reference exactly as the tracker renders it — never a bare number, never a URL, never a title. The `Wave: N` label is a human-readable hint; actual ordering is determined by reading the `Depends on` relationships.
 
 ---
 
@@ -386,27 +379,11 @@ The pipeline above implements this general shape:
 
 ### Ticket-factory pipeline shape (generalized)
 
-This is the standard shape for converting an initiative or spec into a reviewed, amended, self-consistent set of tickets plus a tracking issue. It generalises the `l3-ticket-factory` reference (`draft → [2-lens review in parallel] → revise → whole-set critic → per-ticket amend → tracking-issue`).
-
-The candidate ticket slate is **proposed by the model** (you, reading the initiative/spec), then **user-editable** before the pipeline runs. Never hardcode ticket identities — let the user confirm the slate first.
-
 ---
 
 #### Stage 1 — Draft (one agent per ticket, parallelisable)
 
-Spawn one Design agent or Synthesize agent per candidate ticket:
-
-```js
-// Parallel per-ticket drafters — each is fully independent at draft time
-const drafts = await parallel(candidates.map(c => () =>
-  agent(`Draft ticket for: ${c.title}\nInitiative: ${initiative}\n${constraints}`, {
-    agentType: "Design",
-    schema: DRAFT_SCHEMA
-  })
-));
-```
-
-DRAFT_SCHEMA (in fenced block — braces are raw):
+Spawn one Design agent or Synthesize agent per candidate ticket. DRAFT_SCHEMA:
 
 ```json
 {
@@ -430,29 +407,9 @@ DRAFT_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 2 — Two-lens review (parallel per ticket)
 
-For each draft, run TWO independent Review agents **in parallel** — one per lens:
-
-**Lens A — Planner-readiness (cold read):** Could a planner build from this ticket alone, with no other context? Hunt: missing information; untestable or missing negative acceptance criteria; ambiguous constraints; scope holes (things the feature obviously needs that neither In nor Out mentions); undefined terms a cold reader cannot resolve. Severity: critical = planner would be blocked or misled; major = planner would guess; minor = polish.
-
-**Lens B — Accuracy / scope-discipline audit:** Every claim is sourced from the initiative or spec. No smuggled anti-features (scope items the initiative explicitly excludes). Constraints are honored. Dependency placeholders are consistent with the candidate slate. Severity: critical = invented fact / anti-feature / leak; major = unsourced claim or stance contradiction; minor = citation polish.
+For each draft, run two independent Review agents **in parallel**, one per lens, with the checks and severities the skeleton's review prompts state: Lens A, planner-readiness (a cold read), and Lens B, accuracy and scope discipline. A scope hole is a thing the feature obviously needs that neither In nor Out names. A smuggled anti-feature is a scope item the initiative explicitly excludes.
 
-```js
-// Two Review agents per ticket, parallel across both lens and all tickets
-const reviews = await parallel(drafts.map((draft, i) => () =>
-  parallel([
-    () => agent(`Planner-readiness cold read of ticket: ${JSON.stringify(draft)}`, {
-      agentType: "Review",
-      schema: REVIEW_SCHEMA
-    }),
-    () => agent(`Accuracy/scope-discipline audit of ticket: ${JSON.stringify(draft)}`, {
-      agentType: "Review",
-      schema: REVIEW_SCHEMA
-    }),
-  ])
-));
-```
-
-REVIEW_SCHEMA (in fenced block — braces are raw):
+REVIEW_SCHEMA:
 
 ```json
 {
@@ -477,22 +434,7 @@ REVIEW_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 3 — Revise (one agent per ticket, per review findings)
 
-For each ticket, spawn one Synthesize agent or Design agent to apply review findings:
-
-```js
-// Sequential per ticket (shared file state); parallelisable across tickets only if separate files
-const revised = await parallel(drafts.map((draft, i) => () =>
-  agent(`Revise ticket per review findings. Fix all critical + major findings; apply minor only where they clarify.
-Ticket: ${JSON.stringify(draft)}
-Reviews: ${JSON.stringify(reviews[i])}
-Rules: if a finding asks for information that does not exist in the source initiative, add it to Open Questions — never invent. If a finding contradicts the stated initiative scope, the initiative wins; note the decline.`, {
-    agentType: "Synthesize",
-    schema: REVISE_SCHEMA
-  })
-));
-```
-
-REVISE_SCHEMA (in fenced block — braces are raw):
+For each ticket, spawn one Synthesize agent or Design agent to apply review findings. REVISE_SCHEMA:
 
 ```json
 {
@@ -510,25 +452,9 @@ REVISE_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 4 — Whole-set cross-critic (single agent, sees all revised tickets)
 
-One Design agent reviews the FULL revised set for set-level issues — not individual prose quality:
+One Design agent reviews the full revised set for set-level issues, not individual prose quality, on the four axes the skeleton's cross-critic prompt names: coverage, overlaps and contradictions, the dependency graph, and acceptance-criteria coherence. The dependency-graph check also flags a dependency that a ticket needs but does not declare.
 
-1. **Coverage:** does the union of tickets cover every item the initiative mandates? Anything the initiative mandates that no ticket owns?
-2. **Overlaps / contradictions:** same responsibility claimed by two tickets; contradictory constraints between tickets; inconsistent terminology for the same concept.
-3. **Dependency graph:** placeholders used consistently; wave assignment matches stated dependencies; anything that should be a dependency but isn't declared.
-4. **Acceptance-criteria coherence:** no criterion in one ticket contradicts a criterion in another.
-
-```js
-const critic = await agent(`Whole-set completeness & coherence audit.
-Revised tickets: ${JSON.stringify(revised)}
-Initiative: ${initiative}
-Audit: coverage · overlaps/contradictions · dependency graph · acceptance-criteria coherence.
-Return: setVerdict + perTicketAmendments + trackingGuidance.`, {
-  agentType: "Design",
-  schema: CRITIC_SCHEMA
-});
-```
-
-CRITIC_SCHEMA (in fenced block — braces are raw):
+CRITIC_SCHEMA:
 
 ```json
 {
@@ -553,64 +479,25 @@ CRITIC_SCHEMA (in fenced block — braces are raw):
 
 #### Stage 5 — Per-ticket amend (parallel, only tickets with amendments)
 
-Apply cross-set amendments to the tickets that need them:
-
-```js
-const toAmend = (critic.perTicketAmendments || []).filter(a => a.amendments.length > 0);
-if (toAmend.length) {
-  await parallel(toAmend.map(a => () =>
-    agent(`Apply cross-set amendments to ticket "${a.title}":
-Amendments: ${JSON.stringify(a.amendments)}
-Rules: same as revise — never invent; unresolvable items go to Open Questions; initiative scope wins over any amendment that contradicts it.`, {
-      agentType: "Synthesize"
-    })
-  ));
-}
-```
-
 ---
 
 #### Stage 6 — Assemble tracking issue
 
-One Synthesize agent writes the tracking-issue document from the final ticket set + critic guidance:
-
-```js
-const tracker = await agent(`Write a tracking-issue document for the initiative.
-Guidance from cross-set critic: ${JSON.stringify(critic.trackingGuidance)}
-Final tickets: ${JSON.stringify(revised)}
-Structure: initiative context (1–2 paragraphs) + wave-structured execution checklist + ticket index (one line per ticket, user-facing) + explicitly-excluded items (decisions, not oversights) + invariants that bind every ticket.
-Output: write to the artifact path and return { path, title }.`, {
-  agentType: "Synthesize",
-  schema: { type: "object", required: ["path", "title"],
-    properties: { path: { type: "string" }, title: { type: "string" } } }
-});
-```
+One Synthesize agent writes the tracking-issue document from the final ticket set + critic guidance.
 
 ---
 
-#### Usage notes for commands that import this partial
+#### Usage notes
 
+- Each schema is its stage's return shape, passed as `schema:`: `{ agentType: "Design", schema: DRAFT_SCHEMA }`, `{ agentType: "Review", schema: REVIEW_SCHEMA }`, `{ agentType: "Synthesize", schema: REVISE_SCHEMA }`, `{ agentType: "Design", schema: CRITIC_SCHEMA }`. A field that the host script's `Return:` line adds joins the schema.
 - The `candidates` array is **what the model proposed + user confirmed** — never hardcoded.
 - The `initiative` variable is the raw user input (a description, a spec doc path, or inline text) — read it and distill before passing to agents.
 - The `constraints` variable is optional: any cross-cutting rules (naming discipline, scope filters, authority order) the user supplied.
-- Emit artifact files using the `ticket_body_template()` shape (from `_ticket_template.mds`) for each ticket — write inside agents, since the script body has no filesystem access.
-- Tracking-issue doc goes to `${ROOT}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.md`, `ROOT` being the workflow's `root` argument (agents do the writing).
+- Write each ticket's artifact file inside an agent, with the ticket body template above.
 - For large initiatives (more than ~8 tickets), chunk the `parallel(map())` fan-outs into batches (e.g. `for` loop over slices, `await`-ing each batch) so agent concurrency stays bounded and provider rate limits are respected.
 
 ---
 
-### Artifact paths
-
-Tickets → `{worktree}/.devflow/docs/tickets/{slug}/{ts}/{ticket-slug}.md`
-
-Tracking issue → `{worktree}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.md`
-
-`{worktree}` is the docs root resolved in Pre-authoring setup (it honours `WORKTREE_PATH` when provided).
-
-Timestamps follow the devflow `YYYY-MM-DD_HHMM` convention in local time (date and time separated by an underscore, e.g. `2026-06-12_1148`). The `ts` variable in the workflow script generates this format.
-
----
-
 ### Output schema
 
 The workflow returns:
@@ -626,9 +513,3 @@ The workflow returns:
 ```
 
 The tracking-issue path and any open questions are the primary handoff to `/devflow:dynamic-plan`. The filing step's report — each file's `**Issue:**` reference or `not filed` — follows the workflow's output.
-
----
-
-### Maintenance note
-
-This recipe encodes the ticket-factory shape as of the authoring date (2026-06-12). The pipeline structure (`draft → [2-lens review] → revise → whole-set critic → amend → tracking-issue`) is the load-bearing invariant. Per the LLM-vs-plumbing Iron Rule, no deterministic ticket-parsing logic is added — ticket slates are proposed by the model and confirmed by the user. When the devflow agent roster changes, update the `agentType` values above. No tooling detects drift — by design, under the same rule.

package/dist/curation-off/commands/explore.md

@@ -1,10 +1,8 @@
 ---
-description: Explore codebase with structured analysis and optional feature knowledge creation
+description: Explore codebase with structured analysis; optionally build feature knowledge
 ---
 # Explore Command
 
-Explore a codebase area by spawning parallel agents for flow tracing, dependency mapping, and pattern analysis. Findings are synthesized into structured output with file:line references, with optional feature knowledge created as a byproduct.
-
 ## Usage
 
 ```
@@ -21,26 +19,23 @@ What follows `/explore` is bound once, here. Every later step names it `COMMAND_
 $ARGUMENTS
 </command-input>
 
-`COMMAND_INPUT` is one of:
-- Area description: "how does the auth system work"
-- Flow question: "trace the request lifecycle"
-- Empty: use conversation context
+An empty `COMMAND_INPUT` means: use the conversation context.
 
 ## Phases
 
 ### Phase 1: Resolve Settings
 
-**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root in a one-worktree run:
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for:
 
 ```bash
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (including a script that cannot run) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
 
 The accepted line is the only source of these values.
 
-**No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias. Feature knowledge is only created as a write-back at the end, after exploration is complete.
+**No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias.
 
 ### Phase 2: Orient
 
@@ -102,31 +97,30 @@ Present findings to user. Use AskUserQuestion to offer focused follow-up explora
 
 ### Feature Knowledge Write-Back (Conditional)
 
-Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
+All paths below are relative to `{worktree}`.
 
-If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
+**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
 
-**Step 2 — Evaluate whether write-back is warranted:**
+If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The fail-closed line says `KNOWLEDGE=off` too.
 
-Only proceed if **at least one** of these is true:
+**Step 2 — Write back only if at least one is true:**
 - This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
-- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+- This workflow found durable, cross-cutting knowledge about a codebase area that future agents in that area need: patterns, anti-patterns, integration points, gotchas that a single file read does not show.
 
-**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+Otherwise skip write-back silently.
 
 **Step 3 — Spawn the Knowledge agent:**
 
-Spawn `Agent(subagent_type="Knowledge")` with the following context:
-
 ```
+Agent(subagent_type="Knowledge"):
 "WORKTREE_PATH: {worktree root}
 FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
@@ -146,9 +140,9 @@ Then commit the two files as your Commit Protocol directs."
 
 **Step 4 — Surface an uncommitted knowledge base:**
 
-When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files were written but deliberately not committed — a commit on a detached HEAD becomes unreachable once HEAD moves. Tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch before the worktree is removed. Never commit them yourself.
+When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch. Never commit them yourself.
 
-**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+Non-blocking: if the Knowledge agent fails, log the failure and continue.
 
 Set FEATURE_KNOWLEDGE_STATUS = created (if agent spawned) or skipped.
 
@@ -156,7 +150,7 @@ Set FEATURE_KNOWLEDGE_STATUS = created (if agent spawned) or skipped.
 
 ## Worktree Support
 
-If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+If the orchestrator receives a `WORKTREE_PATH` context, pass it through to all spawned agents.
 
 ## Output
 
@@ -169,38 +163,12 @@ Structured exploration findings with concrete code references:
 - Patterns (recurring conventions, design decisions observed)
 - Key Insights (non-obvious findings, surprises, potential concerns)
 
-## Architecture
-
-```
-/explore (orchestrator)
-│
-├─ Phase 1: Resolve Settings
-│
-├─ Phase 2: Orient
-│  └─ Skim agent (codebase overview)
-│
-├─ Phase 3: Parallel exploration
-│  └─ 2-3 Explore agents (flow, dependency, pattern) in single message
-│
-├─ Phase 4: Synthesize
-│  └─ Synthesize agent aggregates findings in exploration mode
-│
-├─ Phase 5: Present findings with drill-down offer
-│
-└─ Phase 6: Suggest feature knowledge creation (conditional)
-   └─ Knowledge agent write-back (if user accepts and no existing feature knowledge)
-```
-
 ## Principles
 
 1. **Structure over browsing** - Every claim must cite file:line references
-2. **Parallel execution** - All explorers run simultaneously for speed
-3. **Knowledge-informed** - NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
-4. **User-driven depth** - Present findings, then offer drill-down into specific areas
 
 ## Error Handling
 
 - If Skim agent returns no relevant files: report "No files found matching exploration scope"
 - If all explorers error: report partial findings from any that succeeded, note gaps
 - If an explorer errors: continue with remaining results, note the gap
-- If feature knowledge creation fails: log failure, report exploration results normally