devflow-kit 2.5.0 → 3.0.0

package/src/assets/commands/dynamic-build.mds

@@ -5,14 +5,15 @@ output-dir: dist/commands
 ---
 @import { authoring_preamble } from "./_partials/_preamble.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
+@import { docs_root } from "./_partials/_docs_root.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
 @import { gate1_postcode, gate2_acceptance, evaluator_panel, implement_bundle, review_pass, concurrency_doctrine, build_execution_doctrine, engine_output_schema, engine_invariants } from "./_partials/_engine.mds"
 @import { wave_loop, branch_merge_model, merge_doctrine, escalation_model } from "./_partials/_wave.mds"
 @import { acceptance_criteria_contract } from "./_partials/_plan_contract.mds"
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
 @import "./_partials/_publication.mds" as pub
-
-{authoring_preamble()}
+@import "./_partials/_compliance.mds" as compliance
+{{authoring_preamble()}}
 
 ---
 
@@ -20,14 +21,14 @@ output-dir: dist/commands
 
 This command instructs you to construct and run a Claude Code dynamic Workflow that implements, reviews, and verifies one ticket or a full wave of tickets, reusing devflow's existing agents via `agentType`.
 
-{agent_roster()}
+{{agent_roster()}}
 
-{agent_caveats()}
+{{agent_caveats()}}
 
 ---
 
 **Requires:** ticket or task description; optional plan document and acceptance criteria from `/devflow:dynamic-plan`
-**Produces:** implemented and reviewed branch per ticket; wave run report at `.devflow/docs/waves/\{slug\}/\{ts\}/wave-report.md`
+**Produces:** implemented and reviewed branch per ticket; wave run report at `{integration worktree root}/.devflow/docs/waves/{slug}/{ts}/wave-report.md`
 
 ---
 
@@ -37,7 +38,7 @@ 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-build 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).
-3. **Tracker paths:** an issue reference or URL in the input is read through the Git agent, which resolves the configured tracker and its access itself and reports `TRACEABILITY: DEGRADED (\{reason\})` when it cannot read one — then note it and fall back to the issue text the user provided. No tracker CLI is checked here.
+3. **Tracker paths:** an issue reference or URL in the input is read through the Git agent, which resolves the configured tracker and its access itself and reports `TRACEABILITY: DEGRADED ({reason})` when it cannot read one — then note it and fall back to the issue text the user provided. No tracker CLI is checked here.
 4. **No-remote path:** if the repo has no remote, skip the remote-dependent steps (the wave PR and its evidence) and proceed with local branch operations only; the Git agent reports DEGRADED for any tracker step it cannot reach.
 
 ---
@@ -50,10 +51,24 @@ Before you write the workflow script:
 
 **Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
 
-{evidence_policy()}
+{{evidence_policy()}}
 
 Author the resolved `ISSUE_REQUIRED` and `APPLY_CONVENTIONS` into the workflow script as constants — pass them as `issueRequired` and `applyConventions` when invoking the workflow — and pass both to the Git `setup-task` spawn.
 
+**0b. Resolve the compliance lens**
+
+**Produces:** COMPLIANCE_FRAMEWORKS
+
+{{compliance.compliance_lens()}}
+
+Pass it as `complianceFrameworks` when invoking the workflow; the engine hands it to every Code agent.
+
+**0c. Resolve the docs root**
+
+{{docs_root()}}
+
+`{integration worktree root}` is the toplevel of the checkout the integration branch is checked out in: `{worktree}` unless the wave runs in a linked worktree.
+
 **1. Apply decisions context**
 
 Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded per the preamble above: scan the index, Read relevant entries, note the verbatim ADR/PF IDs you will inject into Code agent and Evaluate agent prompts.
