devflow-kit 3.0.1 → 3.2.0

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

@@ -79,7 +79,13 @@ Note the `budget` value from the Workflow tool context (or default to "medium" i
 
 **3. Detect mode: SINGLE or WAVE**
 
-- **SINGLE mode:** input is one ticket, one issue, one task description, or one plan document
+What follows the command is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+- **SINGLE mode:** `COMMAND_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** (`{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`.
 
@@ -113,7 +119,7 @@ If none found: build proceeds Gate-1-only (Gate 2 skipped with a note). Never re
 **5. Resolve tracking-issue number (optional)**
 
 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`)
+- An explicit candidate issue reference or issue URL in `COMMAND_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 `{worktree}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.md`), as a raw token — only when the file holds exactly one `**Issue:**` line
 - Otherwise: none
 
@@ -194,7 +200,7 @@ 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.
+When you build or run tests to verify your work, follow your Running commands block.
 
 After implementing, commit your changes with a conventional-commit message and report:
 - Files changed
@@ -206,7 +212,7 @@ After implementing, commit your changes with a conventional-commit message and r
 const gate1 = await phase("gate1", async () => {
   // Gate 1 #1 — runs once, immediately after the initial implementation.
   const validation = await agent(`Run build, typecheck, lint, and tests on branch ${BRANCH}.
-For any build/test that may run silent >120s, use the background-Bash + Monitor poll procedure (your "Long-running commands" discipline) so you never trip the 180s watchdog; prefer package-scoped commands.
+Follow your Running commands block for every build and test command.
 Report: PASS or FAIL with details.`, { agentType: "Validate" });
 
   if (validation.verdict === "FAIL") {
@@ -261,7 +267,7 @@ ${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" });
+Self-verify your fix compiles, following your Running commands block. Commit fixes.`, { agentType: "Code" });
       evalVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
   }
