devflow-kit 3.0.1 → 3.2.0

package/dist/commands/implement.md

@@ -16,13 +16,19 @@ 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"
 - Empty: use conversation context
 
-**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `$ARGUMENTS` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
+**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `COMMAND_INPUT` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
 
 **A token of any other shape is neither coerced nor dropped silently — and no producer-side grammar check rejects it before the fetch.** Adjudication belongs to the operation that runs, and each one answers in its own Output block: `fetch-issue` strips a leading `#` and takes the text branch, so a non-numeric token is used as a **search term** and the operation returns the first open match or nothing; `fetch-issues-batch` resolves each token to an issue number, drops the ones it cannot resolve, and names them in `NOT_FOUND ({refs})` beside the issues it did fetch. Read the outcome from the operation that ran — a token's shape is a verdict nowhere, and there is nothing upstream holding it back.
 
@@ -48,8 +54,6 @@ 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 (D-DOCS-ROOT).** Every `.devflow/docs/` path this command reads or writes lives at the checkout's toplevel, never under the directory the session started in. Resolve `{worktree}` from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — by running
@@ -70,7 +74,7 @@ Accept the output only when it is exactly two lines: `exit=0` last and, before i
 
 Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
 
-**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
@@ -81,23 +85,25 @@ Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AU
 
 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`,
@@ -158,7 +164,7 @@ Note: the section reaches a public PR body. The Code agent re-checks every line
 
 **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 (TP).** Write every test-plan entry as one line in exactly this shape. `TP_LINE_RE` in `pr-evidence.cjs` parses it and refuses any other line.
 
@@ -428,7 +434,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."
@@ -508,7 +514,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."
@@ -556,7 +562,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"
    ```
@@ -604,7 +610,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"
    ```
@@ -740,8 +746,6 @@ DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
 
-Load the devflow:feature-knowledge skill and follow its authoring process.
-
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 

package/dist/commands/plan.md

@@ -18,13 +18,19 @@ 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
 - Empty → use conversation context
 
-**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `$ARGUMENTS` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
+**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `COMMAND_INPUT` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
 
 **A token of any other shape is neither coerced nor dropped silently — and no producer-side grammar check rejects it before the fetch.** Adjudication belongs to the operation that runs, and each one answers in its own Output block: `fetch-issue` strips a leading `#` and takes the text branch, so a non-numeric token is used as a **search term** and the operation returns the first open match or nothing; `fetch-issues-batch` resolves each token to an issue number, drops the ones it cannot resolve, and names them in `NOT_FOUND ({refs})` beside the issues it did fetch. Read the outcome from the operation that ran — a token's shape is a verdict nowhere, and there is nothing upstream holding it back.
 
@@ -62,7 +68,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:
 
 ```
@@ -212,7 +216,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 |
 |-------|-------------|------|
@@ -355,7 +359,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 |
 |-------|-------------|------|
@@ -384,7 +388,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 |
 |-------|--------|
@@ -573,7 +577,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/dist/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/dist/commands/research.md

@@ -16,7 +16,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
@@ -64,7 +70,7 @@ The index is one direct file read, written at render time by `render-decisions.c
 
 When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
 
-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.
 
 ### Load Feature Knowledge
 
@@ -183,7 +189,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/dist/commands/resolve.md

@@ -266,14 +266,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.
@@ -361,7 +361,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."
@@ -487,7 +487,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)
@@ -665,8 +665,6 @@ DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
 
-Load the devflow:feature-knowledge skill and follow its authoring process.
-
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
@@ -793,8 +791,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)
 
@@ -832,9 +829,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/dist/commands/self-review.md

@@ -225,8 +225,6 @@ DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
 
-Load the devflow:feature-knowledge skill and follow its authoring process.
-
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 

package/dist/core/agent-frontmatter.js

@@ -4,8 +4,8 @@
  * Pure module — zero I/O. All functions take content strings and return
  * new content strings; callers own file reads and writes.
  *
- * applies ADR-013: pure core-layer module, no Claude Code adapter concerns.
- * avoids PF-014: no process.exit(); all fallible paths return Result.
+ * Pure core-layer module, no Claude Code adapter concerns.
+ * No process.exit(); all fallible paths return Result.
  *
  * Regex scoping guarantee: ALL operations are confined to the FIRST `---…---`
  * block. Model/effort lines in the document body are never touched.
@@ -96,6 +96,31 @@ export function readFrontmatterModel(content) {
     const m = MODEL_RE.exec(parts.value.fmBody);
     return Ok(m ? m[1] : '');
 }
+// ---------------------------------------------------------------------------
+// readFrontmatterEffort
+// ---------------------------------------------------------------------------
+/**
+ * Read the `effort:` value from the first frontmatter block.
+ *
+ * D-SHIPPED-EFFORT: an agent's shipped effort is part of its shipped default,
+ * the same as its model, so the reader that answers "what did devflow ship?"
+ * must see both. This is the effort twin of readFrontmatterModel and has the
+ * same contract: it reads only the leading frontmatter block (an `effort:`
+ * line in the body is ignored), returns Ok('') when no `effort:` line exists,
+ * and returns an error for missing or unterminated frontmatter.
+ *
+ * The value is returned as written. Whether it is a valid effort level is the
+ * caller's decision (loadShippedAgentDefaults owns that check against
+ * EFFORT_LEVELS), so a typo in a shipped file is reported rather than hidden here.
+ */
+export function readFrontmatterEffort(content) {
+    const parts = parseFrontmatter(content);
+    if (!parts.ok)
+        return Err(parts.error);
+    const EFFORT_RE = /^effort:[ \t]*(.*?)[ \t]*$/m;
+    const m = EFFORT_RE.exec(parts.value.fmBody);
+    return Ok(m ? m[1] : '');
+}
 /**
  * Rewrite the `model:` and optionally `effort:` lines in the first
  * frontmatter block of `content`.
@@ -156,7 +181,7 @@ export function rewriteAgentFrontmatter(content, opts) {
             if (currentEffort !== opts.effort) {
                 // Use a replacement function — NOT a string — so that $&, $`, $',
                 // and $1 in opts.effort are written verbatim rather than expanded as
-                // replacement patterns (avoids PF-018).
+                // replacement patterns.
                 newBody = newBody.replace(EFFORT_RE, () => `effort: ${opts.effort}`);
             }
         }