@@ -66,7 +81,7 @@ Note the `budget` value from the Workflow tool context (or default to "medium" i
 
 - **SINGLE mode:** input is one ticket, one issue, one task description, or one plan document
 - **WAVE mode:** input is a set of tracker issues (wave labels, milestone, issue list), or the user says "wave" / "all tickets in wave N"
-- **A `/devflow:dynamic-tickets` ticket directory** (`.devflow/docs/tickets/\{slug\}/\{ts\}/`) is WAVE input: in each ticket file (every `.md` there but `tracking-issue.md`), the `**Issue:**` line directly after `**Depends on:**` is one raw `ISSUE_REFS` token, forwarded to the wave's pre-fetch verbatim — never rendered, normalised or re-derived. A ticket file with no `**Issue:**` line, or more than one, contributes no token; name it in the run summary as `not filed`.
+- **A `/devflow:dynamic-tickets` ticket directory** (`{worktree}/.devflow/docs/tickets/{slug}/{ts}/`) is WAVE input: in each ticket file (every `.md` there but `tracking-issue.md`), the `**Issue:**` line directly after `**Depends on:**` is one raw `ISSUE_REFS` token, forwarded to the wave's pre-fetch verbatim — never rendered, normalised or re-derived. A ticket file with no `**Issue:**` line, or more than one, contributes no token; name it in the run summary as `not filed`.
 
 When ambiguous, ask the user before authoring: "Is this a single ticket or a wave of tickets?"
 
@@ -78,7 +93,7 @@ Check for (in priority order):
 - The current working context (recent `/devflow:dynamic-plan` output)
 - An in-context task description
 
-{issue_capture_contract()}
+{{issue_capture_contract()}}
 
 Extract or note:
 - Implementation plan (for Code agent prompt and Evaluate agent)
@@ -86,7 +101,7 @@ Extract or note:
 - The test plan (for Gate 2) — a plan's TP lines, passed only once they pass this check. Copy the plan's `## Test Plan` section byte for byte into a fresh `mktemp` file with the Write tool, never through an interpolated shell string, and run:
 
 ```bash
-node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" check tp <that file>; echo "exit=$?"
+node "$HOME/.devflow/scripts/verify-evidence.cjs" check tp <that file>; echo "exit=$?"
 ```
 
   Only `exit=0` passes it: pass the section's TP lines, as one string, as `testPlan` when invoking the workflow — a test plan alone still runs the Test agent. Any other result, or a plan with no `## Test Plan` section: omit `testPlan` and note `Test plan: missing or malformed` in the run summary. Nothing is repaired, and a test plan in any other shape — an older JSON one included — is never passed.
@@ -99,10 +114,10 @@ If none found: build proceeds Gate-1-only (Gate 2 skipped with a note). Never re
 
 Check, in priority order:
 - An explicit candidate issue reference or issue URL in the user's input (e.g. `#42`, `42`, or `https://github.com/…/issues/42`)
-- The `**Issue:**` line directly after the H1 of the ticket set's `tracking-issue.md` (written by `/devflow:dynamic-tickets`' filing step; the file is at `.devflow/docs/tickets/\{slug\}/\{ts\}/tracking-issue.md`), as a raw token — only when the file holds exactly one `**Issue:**` line
+- The `**Issue:**` line directly after the H1 of the ticket set's `tracking-issue.md` (written by `/devflow:dynamic-tickets`' filing step; the file is at `{worktree}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.md`), as a raw token — only when the file holds exactly one `**Issue:**` line
 - Otherwise: none
 
-{issue_ref_grammar()}
+{{issue_ref_grammar()}}
 
 If a number is found, record it as the command-level `ISSUE_NUMBER`:
 - **SINGLE mode:** it is the ticket's own reference. Pass it as `issueNumber: <number>` when invoking the workflow; the engine hands it to setup-task as `ISSUE_INPUT`. If none is found, pass nothing.
@@ -133,6 +148,7 @@ const DECISIONS_CONTEXT = args.decisionsContext || "";  // injected before autho
 const ISSUE_INPUT = args.issueInput || args.issueNumber || "(none)";  // this ticket's OWN raw reference (Pre-authoring step 5; a wave passes issueInput) — setup-task's input, never a Code agent's
 const ISSUE_REQUIRED = String(args.issueRequired) === "false" ? "false" : "true";  // Pre-authoring step 0; only an explicit false turns it off — absent or unrecognised fails closed, like the resolver
 const APPLY_CONVENTIONS = String(args.applyConventions) === "false" ? "false" : "true";
+const COMPLIANCE_FRAMEWORKS = /^(?:off|none|[a-z][a-z0-9-]{0,15}(?:,[a-z][a-z0-9-]{0,15}){0,7})$/.test(String(args.complianceFrameworks)) ? String(args.complianceFrameworks) : "off";  // Pre-authoring step 0b; any other shape is no lens
 
 // Phase 1: Git setup — declare the operation; the agent owns the process, the branch name included
 const setup = await phase("setup", () =>
@@ -176,6 +192,7 @@ ${DECISIONS_CONTEXT}
 
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
+COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 
 When you build or run tests to verify your work, use your "Long-running commands" discipline (background-Bash + Monitor poll) for anything that may run silent >120s, and prefer package-scoped commands.
 
@@ -199,6 +216,7 @@ Report: PASS or FAIL with details.`, { agentType: "Validate" });
 ${validation.details}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
+COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 Commit fixes with conventional-commit message.`, { agentType: "Code" });
       const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH}. Report: PASS or FAIL.`, { agentType: "Validate" });
       if (recheck.verdict === "PASS") break;
@@ -242,6 +260,7 @@ Report: PASS or FAIL with rationale.`, { agentType: "Evaluate" }),
 ${panel.filter(p => p.verdict === "FAIL").map(p => p.rationale).join("\n")}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
+COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 Self-verify your fix compiles (background-Bash + Monitor for any build >120s — see your "Long-running commands" discipline). Commit fixes.`, { agentType: "Code" });
       evalVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
@@ -261,6 +280,7 @@ Cover: functionality, API contracts, performance, and cover every TEST_PLAN scen
 ${testResult.failures}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
+COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 Self-verify your fix compiles and the scenarios pass (background-Bash + Monitor for any build/test >120s). Commit fixes.`, { agentType: "Code" });
       testVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
@@ -374,6 +394,7 @@ ${chunk.map(f => `- ${f.description} (${f.severity})`).join("\n")}
 
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
+COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 Fix all findings in this batch. Self-verify your fix compiles (background-Bash + Monitor for any build >120s — see your "Long-running commands" discipline). Commit with conventional-commit message.
 Return: {"status": "fixed"|"blocked", "commitShas": ["<sha>"], "unresolved": ["<description of any finding that could not be fixed>"]}`, { agentType: "Code" });
       chunkResults.push({ chunk, result: r });
@@ -424,6 +445,7 @@ Report: PASS or FAIL with details.`, { agentType: "Validate" });
 ${failureDetails}
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
+COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
 Self-verify your fix compiles. Commit fixes with conventional-commit message.`, { agentType: "Code" });
       const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (background+Monitor for long commands). Report: PASS or FAIL.`, { agentType: "Validate" });
       if (recheck.verdict === "PASS") break;
