devflow-kit 3.10.0 → 3.12.0

package/src/assets/commands/_partials/_factory.mds

@@ -1,27 +1,11 @@
 @define factory_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
 {
@@ -45,29 +29,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.
-
-```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
-    }),
-  ])
-));
-```
+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.
 
-REVIEW_SCHEMA (in fenced block — braces are raw):
+REVIEW_SCHEMA:
 
 ```json
 {
@@ -92,22 +56,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
 {
@@ -125,25 +74,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:
-
-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
-});
-```
+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.
 
-CRITIC_SCHEMA (in fenced block — braces are raw):
+CRITIC_SCHEMA:
 
 ```json
 {
@@ -168,48 +101,21 @@ 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.
 @end
 

package/src/assets/commands/_partials/_knowledge.mds

@@ -1,68 +1,54 @@
+@import { root_paths } from "./_docs_root.mds"
+
 A partial: the feature-knowledge load and write-back steps. D-SETTINGS-LINE: it
 imports nothing from `_settings.mds`. Write-back Step 1 takes `KNOWLEDGE` from the
 settings line the host's settings block resolved above, and keeps the
 `KNOWLEDGE=off` skip inside its own step.
 
 D-CMD-CONDENSE (#456): a cut here lands in every host, so each one names the line
-that keeps its text in the same context. Load's closing summary restated Steps 1-4,
-which each name their read, and Step 2's closing sentence restated Step 3's fallback
+that keeps its text in the same context. Load's closing summary restated Steps 1-3,
+which each name their read, and Step 1's closing sentence restated Step 2's fallback
 fields. The Knowledge spawn names what only the caller knows (root, slug, directories,
 files, the two paths, the index line format and its caps); how the agent writes the
 index, writes the two files directly and commits them is held by its own body
 (knowledge.mds steps 6-8, Direct Write Protocol, Commit Protocol), so the spawn no
 longer restates it.
 
-The checkout-root block lives once, in `knowledge_root()`. `knowledge_load()` carries it,
+The checkout-root block lives once, in `knowledge_root()`, which expands the shared
+`root_paths()` step of `_docs_root.mds` (one `resolve-root.cjs` call, run once per run) and
+adds the knowledge fact. `knowledge_load()` carries it,
 and so does `knowledge_writeback()`, which a host with no load step uses. A host that renders
 `knowledge_load()` earlier in the same command calls `knowledge_writeback_after_load()`, whose
 Step 1 and Step 3 take the `{worktree}` that the load step resolved.
 
-@define knowledge_root():
-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
-
-```bash
-git -C "{start}" rev-parse --show-toplevel
-```
-
-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}`.
-@end
-
-@define knowledge_load():
-### Load Feature Knowledge
-
-{{knowledge_root()}}
-
-**Step 1 — Read the index cache:**
-
-Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
-
-```
-- **{slug}** — {areas} — {Use-when description}
-```
-
-If `index.md` exists and contains at least one entry line, use it for relevance matching.
+A host that resolves `{worktree}` earlier with `docs_root()` can call `knowledge_load_after_root()`
+(implement does), which carries the load steps without a second root block. A host that calls it
+then calls `knowledge_writeback_after_load()` too, and the `{worktree}` that the docs-root step
+resolved serves the write-back.
 
-**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+The import is selective and takes `root_paths` alone: that define has no imports of its own, so
+it adds one node to the scope of each define here.
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
+@define knowledge_root():
+{{root_paths()}}
 
-**Step 3 — Pick relevant KBs:**
+All paths below are relative to `{worktree}`.
+@end
 
-Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+@define knowledge_load_steps():
+**Step 1 — Read the index cache** `{worktree}/.devflow/features/index.md`. Each line has the form `- **{slug}** — {areas} — {Use-when description}`. If `index.md` is absent or has no entry line, glob `{worktree}/.devflow/features/*/KNOWLEDGE.md` and read only the YAML frontmatter of each file, in one turn.
 
-**Step 4 — Read each selected KB's Rules:**
+**Step 2 — Pick relevant KBs:** select the entries whose documented area overlaps the current task (index line, or frontmatter `description` and `directories` on fallback).
 
-For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
+**Step 3 — Read each selected KB's Rules.** `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
-2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+1. List the `##` headings with line numbers of all selected KBs in one Bash call: `command grep -n '^## ' "{kb}" …`. With two or more paths, each line starts with its `{kb}:` path. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, all selected KBs in one turn, and choose the one to three bullets most relevant to the task.
 3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
 
-When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
-
-**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+When a KB contradicts the code you observe, **trust the code**.
 
-Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
+**Step 4 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES.** Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
 
 ```
 --- Feature knowledge: {slug} ---
@@ -73,31 +59,41 @@ Rules:
 Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 ```
 
-A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
+A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
+@end
+
+@define knowledge_load():
+### Load Feature Knowledge
+
+{{knowledge_root()}}
+
+{{knowledge_load_steps()}}
+@end
+
+@define knowledge_load_after_root():
+### Load Feature Knowledge
 
-**One git call, then direct reads — no `.cjs` script.**
+{{knowledge_load_steps()}}
 @end
 
 @export knowledge_load
+@export knowledge_load_after_root
 
 @define knowledge_writeback_steps():
 **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.
 
-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.
+If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The fail-closed line says `KNOWLEDGE=off` too.
 
-**Step 2 — Evaluate whether write-back is warranted:**
-
-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}
@@ -120,9 +116,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.
 @end
 
 @define knowledge_writeback():