@@ -271,7 +277,7 @@ Self-verify your fix compiles (background-Bash + Monitor for any build >120s —
     const testResult = await agent(`Run scenario-based acceptance tests on branch ${BRANCH} against these criteria:
 ${CRITERIA || "(none)"}
 TEST_PLAN: ${TEST_PLAN || "(none)"}
-For any test/build command that may run silent >120s, use the background-Bash + Monitor poll procedure (your "Long-running commands" discipline) so you never trip the 180s watchdog.
+Follow your Running commands block for every scenario command.
 Cover: functionality, API contracts, performance, and cover every TEST_PLAN scenario. Report: PASS or FAIL per scenario.`, { agentType: "Test" });
     testVerdict = testResult.verdict;
     if (testVerdict === "FAIL") {
@@ -281,7 +287,7 @@ ${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" });
+Self-verify your fix compiles and the scenarios pass, following your Running commands block. Commit fixes.`, { agentType: "Code" });
       testVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
   }
@@ -395,7 +401,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.
+Fix all findings in this batch. Self-verify your fix compiles, following your Running commands block. 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 });
     }
@@ -435,7 +441,7 @@ Return: {"status": "fixed"|"blocked", "commitShas": ["<sha>"], "unresolved": ["<
 // this is the build gate before the branch is handed back. See gate1_postcode() cadence.
 const gate1Final = await phase("gate1-final", async () => {
   const validation = await agent(`Run build, typecheck, lint, and tests on branch ${BRANCH} (final gate after all fixing).
-For any build/test that may run silent >120s, use the background-Bash + Monitor poll procedure (your "Long-running commands" discipline) so you never trip the 180s watchdog; prefer package-scoped commands.
+Follow your Running commands block for every build and test command.
 Report: PASS or FAIL with details.`, { agentType: "Validate" });
 
   if (validation.verdict === "FAIL") {
@@ -447,7 +453,7 @@ 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" });
+      const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (follow your Running commands block). Report: PASS or FAIL.`, { agentType: "Validate" });
       if (recheck.verdict === "PASS") break;
       failureDetails = recheck.details || failureDetails;
       if (attempt === 2) return { verdict: "ESCALATED", reason: "Final Gate 1 validation exhausted after 2 Code agent fix attempts" };
@@ -459,7 +465,7 @@ Self-verify your fix compiles. Commit fixes with conventional-commit message.`,
   const scrutiny = await agent(`9-pillar self-review of recent changes on branch ${BRANCH}. Report any code you changed and your findings.`, { agentType: "Scrutinize" });
 
   if (scrutiny.codeChanged) {
-    await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (Scrutinize agent made changes; background+Monitor for long commands). Report: PASS or FAIL.`, { agentType: "Validate" });
+    await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (Scrutinize agent made changes; follow your Running commands block). Report: PASS or FAIL.`, { agentType: "Validate" });
   }
 
   return { verdict: "PASS" };
@@ -739,4 +745,4 @@ Update the wave PR's test-plan block and post its evidence comment."
 
 ### Maintenance note
 
-This recipe encodes the current `/implement` + `/code-review` + `/resolve` orchestration shape as of the authoring date (2026-06-12). When those base commands change their orchestration, update this recipe to match. No tooling detects drift — by design (ADR-008 Iron Rule). The reminder lives in the design doc §16.
+This recipe encodes the current `/implement` + `/code-review` + `/resolve` orchestration shape as of the authoring date (2026-06-12). When those base commands change their orchestration, update this recipe to match. No tooling detects drift — by design (the LLM-vs-plumbing Iron Rule). The reminder lives in the design doc §16.

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

@@ -59,7 +59,13 @@ If present, note its contents as `PREFERENCE_PROFILE`. This will be used to auto
 
 **3. Resolve ticket input**
 
-Determine the ticket source (in priority order):
+What follows the command is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+Determine the ticket source from `COMMAND_INPUT` (in priority order):
 - A directory of ticket `.md` files (from `/devflow:dynamic-tickets` output)
 - A list of candidate issue references or issue URLs
 - Inline ticket descriptions passed as args
@@ -127,7 +133,7 @@ const plans = await phase("plan-parallel", () =>
   parallel((tickets || []).map(ticket => () =>
     agent(`Write an implementation plan for this ticket.
 Ticket: ${JSON.stringify(ticket)}
-Decisions context (apply devflow:apply-decisions; cite ADR/PF IDs): ${DECISIONS_CONTEXT}
+Decisions context (apply devflow:apply-decisions; a plan file can be posted to the tracker, so state each decision in words, never by ID): ${DECISIONS_CONTEXT}
 The plan must cover: approach overview, affected files and modules, key design decisions, implementation sequence (what to build first), risks and mitigations, and any open questions you cannot resolve from the ticket alone.
 Write a thorough but tight plan — every section must earn its place for a Code agent who has no other context.
 Return: { ticketTitle, planMarkdown, openDecisions (array of genuine unknowns requiring user input) }.`, { agentType: "Design" })
@@ -218,7 +224,7 @@ For each ticket, write ${OUTDIR}/{ticket-slug}-plan.md containing:
 - ## Acceptance Criteria (numbered, positive + negative)
 - ## Test Plan — the challenger's testPlan lines, verbatim, one per line, and nothing else: no prose, no blank line between them, no setup or outcome
 - ## Test Scenarios — one line per TP, in TP order: TP-n: its setup, then its expected outcome, from testScenarios
-- ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source)
+- ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source, naming a recorded decision in words, never by ID)
 
 Then write ${OUTDIR}/DECISIONS-NEEDED.md:
 - ## Auto-Resolved Decisions — list each silently-resolved decision as: decision → resolution → source (preference profile / ADR-NNN), so auto-resolution is auditable and reversible. If none, write "None."
@@ -268,4 +274,4 @@ After the workflow returns: check each plan's test plan (step 1 of the F4 list a
 
 ### Maintenance note
 
-This recipe encodes the planning pipeline as of the authoring date (2026-06-12). The plan-challenge verbatim intent (§5.1) is load-bearing — do not paraphrase it when authoring the challenger agent prompt. The "Acceptance criteria + test plan contract" section above is the shared shape with `/devflow:dynamic-build` Gate 2; any change must be kept in sync. No tooling detects drift — by design (ADR-008 Iron Rule).
+This recipe encodes the planning pipeline as of the authoring date (2026-06-12). The plan-challenge verbatim intent (§5.1) is load-bearing — do not paraphrase it when authoring the challenger agent prompt. The "Acceptance criteria + test plan contract" section above is the shared shape with `/devflow:dynamic-build` Gate 2; any change must be kept in sync. No tooling detects drift — by design (the LLM-vs-plumbing Iron Rule).

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

@@ -142,4 +142,4 @@ Next steps:
 
 ### Maintenance note
 
-This command mines ALL projects' history on this machine. The bounded-reading discipline (grep/rg + sample — never full-read) is mandatory and must be preserved in every revision. The agent writes prose; no extraction or clustering algorithm is authored here. Per ADR-008 Iron Rule: the agent does the reading and summarizing — not a script we maintain.
+This command mines ALL projects' history on this machine. The bounded-reading discipline (grep/rg + sample — never full-read) is mandatory and must be preserved in every revision. The agent writes prose; no extraction or clustering algorithm is authored here. Per the LLM-vs-plumbing Iron Rule: the agent does the reading and summarizing — not a script we maintain.

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

@@ -105,7 +105,7 @@ const drafts = await phase("draft", () =>
     agent(`Draft ticket for initiative: "${initiative}"
 Ticket: ${JSON.stringify(c)}
 Constraints: ${constraints}
-Decisions context (apply devflow:apply-decisions; cite ADR/PF IDs): ${DECISIONS_CONTEXT}
+Decisions context (apply devflow:apply-decisions; the ticket is filed to the tracker, so state each decision in words, never by ID): ${DECISIONS_CONTEXT}
 Write the ticket body following the ticket_body_template structure (Wave/Depends-on header, Summary, Scope with In/Out + anti-features, Invariants, numbered Acceptance Criteria with at least one negative criterion, Open Questions).
 Return a JSON object with: title (string), summary (string), wave (number), dependsOn (array), bodyMarkdown (string), openQuestions (array).`, { agentType: "Design" })
   ))
@@ -270,4 +270,4 @@ The tracking-issue path and any open questions are the primary handoff to `/devf
 
 ### 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 ADR-008, 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 (ADR-008 Iron Rule).
+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/src/assets/commands/explore.mds

@@ -18,7 +18,13 @@ Explore a codebase area by spawning parallel agents for flow tracing, dependency
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/explore`:
+What follows `/explore` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$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
@@ -58,6 +64,8 @@ Based on Skim agent findings, spawn 2-3 `Agent(subagent_type="Explore")` agents
 
 Adjust explorer focus based on the specific exploration question.
 
+Ask each explorer for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
+
 ### Phase 4: Synthesize
 
 **Produces:** MERGED_FINDINGS

package/src/assets/commands/implement.mds

@@ -25,7 +25,13 @@ Orchestrate a single task through implementation by spawning specialized agents.
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/implement`:
+What follows `/implement` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Plan document path: `.devflow/docs/design/42-jwt-auth.2026-04-07_1430.md` (path to an existing `.md` file)
 - Issue reference: `#42`
 - Task description: "implement JWT auth"
@@ -53,15 +59,13 @@ If the user prompt does NOT match re-validation, proceed with the full pipeline
 
 **Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
 
-**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:dependency-research`. If a skill fails to load, continue without it.
-
 Record the current branch name as `BASE_BRANCH` - this will be the PR target.
 
 {{docs_root()}}
 
 {{evidence_policy()}}
 
-**Plan Document Handling** (when $ARGUMENTS is a path ending in `.md`):
+**Plan Document Handling** (when `COMMAND_INPUT` is a path ending in `.md`):
 1. Read the plan document from the path provided
 2. Extract from YAML frontmatter: `execution-strategy`, `context-risk`, `issue` number
 3. Extract from body: Subtask Breakdown, Implementation Plan, Patterns to Follow, Acceptance Criteria
@@ -72,23 +76,25 @@ Record the current branch name as `BASE_BRANCH` - this will be the PR target.
 
 If `PR_DESCRIPTION_GUIDANCE` was not set above (non-plan paths: issue input or task description), set it to `(none)`.
 
+**Empty input.** When `COMMAND_INPUT` is empty — a plan handoff arrives this way, with the plan already in the conversation — there is no argument to name the branch from, and the Git agent sees none of this conversation. Write the description yourself: one line, taken from the plan's title or, with no plan, from the conversation. Send it as the setup-task `TASK_DESCRIPTION` below.
+
 Spawn Git agent to set up task environment. The Git agent derives the branch name automatically from the issue or task description:
 
 ```
 Agent(subagent_type="Git"):
 "OPERATION: setup-task
 BASE_BRANCH: {current branch name}
-ISSUE_INPUT: {$ARGUMENTS verbatim, when it is a single whitespace-delimited token that does not end in .md; when it ends in .md, the plan frontmatter's issue value verbatim unless absent or pending — otherwise omit}
-TASK_DESCRIPTION: {$ARGUMENTS verbatim, when it is two or more whitespace-delimited tokens — otherwise omit}
+ISSUE_INPUT: {COMMAND_INPUT verbatim, when it is a single whitespace-delimited token that does not end in .md; when it ends in .md, the plan frontmatter's issue value verbatim unless absent or pending — otherwise omit}
+TASK_DESCRIPTION: {COMMAND_INPUT verbatim, when it is two or more whitespace-delimited tokens; when COMMAND_INPUT is empty, the one-line description you wrote above — otherwise omit}
 ISSUE_REQUIRED: {ISSUE_REQUIRED}
 APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
-PLAN_ARTIFACT_PATH: {path to plan document if $ARGUMENTS ends in .md, otherwise (none)}
+PLAN_ARTIFACT_PATH: {path to plan document if COMMAND_INPUT ends in .md, otherwise (none)}
 Derive branch name from issue or description, create feature branch, and fetch issue if specified.
 Return the branch setup summary."
 ```
 
 The issue token is forwarded **unclassified**, and the routing is decided by
-SHAPE alone — how many tokens `$ARGUMENTS` has, and whether it ends in `.md`.
+SHAPE alone — how many tokens `COMMAND_INPUT` has, and whether it ends in `.md`.
 
 `setup-task` is the one step that has resolved a provider, and therefore the only
 one that knows what an issue reference looks like on this machine: `#123`,
@@ -133,7 +139,7 @@ visible, a silently discarded request is not.
 
 **Test plan.** Before any Code spawn, give the task a test plan in the evidence file `{worktree}/.devflow/docs/evidence-{branch_slug}.md` (`EVIDENCE_FILE`) — unlike the handoff file, it stays after the PR exists. It holds up to three sections, in this order and nothing else: `## Test Plan`; `## Evidence Exceptions`, a byte copy of `PR_EXCEPTIONS` present only while that is not `(none)`; and `## Claims`, always last, so every claim is appended at the end of the file. Create the file if absent; if it exists, replace its `## Test Plan` and `## Evidence Exceptions` sections and keep `## Claims` byte-identical.
 
-Write the `## Test Plan` section: when `$ARGUMENTS` is a plan document with a `## Test Plan` section, copy that section's lines verbatim; otherwise write one TP line per acceptance criterion the plan, the issue or the task text states, numbered from `TP-1`. Never invent a criterion, and word every scenario yourself in plain words: the lines reach the PR body, so a scenario holds no `#`, `@` or `/` — no issue reference, mention, closing keyword target or URL — and the files a TP covers go in its `files:` field. Each line follows the TP-line contract:
+Write the `## Test Plan` section: when `COMMAND_INPUT` is a plan document with a `## Test Plan` section, copy that section's lines verbatim; otherwise write one TP line per acceptance criterion the plan, the issue or the task text states, numbered from `TP-1`. Never invent a criterion, and word every scenario yourself in plain words: the lines reach the PR body, so a scenario holds no `#`, `@` or `/` — no issue reference, mention, closing keyword target or URL — and the files a TP covers go in its `files:` field. Each line follows the TP-line contract:
 
 {{test_plan_line()}}
 
@@ -314,7 +320,7 @@ ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}"
 After Code agent completes, spawn Validate agent to verify correctness:
 
 ```
-Agent(subagent_type="Validate", model="haiku"):
+Agent(subagent_type="Validate"):
 "FILES_CHANGED: {list of files from Code agent output}
 VALIDATION_SCOPE: full
 Run build, typecheck, lint, test. Report pass/fail with failure details."
@@ -394,7 +400,7 @@ If Scrutinize agent returns BLOCKED, report to user and halt.
 If Scrutinize agent made code changes (status: FIXED), spawn Validate agent to verify:
 
 ```
-Agent(subagent_type="Validate", model="haiku"):
+Agent(subagent_type="Validate"):
 "FILES_CHANGED: {files modified by Scrutinize agent}
 VALIDATION_SCOPE: changed-only
 Verify Scrutinize agent's fixes didn't break anything."
@@ -442,7 +448,7 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta
    ```
    - Spawn Validate agent to verify fix didn't break tests:
    ```
-   Agent(subagent_type="Validate", model="haiku"):
+   Agent(subagent_type="Validate"):
    "FILES_CHANGED: {files modified by fix Code agent}
    VALIDATION_SCOPE: changed-only"
    ```
@@ -490,7 +496,7 @@ After every Test agent run — PASS or FAIL, first run or retry — append its T
    ```
    - Spawn Validate agent to verify fix didn't break tests:
    ```
-   Agent(subagent_type="Validate", model="haiku"):
+   Agent(subagent_type="Validate"):
    "FILES_CHANGED: {files modified by fix Code agent}
    VALIDATION_SCOPE: changed-only"
    ```

package/src/assets/commands/plan.mds

@@ -26,7 +26,13 @@ The orchestrator only spawns agents and gates — all analytical work is done by
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/plan`:
+What follows `/plan` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Opens with a candidate issue reference → issue mode (one candidate = single-ref, more than one = multi-issue)
 - Path to existing `.md` file → **error**: "Use /implement with plan documents"
 - Other text → feature description
@@ -66,7 +72,7 @@ Explore the user's intent through focused Socratic questioning before spawning a
 
 **Step 0 — Fetch issue(s)** (issue mode only; skip for feature-description and empty modes):
 
-- **Single-ref** (one candidate ref in `$ARGUMENTS`):
+- **Single-ref** (one candidate ref in `COMMAND_INPUT`):
 
   ```
   Agent(subagent_type="Git"):
@@ -106,8 +112,6 @@ If the user says "skip" or "just proceed" — skip remaining questions, present
 **Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 **Requires:** CONFIRMED_SCOPE
 
-**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:software-design`, `devflow:security`, `devflow:design-review`. If a skill fails to load, continue without it.
-
 Spawn Skim agent for codebase context:
 
 ```
@@ -136,7 +140,7 @@ Pass `FEATURE_KNOWLEDGE` alongside `DECISIONS_CONTEXT` to Explore and Design age
 **Produces:** EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, DECISIONS_CONTEXT
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated."
+Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -265,7 +269,7 @@ User can:
 **Produces:** IMPL_EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, ACCEPTED_SCOPE
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope:
+Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope. Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -294,7 +298,7 @@ Combine into: patterns to follow, integration points, reusable code, edge cases"
 **Produces:** PLAN_OUTPUTS
 **Requires:** IMPL_EXPLORATION_SYNTHESIS, GAP_SYNTHESIS, DECISIONS_CONTEXT
 
-Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis:
+Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis. Ask each agent for a final report of at most about 1,500 tokens: the plan itself, not a restatement of the exploration.
 
 | Focus | Output |
 |-------|--------|
@@ -470,7 +474,7 @@ Spawn a Git agent with `OPERATION: ensure-traceable-issue`:
 ```
 Agent(subagent_type="Git"):
 "OPERATION: ensure-traceable-issue
-ISSUE_INPUT: {the raw candidate token from $ARGUMENTS if /plan was invoked with an issue reference, else omit}
+ISSUE_INPUT: {the raw candidate token from COMMAND_INPUT if /plan was invoked with an issue reference, else omit}
 TASK_DESCRIPTION: {Gate 0 confirmed scope — one-line title}
 INITIAL_REQUEST: {the Gate 0 confirmed scope statement}
 REQUIREMENTS: {discovered requirements summary from Phase 6 gap synthesis}

package/src/assets/commands/release.md

@@ -17,13 +17,19 @@ Release the project using adaptive learned configuration. On first run, scans th
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/release`:
+What follows `/release` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Explicit version: `v1.2.3` or `1.2.3`
 - Bump type: `patch`, `minor`, `major`
 - Flag: `--dry-run`
 - Empty: interactive mode (will ask for version)
 
-Parse from $ARGUMENTS:
+Parse from `COMMAND_INPUT`:
 - `VERSION`: explicit version string if present (strip leading `v`)
 - `BUMP_TYPE`: `patch | minor | major` if bump type provided
 - `DRY_RUN`: true if `--dry-run` present, false otherwise
@@ -48,7 +54,21 @@ Read `.release/RELEASE-FLOW.md`:
 
 **Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 
-Read `.devflow/learning/index.md`. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
+The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+
+```bash
+git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
+```
+
+Line 1 is the checkout's toplevel, line 2 the repository's common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first of these that applies:
+
+1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
+2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
+3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
+
+This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+
+Read `{ledger}/.devflow/learning/index.md`. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
 
 Load feature knowledge: Attempt to read `.devflow/features/index.md` (the regenerable cache). If absent or empty, glob `.devflow/features/*/KNOWLEDGE.md` and read each file's YAML frontmatter (`name`, `description`, `directories`) as the relevance surface. Pick release-relevant KBs by matching their documented area against the release context. For each selected KB, read the full `KNOWLEDGE.md` — trust current code over KB content on any mismatch. Concatenate under slug headers and set `FEATURE_KNOWLEDGE` (or `(none)` if no KBs exist or none are relevant). No `index.json`, no subprocess, no `.cjs` script.
 

package/src/assets/commands/research.mds

@@ -20,7 +20,13 @@ Research a topic by spawning parallel Research agents across multiple research t
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/research`:
+What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Research question: "best caching strategies"
 - Comparison question: "compare React vs Svelte for our use case"
 - Empty: use conversation context
@@ -35,7 +41,7 @@ Research a topic by spawning parallel Research agents across multiple research t
 
 {{decisions_load()}}
 
-Use `DECISIONS_CONTEXT` locally when framing research — prior decisions and pitfalls suggest areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. Pass `DECISIONS_CONTEXT` to each Research agent in Phase 4 so they can cite relevant decisions in findings.
+Use `DECISIONS_CONTEXT` locally when framing research — prior decisions and pitfalls suggest areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. Pass `DECISIONS_CONTEXT` to each Research agent in Phase 4 so their findings can account for relevant decisions.
 
 {{knowledge_load()}}
 
@@ -111,7 +117,7 @@ If external research was skipped due to tool unavailability: inform user.
 1. If `codebase` type was not in RESEARCH_PLAN → skip
 2. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
 3. Use AskUserQuestion: "No feature knowledge exists for {researched area}. Create one?"
-4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to load `devflow:feature-knowledge`, write `KNOWLEDGE.md`, and update `index.md` directly
+4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to write `KNOWLEDGE.md` and update `index.md` directly
 5. Set FEATURE_KNOWLEDGE_STATUS = created or skipped
 
 **Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.

package/src/assets/commands/resolve.mds

@@ -180,14 +180,14 @@ Wait for Triage agent to complete before proceeding. Parse verdict ledger from T
 - **ESCALATED**: Security issues requiring human escalation
 - **FIX_NOW**: Valid issues assigned to Code agents (with risk tier: Standard | Careful)
 - **FALSE_POSITIVE**: Issues the Review agent got wrong (with cited evidence)
-- **BY_DESIGN**: Intentional code (with ADR or code doc citation)
+- **BY_DESIGN**: Intentional code (with a recorded decision, stated in words, or a code doc citation)
 - **FIX_SEPARATE**: Valid but out of blast-radius scope (must become manage-debt ticket)
 - **TECH_DEBT**: Architectural overhaul only — LAST RESORT
 - **DUPLICATE**: Collapsed duplicate issue — carries `duplicate_of: <primary-id>` referencing the non-DUPLICATE primary; inherits the primary's outcome
 
-Collect all decisions citations (ADR-NNN / PF-NNN) from Triage agent Reasoning columns.
+Collect every decision and pitfall the Triage agent's Reasoning columns state, in its words — the resolution summary is posted, so it never carries an ADR/PF ID.
 
-**Triage agent completeness assertion (avoids PF-002):** Verify the parsed ledger against ISSUES before proceeding:
+**Triage agent completeness assertion:** Verify the parsed ledger against ISSUES before proceeding:
 1. Every issue `id` from ISSUES must appear in exactly one verdict bucket — none may vanish, none may appear in multiple buckets. DUPLICATE is a valid bucket; a valid DUPLICATE entry must name its `duplicate_of` primary (the `Duplicate Of` column of the ledger's DUPLICATE table) and that primary must be a non-DUPLICATE issue id. A missing `duplicate_of` or one that chains to another DUPLICATE is a **Triage agent failure** (retry-then-abort as below).
 2. If the Triage agent output is empty, contains a skill re-entrancy guard string (e.g., contains `already running`), or is missing any issue IDs from ISSUES: treat as a **Triage agent failure**:
    - Retry the Triage agent once with the same inputs.
@@ -275,7 +275,7 @@ If no fixes were made (CODE_AGENT_RESULTS contains 0 commits) → set VERIFICATI
 Otherwise, spawn Validate agent:
 
 ```
-Agent(subagent_type="Validate", model="haiku"):
+Agent(subagent_type="Validate"):
 "FILES_CHANGED: {list of files from Code agent output}
 VALIDATION_SCOPE: full
 Run build, typecheck, lint, test. Report pass/fail with failure details."
@@ -401,7 +401,7 @@ Run this step only when `EVIDENCE_POLICY` is `required` and THREAD_MAP is non-em
 
 Prepare THREAD_MAP with verdicts from triage/code agent results:
 - For each `ext-{N}`: match to an issue verdict (FIXED, FALSE_POSITIVE, BY_DESIGN, ESCALATED) by `file:line` correlation
-- If the matched issue has verdict DUPLICATE, use the **primary's** verdict and verification status for the reply — do not expose DUPLICATE to the thread author (avoids PF-024; caller-side mapping — git.md contracts unchanged)
+- If the matched issue has verdict DUPLICATE, use the **primary's** verdict and verification status for the reply — do not expose DUPLICATE to the thread author (caller-side mapping: the Git agent's verdict set has no DUPLICATE, so its contract stays unchanged)
 - Include `commit_sha` from Code agent results for FIXED verdicts
 - If `fork_no_push` is set: drop FIXED entries from THREAD_MAP — their commits never reached the PR — and record each as `DEGRADED` in `## Third-Party Threads`
 - Unmatched threads: ESCALATED (human review)
@@ -642,8 +642,7 @@ Written in Phase 5 (Collect Results) to `{TARGET_DIR}/resolution-summary.md`:
 
 ## Decisions Citations
 
-- applies ADR-{NNN} — {batch-id}, {issue-id}
-- avoids PF-{NNN} — {batch-id}, {issue-id}
+- {decision applied or pitfall avoided, stated in words — never its ID} — {batch-id}, {issue-id}
 
 (Omit section if no citations were made)
 
@@ -681,9 +680,9 @@ Final gate: PASS | FAILED after {n} attempts
 | {description} | {file}:{line} | {why} |
 
 ## By Design
-| Issue | File:Line | Rationale (ADR/doc) |
-|-------|-----------|---------------------|
-| {description} | {file}:{line} | {applies ADR-NNN or code comment} |
+| Issue | File:Line | Rationale (decision/doc) |
+|-------|-----------|--------------------------|
+| {description} | {file}:{line} | {the decision, in words, or code comment} |
 
 ## Fix Separately
 | Issue | File:Line | Reason | Tracked |

package/src/assets/mds/git/_pr.mds

@@ -35,7 +35,7 @@ omission:
 Headings below each section's own anchor are `###` by grammar, not by taste: a
 column-0 `## ` line outside a fence terminates the section for every guard that
 reads it through `extractOpSectionFromCorpus`, and everything under it becomes
-invisible while the bytes stay on disk (PF-063). The `## ` lines inside the two
+invisible while the bytes stay on disk. The `## ` lines inside the two
 summary operations' compose fences are indented payload and stay exactly as they
 were authored.
 
@@ -186,7 +186,7 @@ Load for `resolve-review-threads` under every tracker provider.
 Each `THREAD_MAP` entry carries one verdict:
 - `FIXED` — issue addressed
 - `FALSE_POSITIVE` — not a real issue; requires grep/file:line citation as evidence
-- `BY_DESIGN` — intentional; requires ADR or code citation as evidence
+- `BY_DESIGN` — intentional; requires a recorded decision, stated in words, or code citation as evidence
 - `ESCALATED` — requires human review
 
 (The resolution gate these verdicts feed — D9 — is stated in the agent's own section.)
@@ -205,7 +205,7 @@ unexplained unresolved threads.
    - **FALSE_POSITIVE**: `After investigation, this appears to be a false positive: {evidence}. No code change needed.`
    - **BY_DESIGN**: `This is intentional: {evidence}. No code change needed.`
    - **ESCALATED**: `This thread has been escalated for human review and recorded in the resolution summary.`
-   - Reply bodies MUST NOT contain verbatim content from the external thread body — cite only internal evidence (commit SHAs, file:line from this codebase, ADR IDs)
+   - Reply bodies MUST NOT contain verbatim content from the external thread body — cite only internal evidence (commit SHAs, file:line from this codebase)
 2. Write reply to `$DEVFLOW_BODY_RAW`; apply the Comment-sink scrub (D11) — non-zero exit → DEGRADED for that thread, continue per D4. Post reply via `addPullRequestReviewThreadReply` GraphQL mutation with `-F body=@"$DEVFLOW_BODY"` (file-ref form).
 
    (Step 3, the D9 gate, is stated in the agent's own section.)

package/src/assets/mds/tracker/_common.mds

@@ -76,7 +76,7 @@ One line is DELIBERATELY not here. The marker-neutralisation bullet
 NOT in its indentation — five spaces in one module and three in the other two,
 because the surrounding list nests differently. A define emits one string, so
 hoisting it would re-indent one of the three, and indentation is list grammar
-rather than whitespace here (PF-063). Normalising those lists is its own edit.
+rather than whitespace here. Normalising those lists is its own edit.
 
 @define state_batch_line(subject, subject_ref, ref_token):
 2b. Render each issue's {{subject}} as a `**State**: {state}` line of its own, between that issue's `### Issue {{ref_token}}:` heading and its `<untrusted-issue-body>` marker — OUTSIDE the wrapper, because {{subject_ref}} is an enum the tracker computed, not remote prose. A caller refreshing a batch reads it to see a ticket closed out of band.

package/src/assets/mds/tracker/_github.mds

@@ -26,7 +26,7 @@ the single-authority corpus is the divergence this split exists to prevent.
 Headings below each section's own anchor are `###` by grammar, not by taste: a
 column-0 `## ` line outside a fence terminates the section for every guard that
 reads it through `extractOpSectionFromCorpus`, and everything under it becomes
-invisible while the bytes stay on disk (PF-063).
+invisible while the bytes stay on disk.
 
 `_common.mds` is an ALIAS import (`as common`), as in the other two provider
 modules. A SELECTIVE import deep-copies each named function into every `@define`
@@ -226,13 +226,13 @@ This issue reached the size limit.
 
 Load when the resolved tracker provider is `github` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` provided: append a `## Closed Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)
+   - If `SHIPPED_ISSUES` provided: append a `## Shipped Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)
 @end
 
 @define gather_release_evidence():

package/src/assets/mds/tracker/_jira.mds

@@ -56,7 +56,7 @@ conflict the contract wins.
 Headings below each section's own anchor are `###` by grammar, not by taste: a
 column-0 `## ` line outside a fence terminates the section for every guard that
 reads it through `extractOpSectionFromCorpus`, and everything under it becomes
-invisible while the bytes stay on disk (PF-063).
+invisible while the bytes stay on disk.
 
 The comment-body cap is a PROVIDER FACT and is stated once, as `comment_cap()`
 below; every site that renders it invokes the define. It is not in `_mcp.mds`
@@ -180,13 +180,13 @@ Over `{{comment_cap()}}` characters the rolling item is closed and a successor i
 
 Load when the resolved tracker provider is `jira` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - {{common.ref_preflight_list("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`", "", "", " and the section is omitted rather than rendered empty.")}}
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the key itself on its own line, and record the discard under `### Substitutions`.