@@ -476,25 +498,25 @@ Write a concise report. Present only surviving findings as outstanding — never
 });
 ```
 
-{concurrency_doctrine()}
+{{concurrency_doctrine()}}
 
-{build_execution_doctrine()}
+{{build_execution_doctrine()}}
 
-{implement_bundle()}
+{{implement_bundle()}}
 
-{gate1_postcode()}
+{{gate1_postcode()}}
 
-{gate2_acceptance()}
+{{gate2_acceptance()}}
 
-{evaluator_panel()}
+{{evaluator_panel()}}
 
-{acceptance_criteria_contract()}
+{{acceptance_criteria_contract()}}
 
-{review_pass()}
+{{review_pass()}}
 
-{engine_invariants()}
+{{engine_invariants()}}
 
-{engine_output_schema()}
+{{engine_output_schema()}}
 
 ---
 
@@ -502,17 +524,17 @@ Write a concise report. Present only surviving findings as outstanding — never
 
 When WAVE mode is detected, author a workflow that wraps the single-ticket engine with the wave loop:
 
-{wave_loop()}
+{{wave_loop()}}
 
-{branch_merge_model()}
+{{branch_merge_model()}}
 
-{merge_doctrine()}
+{{merge_doctrine()}}
 
-{escalation_model()}
+{{escalation_model()}}
 
 **Wave workflow structure (author after the SINGLE engine blocks above):**
 
-The wave workflow uses the same phases as SINGLE but wraps them in a wave loop. The integration branch is `wave/<initiative>` — the initiative slug, referenced below as `\{slug\}` — (or the user's current branch). Each ticket works on the branch setup-task created. The Git agent manages worktrees for parallel-eligible tickets. After every merge: Validate agent (build + test). Escalations accumulate in a list; the final report lists all of them.
+The wave workflow uses the same phases as SINGLE but wraps them in a wave loop. The integration branch is `wave/<initiative>` — the initiative slug, referenced below as `{slug}` — (or the user's current branch). Each ticket works on the branch setup-task created. The Git agent manages worktrees for parallel-eligible tickets. After every merge: Validate agent (build + test). Escalations accumulate in a list; the final report lists all of them.
 
 Wave skeleton — compact reference (see `wave_loop()` doctrine for full semantics):
 
@@ -556,7 +578,7 @@ Return: {"ready": [...ticket-ids], "blocked": [{"ticket": "id", "namedBlocker":
     try {
       // ticketId is the ISSUE_REF the pre-fetch heading printed — this ticket's OWN reference: the engine's `ticket` (its TICKET)
       // and its setup-task ISSUE_INPUT; the engine returns the branch that setup-task created, merged below; plans[ticketId] is its own plan, criteria and checked testPlan (Pre-authoring step 4)
-      const engineResult = await runSingleTicketEngine({ ticket: ticketId, baseBranch: INTEGRATION_BRANCH, ...(plans[ticketId] || {}), decisionsContext: DECISIONS_CONTEXT, issueRequired: ISSUE_REQUIRED, applyConventions: APPLY_CONVENTIONS, issueInput: ticketId });
+      const engineResult = await runSingleTicketEngine({ ticket: ticketId, baseBranch: INTEGRATION_BRANCH, ...(plans[ticketId] || {}), decisionsContext: DECISIONS_CONTEXT, issueRequired: ISSUE_REQUIRED, applyConventions: APPLY_CONVENTIONS, complianceFrameworks: COMPLIANCE_FRAMEWORKS, issueInput: ticketId });
       // Check both verdict (engine_output_schema) and overallVerdict (SINGLE skeleton alias).
       // PASS and UNVERIFIED merge; PARTIAL, FAIL, ESCALATED (the ticket-link and branch stops included) or no verdict quarantine.
       if (["PASS", "UNVERIFIED"].includes(engineResult.verdict || engineResult.overallVerdict)) {
@@ -587,21 +609,21 @@ return { tickets: WAVE_TICKETS.map(t => results[t] || { ticket: t, ran: false, v
 
 A workflow cannot pause mid-run. After the build/wave workflow returns, you (the main model) surface anything that needs a human decision — all at once:
 
-1. Read the wave report (`.devflow/docs/waves/\{slug\}/\{ts\}/wave-report.md`) for its **escalations** (quarantined/blocked tickets and why), and read any `DECISIONS-NEEDED.md` left by a prior `/devflow:dynamic-plan` run for this initiative.
-2. **Post wave-report as tracking-issue comment** (WAVE mode only — skip this step entirely in SINGLE mode; SINGLE runs produce no wave report): In WAVE mode, if a tracking-issue number was resolved in Pre-authoring step 5 (`ISSUE_NUMBER` is not `(none)`) AND `.devflow/docs/waves/\{slug\}/\{ts\}/wave-report.md` exists, define `WAVE_ID` as the timestamped wave directory slug (the `\{ts\}` component, e.g. `2026-08-20_1730`), then spawn:
+1. Read the wave report (`{integration worktree root}/.devflow/docs/waves/{slug}/{ts}/wave-report.md`) for its **escalations** (quarantined/blocked tickets and why), and read any `DECISIONS-NEEDED.md` left by a prior `/devflow:dynamic-plan` run for this initiative.
+2. **Post wave-report as tracking-issue comment** (WAVE mode only — skip this step entirely in SINGLE mode; SINGLE runs produce no wave report): In WAVE mode, if a tracking-issue number was resolved in Pre-authoring step 5 (`ISSUE_NUMBER` is not `(none)`) AND `{integration worktree root}/.devflow/docs/waves/{slug}/{ts}/wave-report.md` exists, define `WAVE_ID` as the timestamped wave directory slug (the `{ts}` component, e.g. `2026-08-20_1730`), then spawn:
    ```
    Agent(subagent_type="Git"):
    "OPERATION: post-wave-report