package/src/assets/commands/_partials/_plan_contract.mds

@@ -10,7 +10,7 @@
 @define acceptance_criteria_contract():
 ### Acceptance criteria + test plan contract
 
-This is the shared shape produced by `/devflow:dynamic-plan`'s plan-challenge step (§5.1) and consumed by `/devflow:dynamic-build`'s Gate 2 (§7.2). Single source of truth — no drift between planning and build.
+This is the shared shape produced by `/devflow:dynamic-plan`'s plan-challenge step (§5.1) and consumed by `/devflow:dynamic-build`'s Gate 2 (§7.2).
 
 #### What the plan-challenge step MUST produce (per ticket)
 
@@ -38,7 +38,7 @@ The test plan IS TP lines: at least one per acceptance criterion, numbered from
 
 A scenario's setup and expected outcome are not part of its line. They go under a `## Test Scenarios` section after `## Test Plan`, one `TP-<n>:` entry per TP. `## Test Plan` holds TP lines only, so `check tp` can parse it.
 
-The test plan must be executable by the Test agent without further clarification — it is a complete specification, not notes.
+The test plan must be executable by the Test agent without further clarification.
 
 Every line of a `## Test Plan` section, or of a PR's test-plan block, follows this contract:
 

package/src/assets/commands/_partials/_preamble.mds

@@ -1,11 +1,11 @@
 @import "./_decisions.mds" as decisions
 
-A partial: the Workflow-authoring preamble the dynamic commands share, and the
-decisions step that precedes authoring.
+A partial: the Workflow-authoring preamble that the three Workflow hosts
+(dynamic-build, dynamic-plan and dynamic-tickets) share, and the decisions step
+that precedes authoring.
 
 D-DECISIONS-AUTHORING-STEP: the "DECISIONS_CONTEXT — obtain BEFORE authoring" step
-is its own define, `authoring_decisions()`, expanded by the hosts that load
-decisions (dynamic-build, dynamic-plan, dynamic-tickets and dynamic-profile) right
+is its own define, `authoring_decisions()`, expanded by the same three hosts right
 after their settings block, so the gate in it reads a line already resolved.
 `authoring_preamble()` carries no decisions text. D-LEARNING-VARIANTS: the whole of
 `authoring_decisions()` is a curation-on arm, so a curation-off build carries no decisions
@@ -19,11 +19,11 @@ from the agent sources and holds every pass sentence to it.
 @define authoring_preamble():
 ## 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 = {