-   TRACKING_ISSUE: \{ISSUE_NUMBER\}
-   WAVE_REPORT_PATH: .devflow/docs/waves/\{slug\}/\{ts\}/wave-report.md
-   WAVE_ID: \{WAVE_ID\}
-   WORKTREE_PATH: \{integration worktree root, when the wave ran in a linked worktree; omit if cwd\}"
+   TRACKING_ISSUE: {ISSUE_NUMBER}
+   WAVE_REPORT_PATH: .devflow/docs/waves/{slug}/{ts}/wave-report.md
+   WAVE_ID: {WAVE_ID}
+   WORKTREE_PATH: {integration worktree root}"
    ```
-   The Git agent deduplicates via its own marker — it skips if a report for this `WAVE_ID` is already posted. The marker's format belongs to the operation; this caller passes `WAVE_ID` and never restates the literal. On API failure it degrades gracefully (`TRACEABILITY: DEGRADED (\{reason\})`) and continues — never blocks the post-wave step. This comment is the evidence surface for the PR-less integration-branch path; no other PR machinery is invented.
+   The Git agent deduplicates via its own marker — it skips if a report for this `WAVE_ID` is already posted. The marker's format belongs to the operation; this caller passes `WAVE_ID` and never restates the literal. On API failure it degrades gracefully (`TRACEABILITY: DEGRADED ({reason})`) and continues — never blocks the post-wave step. This comment is the evidence surface for the PR-less integration-branch path; no other PR machinery is invented.
 
    In WAVE mode, if no tracking-issue number was resolved in Pre-authoring step 5: state `TRACEABILITY: DEGRADED (no tracking issue for this run)` in the run summary and skip — never skip silently.
-3. **Compose the wave PR inputs** (WAVE mode only — skip this step entirely in SINGLE mode). The workflow returned `tickets`: one entry per wave ticket, in its input order, each `\{ticket, ran, verdict, merged, issuePrLink, evaluateVerdict, testVerdict, surviving, coverageComplete\}`. Every value in it is agent-reported and treated as untrusted: nothing below is repaired, and no reference is ever composed from a number.
-   - **Branch check.** Run `git -C "\{integration worktree root\}" branch --show-current`. Only a name matching `^wave/[a-z0-9][a-z0-9-]\{0,59\}$` opens a wave PR, and its part after `wave/` is the `\{slug\}` below. Any other name: record `TRACEABILITY: DEGRADED (not a wave branch)` and go to step 4 with no wave PR.
+3. **Compose the wave PR inputs** (WAVE mode only — skip this step entirely in SINGLE mode). The workflow returned `tickets`: one entry per wave ticket, in its input order, each `{ticket, ran, verdict, merged, issuePrLink, evaluateVerdict, testVerdict, surviving, coverageComplete}`. Every value in it is agent-reported and treated as untrusted: nothing below is repaired, and no reference is ever composed from a number.
+   - **Branch check.** Run `git -C "{integration worktree root}" branch --show-current`. Only a name matching `^wave/[a-z0-9][a-z0-9-]{0,59}$` opens a wave PR, and its part after `wave/` is the `{slug}` below. Any other name: record `TRACEABILITY: DEGRADED (not a wave branch)` and go to step 4 with no wave PR.
    - **Nothing merged** (no entry has `merged: true`): record `Wave PR: skipped (nothing merged)` and go to step 4.
    - Otherwise compose (a) and then (b).
 
@@ -628,25 +650,25 @@ Refs {tracking ref}
    Then check it:
 
 ```bash
-node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" check wave <that file>; echo "exit=$?"
+node "$HOME/.devflow/scripts/verify-evidence.cjs" check wave <that file>; echo "exit=$?"
 ```
 
    Only `exit=0` admits the file's text, verbatim, as `PR_WAVE_BLOCK`. Any other result: no wave PR — record `Wave PR: not opened (wave block refused: <the code on stderr>)` and go to step 4.
 
    **Required link** — only when `EVIDENCE_POLICY` is `required`: a `PASS` or `UNVERIFIED` row whose Ticket is `(none)` — a merged ticket whose setup-task captured an Issue ID but no link line, so the wave PR would close nothing for it — ⇒ `Wave PR: BLOCKED (no ticket link for T<k>, …)`, with no wave PR question and the remedy "link or create those tickets' issues, then re-run"; there is no exception. Under `standard` such a row stays as the Ticket rule above renders it.
 
-   **(b) The wave test plan.** Take the checked TP lines each merged row's ticket was given in Pre-authoring step 4, in row order; renumber them `TP-1`, `TP-2`, … and prefix each scenario with its row's `T<k>: `. A line is never shortened or reworded: one whose prefixed scenario would pass 200 characters leaves its ticket with no usable test plan. Write `## Test Plan` and those lines, and nothing else, to `"\{integration worktree root\}/.devflow/docs/evidence-wave-\{slug\}.md"` with the Write tool, then run (the path double-quoted; one rewrite from the same lines after a refusal, never a second):
+   **(b) The wave test plan.** Take the checked TP lines each merged row's ticket was given in Pre-authoring step 4, in row order; renumber them `TP-1`, `TP-2`, … and prefix each scenario with its row's `T<k>: `. A line is never shortened or reworded: one whose prefixed scenario would pass 200 characters leaves its ticket with no usable test plan. Write `## Test Plan` and those lines, and nothing else, to `"{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"` with the Write tool, then run (the path double-quoted; one rewrite from the same lines after a refusal, never a second):
 
 ```bash
-node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" check tp "{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"; echo "exit=$?"
-node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" render --plan "{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"; echo "exit=$?"
+node "$HOME/.devflow/scripts/verify-evidence.cjs" check tp "{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"; echo "exit=$?"
+node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"; echo "exit=$?"
 ```
 
    Only when both exit 0 is `PR_TEST_PLAN_BLOCK` the render's stdout, byte for byte without its `exit=` line; in every other case it is `(none)`.
 
    **Required plan** — only when `EVIDENCE_POLICY` is `required`: a merged ticket with no usable test plan ⇒ `Wave PR: BLOCKED (no test plan for T<k>, …)`, more than 200 lines in all ⇒ `Wave PR: BLOCKED (test plan over 200 lines)`, and a plan that did not check and render ⇒ `Wave PR: BLOCKED (test plan malformed)` — each with no wave PR question and the remedy "run `/devflow:dynamic-plan` for those tickets and re-run, or ship them through `/implement`"; no exception is offered here. Otherwise the block is optional: a ticket with no usable test plan is left out of it and named in the summary, and `(none)` is passed when no line remains.
 4. Surface ALL of them — escalations AND open decisions — to the user in ONE batched `AskUserQuestion` (never one-at-a-time). `_wave.mds`'s escalation model already quarantines-and-continues; this batches the surfacing so the user answers everything in a single pass.
-   - **The wave PR question.** Only when step 3 composed `PR_WAVE_BLOCK`, the batch gains exactly one question: "Open the wave PR from wave/\{slug\}? It links \{n\} merged tickets (\{u\} UNVERIFIED) and references \{q\} quarantined." It has exactly two options: open it, or don't. The counts come from the checked block's rows: `\{n\}` PASS and UNVERIFIED, `\{u\}` UNVERIFIED, `\{q\}` QUARANTINED.
+   - **The wave PR question.** Only when step 3 composed `PR_WAVE_BLOCK`, the batch gains exactly one question: "Open the wave PR from wave/{slug}? It links {n} merged tickets ({u} UNVERIFIED) and references {q} quarantined." It has exactly two options: open it, or don't. The counts come from the checked block's rows: `{n}` PASS and UNVERIFIED, `{u}` UNVERIFIED, `{q}` QUARANTINED.
    - A `ticket-link-missing` escalation carries its remedy: link or create that ticket's issue, then re-run. There is no per-ticket exception.
    - **Headless** — `AskUserQuestion` is unavailable, or no answer comes — is a decline: nothing is created and nothing is pushed.
 5. If `~/.devflow/preference-profile.md` was absent, note in your summary: "no preference profile found — N decisions surfaced that a profile might have auto-resolved; consider `/devflow:dynamic-profile`."
@@ -654,19 +676,19 @@ node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" render --plan
    ```
    Agent(subagent_type="Git"):
    "OPERATION: ensure-pr-ready
-   WORKTREE_PATH: \{integration worktree root\}
-   PR_DESCRIPTION_GUIDANCE: \{counts only — the wave slug and the merged, quarantined and blocked counts; never an issue title or body\}
-   APPLY_CONVENTIONS: \{APPLY_CONVENTIONS\}
-   PR_WAVE_BLOCK: \{PR_WAVE_BLOCK verbatim\}
-   PR_TEST_PLAN_BLOCK: \{PR_TEST_PLAN_BLOCK verbatim, or (none)\}"
+   WORKTREE_PATH: {integration worktree root}
+   PR_DESCRIPTION_GUIDANCE: {counts only — the wave slug and the merged, quarantined and blocked counts; never an issue title or body}
+   APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
+   PR_WAVE_BLOCK: {PR_WAVE_BLOCK verbatim}
+   PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}"
    ```
-   The Git agent pastes each block only behind its own check. Report its `**PR**` line and any `TRACEABILITY: DEGRADED (\{reason\})` lines. The wave PR is opened here and nowhere else; it is never merged, and main is never touched — the user merges.
+   The Git agent pastes each block only behind its own check. Report its `**PR**` line and any `TRACEABILITY: DEGRADED ({reason})` lines. The wave PR is opened here and nowhere else; it is never merged, and main is never touched — the user merges.
 
 Do NOT ask questions mid-workflow — that is impossible (F4). The workflow only WRITES the report; you read it and ask.
 