@@ -33,7 +33,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
@@ -46,7 +46,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
 
@@ -56,39 +56,39 @@ 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.
 @end
 
 @define authoring_decisions():
@@ -101,7 +101,7 @@ When a ticket requires multiple sequential Code agent phases, each Code agent ap
 
 Before you author the workflow script, read `{ledger}/.devflow/curation/index.md`. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
 
-The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into the prompts of the Code, Fix, Design, Knowledge, Review and Harden agents, which follow `devflow:apply-decisions`. Those are the agent types above whose contract declares it; every other agent type gets no decisions context.
+Then inject the relevant DECISIONS_CONTEXT into the prompts of the Code, Fix, Design, Architect, Review and Harden agents, which follow `devflow:apply-decisions`. Those are the agent types above whose contract declares it; every other agent type gets no decisions context.
 
 {{decisions.decisions_slice()}} The script carries one `DECISIONS_CONTEXT` for every agent, so cut it once, over the whole run.
 

package/src/assets/commands/_partials/_publication.mds

@@ -8,15 +8,15 @@ note that names the Git agent's publication gate; a host with compliance off cal
 because the gate's reference file is not installed there.
 
 @define publication_resolve():
-**Resolve `REVIEW_PUBLICATION` per worktree:** take `REVIEW_PUBLICATION` from that worktree's settings line — the line resolved above for `{root}`, the worktree's root, by the settings block when this run has not yet resolved that root; multi-worktree repos may resolve different values per worktree. The line already caps the personal choice at the team's (D-PUBLICATION-CEILING), so it is `off`, `auto` or `full`, and `off` when the line was unresolvable.
+**Resolve `REVIEW_PUBLICATION` per worktree:** take `REVIEW_PUBLICATION` from that worktree's settings line — the line resolved above for `{root}`, the worktree's root, by the settings block when this run has not yet resolved that root. The line already caps the personal choice at the team's, so it is `off`, `auto` or `full`, and `off` when the line was unresolvable.
 
-**Evidence stub:** only when `EVIDENCE_POLICY` is `required`, a resolved `off` becomes `stub`, so a counts-only record still reaches the PR. `stub` is never a config value: the settings line never carries it.
+**Evidence stub:** only when `EVIDENCE_POLICY` is `required`, a resolved `off` becomes `stub`, so a counts-only record still reaches the PR. `stub` is never a config value.
 @end
 
 @define publication_gate():
 {{publication_resolve()}}
 
-Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB). What each value does is decided by the Git agent's publication gate (`references/publication-gate.md` step 2); this partial only resolves the value.
+Note: `auto` does not fail open: the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB). What each value does is decided by the Git agent's publication gate (`references/publication-gate.md` step 2); this partial only resolves the value.
 @end
 
 @export publication_resolve

package/src/assets/commands/_partials/_roster.mds

@@ -1,31 +1,30 @@
 @define agent_roster():
 ### 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 |
 @end
 
 @define agent_caveats():
 ### 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.
 @end
 
 @export agent_roster

package/src/assets/commands/_partials/_settings.mds

@@ -19,16 +19,19 @@ not runtime calls.
 
 The accepted shape below is `SETTINGS_LINE_RE` written out, and the fallback is
 `SETTINGS_FAIL_CLOSED_LINE`, both exported by `resolve-settings.cjs`;
-`tests/commands/settings-partial.test.ts` pins both to the script.
+`tests/commands/settings-partial.test.ts` pins both to the script. On every error
+path the script prints that same fallback line itself, with a non-zero exit. The
+literal in the block applies when the script output fails the check or the script
+cannot run at all.
 
 @define settings_resolve():
-**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.
 @end

package/src/assets/commands/_partials/_ticket_template.mds

@@ -1,8 +1,6 @@
 @define ticket_body_template():
 ### 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
@@ -26,7 +24,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
 
@@ -37,7 +35,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...
@@ -50,11 +48,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.
 @end
 
 @export ticket_body_template