-7. **Wave PR evidence** — only when step 6 reported the wave PR, after it; it never blocks, and every outcome below goes into the run summary. Take `\{n\}` from step 6's `- **PR**: #\{n\}` line when `\{n\}` matches `^[1-9][0-9]\{0,9\}$` as a whole; no such line ⇒ record `TRACEABILITY: DEGRADED (wave PR number not captured)` and skip this step. `PR_TEST_PLAN_BLOCK` `(none)` ⇒ record `Wave evidence: skipped (no wave test plan)` and skip it.
+7. **Wave PR evidence** — only when step 6 reported the wave PR, after it; it never blocks, and every outcome below goes into the run summary. Take `{n}` from step 6's `- **PR**: #{n}` line when `{n}` matches `^[1-9][0-9]{0,9}$` as a whole; no such line ⇒ record `TRACEABILITY: DEGRADED (wave PR number not captured)` and skip this step. `PR_TEST_PLAN_BLOCK` `(none)` ⇒ record `Wave evidence: skipped (no wave test plan)` and skip it.
 
-   **(a) Test the wave.** Spawn one Test agent on the integration worktree with the wave test plan — the TP lines of the `## Test Plan` section step 3(b) wrote to `.devflow/docs/evidence-wave-\{slug\}.md`:
+   **(a) Test the wave.** Spawn one Test agent on the integration worktree with the wave test plan — the TP lines of the `## Test Plan` section step 3(b) wrote to `{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md`:
 
 ```
 Agent(subagent_type="Test"):
@@ -679,7 +701,7 @@ Cover every TEST_PLAN line on the integration branch as it stands. Report PASS o
 
    Nothing is fixed here, PASS or FAIL: the wave is done and its PR is open. Report the Test agent's Status.
 
-   **(b) Claims.** Append its TP claims, PASS or FAIL alike, to the `## Claims` section of `"\{integration worktree root\}/.devflow/docs/evidence-wave-\{slug\}.md"` — the file's last section, created when absent. Append only: never edit or remove a claim. Each line is `/implement`'s TP claim, keyed to the 40-hex `HEAD:` the Test agent's report shows:
+   **(b) Claims.** Append its TP claims, PASS or FAIL alike, to the `## Claims` section of `"{integration worktree root}/.devflow/docs/evidence-wave-{slug}.md"` — the file's last section, created when absent. Append only: never edit or remove a claim. Each line is `/implement`'s TP claim, keyed to the 40-hex `HEAD:` the Test agent's report shows:
 
 ```
 - TP-<n> <PASS|FAIL|SKIP> sha:<head> by:test exit:<0-255>
@@ -697,7 +719,7 @@ git -C "{integration worktree root}" push origin HEAD; echo "exit=$?"
 
    **(d) Refresh.** Resolve the publication value for the integration worktree:
 
-{pub.publication_gate()}
+{{pub.publication_gate()}}
 
    Then spawn:
 
@@ -711,7 +733,7 @@ WORKTREE_PATH: {integration worktree root}
 Update the wave PR's test-plan block and post its evidence comment."
 ```
 
-   `update-pr-evidence` decides what each publication value means for the evidence comment. Report its `## PR Evidence` block — its `EVIDENCE` line and its `**Body**:` / `**Comment**:` line — or its `TRACEABILITY: DEGRADED (\{reason\})` line; a spawn that returns neither ⇒ `TRACEABILITY: DEGRADED (evidence refresh failed)`. Whatever it returns, the run ends here.
+   `update-pr-evidence` decides what each publication value means for the evidence comment. Report its `## PR Evidence` block — its `EVIDENCE` line and its `**Body**:` / `**Comment**:` line — or its `TRACEABILITY: DEGRADED ({reason})` line; a spawn that returns neither ⇒ `TRACEABILITY: DEGRADED (evidence refresh failed)`. Whatever it returns, the run ends here.
 
 ---
 

package/src/assets/commands/dynamic-plan.mds

@@ -4,11 +4,11 @@ argument-hint: "[tickets-dir | issue-list]"
 output-dir: dist/commands
 ---
 @import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { docs_root } from "./_partials/_docs_root.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
 @import { acceptance_criteria_contract } from "./_partials/_plan_contract.mds"
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
-
-{authoring_preamble()}
+{{authoring_preamble()}}
 
 ---
 
@@ -16,14 +16,14 @@ output-dir: dist/commands
 
 This command instructs you to construct and run a Claude Code dynamic Workflow that plans all tickets in parallel, challenges each plan (gaps, edge cases, side-effects), produces well-structured acceptance criteria and a test plan for each ticket (consumed by `/devflow:dynamic-build`'s Gate 2), runs a cross-plan conflict critic, auto-resolves decisions matching the user's preference profile, and writes per-ticket plan files + one `DECISIONS-NEEDED.md`.
 
-{agent_roster()}
+{{agent_roster()}}
 
-{agent_caveats()}
+{{agent_caveats()}}
 
 ---
 
 **Requires:** ticket files directory or tracker issue list; optional `~/.devflow/preference-profile.md`
-**Produces:** per-ticket plan files + `DECISIONS-NEEDED.md` at `.devflow/docs/design/\{slug\}/\{ts\}/`
+**Produces:** per-ticket plan files + `DECISIONS-NEEDED.md` at `{worktree}/.devflow/docs/design/{slug}/{ts}/`
 
 ---
 
@@ -33,13 +33,17 @@ 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-plan requires Claude Code's dynamic workflow runtime."
 2. **`agentType` support:** confirmed available (spike F5, 2026-06-11).
-3. **Tracker paths:** a list of issue references or URLs is read through the Git agent, which resolves the configured tracker and its access itself and reports `TRACEABILITY: DEGRADED (\{reason\})` when it cannot read an issue — then fall back to reading ticket `.md` files from a local path. No tracker CLI is checked here.
+3. **Tracker paths:** a list of issue references or URLs is read through the Git agent, which resolves the configured tracker and its access itself and reports `TRACEABILITY: DEGRADED ({reason})` when it cannot read an issue — then fall back to reading ticket `.md` files from a local path. No tracker CLI is checked here.
 4. **No-remote path:** if the repo has no remote, read ticket files from the provided local path; the Git agent reports DEGRADED for any issue it cannot reach.
 
 ---
 
 ### Pre-authoring setup
 
+{{docs_root()}}
+
+Pass `{worktree}` to the workflow as its `root` argument.
+
 **1. Apply decisions context**
 
 Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded per the preamble above: scan the index, Read relevant entries, note verbatim ADR/PF IDs to inject into Design agent and Evaluate agent prompts.
@@ -60,11 +64,11 @@ Determine the ticket source (in priority order):
 - A list of candidate issue references or issue URLs
 - Inline ticket descriptions passed as args
 
-{issue_ref_grammar()}
+{{issue_ref_grammar()}}
 
 Read or note the tickets. The agents will read them in full; you need the list and any key constraints.
 
-{issue_capture_contract()}
+{{issue_capture_contract()}}
 
 ---
 
@@ -76,11 +80,11 @@ After the workflow completes:
 1. **Check each plan's test plan.** For every path in `planPaths`, copy that plan's `## Test Plan` section — the heading and its TP lines, up to the next `## ` heading — byte for byte into a fresh `mktemp` file with the Write tool, never through an interpolated shell string, and run:
 
 ```bash
-node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" check tp <that file>; echo "exit=$?"
+node "$HOME/.devflow/scripts/verify-evidence.cjs" check tp <that file>; echo "exit=$?"
 ```
 
    Check the section, never the whole plan file: the plan's other `## ` headings are not evidence-file sections, so the script would parse the whole document as the plan. `exit=0` passes. Any other result names that plan `test plan malformed (<code>)` in your summary, `<code>` being the code the script printed on stderr; a plan with no `## Test Plan` section copies as an empty file, which the script refuses. Nothing is repaired: `/devflow:dynamic-build` passes no test plan from that plan.
-2. Read the `decisionsNeededPath` returned by the workflow (e.g. `.devflow/docs/design/<slug>/<ts>/DECISIONS-NEEDED.md`). Always use the OUTDIR-scoped path the workflow wrote — never the flat `.devflow/docs/design/DECISIONS-NEEDED.md`.
+2. Read the `decisionsNeededPath` returned by the workflow (e.g. `{worktree}/.devflow/docs/design/<slug>/<ts>/DECISIONS-NEEDED.md`). Always use the OUTDIR-scoped path the workflow wrote — never the flat `{worktree}/.devflow/docs/design/DECISIONS-NEEDED.md`.
 3. First surface the **Auto-Resolved Decisions** section (decision → resolution → source) for audit, then surface ALL open **Decisions Needed** to the user in ONE batched `AskUserQuestion` (never one-at-a-time).
 4. The user's answers feed into their own plan edits or a follow-up `/devflow:dynamic-plan` run.
 
@@ -107,7 +111,8 @@ const PREFERENCE_PROFILE = args.preferenceProfile || "";  // injected before aut
 const TP_CONTRACT = args.tpContract || "";  // the "Test-plan line (TP)" contract below — its paragraph and four bullets — passed verbatim as tpContract when invoking the workflow, never pasted into this script (it holds backticks)
 const slug = args.slug || "wave";
 const ts = new Date().toISOString().slice(0,16).replace(/[-:T]/g, (c) => c === 'T' ? '_' : c === ':' ? '' : c);
-const OUTDIR = `.devflow/docs/design/${slug}/${ts}`;
+const ROOT = args.root;  // {worktree} from Pre-authoring setup: the checkout's toplevel, never cwd
+const OUTDIR = `${ROOT}/.devflow/docs/design/${slug}/${ts}`;
 
 // Phase 1: Read all tickets
 const tickets = await phase("read-tickets", () =>
@@ -230,17 +235,17 @@ Return: { planPaths (array), decisionsNeededPath (string), decisionsNeededCount
 
 The plan-challenge step (Phase 3 above) MUST produce the acceptance criteria and test plan shape that `/devflow:dynamic-build`'s Gate 2 consumes:
 
-{acceptance_criteria_contract()}
+{{acceptance_criteria_contract()}}
 
 ---
 
 ### Artifact paths
 
-Per-ticket plans → `.devflow/docs/design/\{slug\}/\{ts\}/\{ticket-slug\}-plan.md`
+Per-ticket plans → `{worktree}/.devflow/docs/design/{slug}/{ts}/{ticket-slug}-plan.md`
 
-Decisions needed → `.devflow/docs/design/\{slug\}/\{ts\}/DECISIONS-NEEDED.md`
+Decisions needed → `{worktree}/.devflow/docs/design/{slug}/{ts}/DECISIONS-NEEDED.md`
 
-Honor the `WORKTREE_PATH` prefix when provided.
+`{worktree}` is the docs root resolved in Pre-authoring setup (it honours `WORKTREE_PATH` when provided).
 
 ---
 

package/src/assets/commands/dynamic-profile.mds

@@ -4,8 +4,7 @@ argument-hint: "[--dry-run]"
 output-dir: dist/commands
 ---
 @import { authoring_preamble } from "./_partials/_preamble.mds"
-
-{authoring_preamble()}
+{{authoring_preamble()}}
 
 ---
 
@@ -19,14 +18,26 @@ The profile is then consumed by `/devflow:dynamic-plan` to pre-resolve design de
 
 ---
 
-**Requires:** read access to `~/.claude/projects/*/` session transcripts and `~/.claude/rules/`
+**Requires:** read access to `{claude_dir}/projects/*/` session transcripts and `{claude_dir}/rules/`
 **Produces:** `~/.devflow/preference-profile.md` — plain-prose decision-preference profile
 
 ---
 
+### Claude Code's directory
+
+`{claude_dir}` is Claude Code's directory, resolved once, the way the installer resolves it (D-CLAUDE-DIR-PROMPTS): `CLAUDE_CONFIG_DIR` when that is set to an absolute path, else `$HOME/.claude`. Run
+
+```bash
+d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"
+```
+
+and use its one-line output. Pass it to the agent below as `CLAUDE_DIR`.
+
+---
+
 ### Privacy note
 
-This command mines session transcripts across **all projects** on this machine — `~/.claude/projects/*/*.jsonl`, `~/.claude/history.jsonl`, and feedback memories. The resulting profile is then injected into planning prompts as context. This is a cross-project surface: patterns from one project's decisions may influence planning in another.
+This command mines session transcripts across **all projects** on this machine — `{claude_dir}/projects/*/*.jsonl`, `{claude_dir}/history.jsonl`, and feedback memories. The resulting profile is then injected into planning prompts as context. This is a cross-project surface: patterns from one project's decisions may influence planning in another.
 
 Mitigation: the profile is plain prose that you review and edit before use. You can trim, redact, or rewrite any section. The profile is at `~/.devflow/preference-profile.md` — open it, read it, adjust it. It is never committed to any repo.
 
@@ -38,8 +49,8 @@ Session transcripts on a typical machine are gigabytes. **The agent MUST NOT ful
 
 1. Use `rg` (ripgrep) or `grep` to search for `AskUserQuestion` occurrences across transcript files — extracting just the question text and the surrounding user response (a few lines each).
 2. Sample the results — take up to ~200 instances spread across projects and time; do not feed everything into context at once.
-3. Read `~/.claude/rules/` files (these are small) to supplement with explicitly stated preferences.
-4. Read existing feedback memory files (`~/.claude/projects/*/memory/*.md`) — these are small and already distilled.
+3. Read `{claude_dir}/rules/` files (these are small) to supplement with explicitly stated preferences.
+4. Read existing feedback memory files (`{claude_dir}/projects/*/memory/*.md`) — these are small and already distilled.
 
 This grep-and-sample approach is both efficient and Iron-Rule-safe: the agent uses `rg`/`grep` as tools — no extractor or clustering logic is authored.
 
@@ -47,7 +58,7 @@ This grep-and-sample approach is both efficient and Iron-Rule-safe: the agent us
 
 ### When --dry-run is passed
 
-Print what the agent would do (a summary of which paths it would search, what it would write) and STOP — do not spawn the agent.
+Print what the agent would do (a summary of which paths under the resolved `{claude_dir}` it would search, what it would write) and STOP — do not spawn the agent.
 
 ---
 
@@ -58,15 +69,17 @@ Spawn a single Knowledge agent with this task:
 ```
 You are distilling a decision-preference profile from past session history.
 
+CLAUDE_DIR: {claude_dir} — Claude Code's directory, already resolved; every path below is under it.
+
 BOUNDED READING — MANDATORY: transcripts are gigabytes; never full-read them.
-1. Run: rg -l "AskUserQuestion" ~/.claude/projects/ 2>/dev/null | head -50
+1. Run: rg -l "AskUserQuestion" "{claude_dir}/projects/" 2>/dev/null | head -50
    to find transcript files that contain AskUserQuestion moments.
 2. For each found file, run: rg -A 5 "AskUserQuestion" <file> | head -200
    to extract the question + nearby user response context. Sample broadly —
    aim for ~150-200 instances spread across projects and time windows.
-3. Read ~/.claude/history.jsonl if it exists (rg "AskUserQuestion" ... similarly).
-4. Read all files in ~/.claude/rules/ (small — read fully).
-5. Read all *.md files in ~/.claude/projects/*/memory/ (small — read fully).
+3. Read {claude_dir}/history.jsonl if it exists (rg "AskUserQuestion" ... similarly).
+4. Read all files in {claude_dir}/rules/ (small — read fully).
+5. Read all *.md files in {claude_dir}/projects/*/memory/ (small — read fully).
 
 From this evidence, identify the recurring patterns in how the user answers design
 questions. Look for preferences about: