devflow-kit 3.0.0 → 3.1.0

package/dist/commands/dynamic-build.md

@@ -65,7 +65,21 @@ The `budget` global governs depth. Scale Review agent roster and verification vo
 
 ### DECISIONS_CONTEXT — obtain BEFORE authoring
 
-Before you author the workflow script, read `.devflow/learning/index.md` for the current worktree. 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.
+
+Before you author the workflow script, 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`.
 
 The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into agent prompts using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Only agents that need architectural context (Code agent, Evaluate agent, Review agent, Scrutinize agent) need DECISIONS_CONTEXT injected; lightweight agents (Validate agent, Simplify agent) do not.
 
@@ -73,7 +87,7 @@ The script body cannot perform this read — you (the main model) do it before a
 
 When a ticket requires multiple sequential Code agent phases, each Code agent writes `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. The next Code agent reads it via HANDOFF_FILE input. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Always read the handoff file directly — code is authoritative, summaries are supplementary.
 
-### IRON RULE (ADR-008: LLM-vs-plumbing)
+### IRON RULE (LLM-vs-plumbing)
 
 **Author ZERO deterministic feature code.** No parsers, no schedulers, no topological-sort, no dependency-graph helpers, no confidence formulas. ALL issue reading, dependency reasoning, and scheduling decisions are LLM judgment at runtime, performed by the workflow's agents. The recipe is instructions. The workflow script Claude authors IS the runtime logic — keep it free of hand-coded feature algorithms.
 
@@ -680,7 +694,7 @@ Code(agentType:"Code", prompt: full task + plan + DECISIONS_CONTEXT + handoff if
   → gate2_acceptance()   ← Gate 2 runs HERE — before the review pass, not after
 ```
 
-The Code agent prompt must include: task description, implementation plan (if one exists), relevant DECISIONS_CONTEXT (from `.devflow/learning/index.md`), the compliance lens (`COMPLIANCE_FRAMEWORKS` — every Code prompt carries it, fix prompts included), and any PRIOR_PHASE_SUMMARY / HANDOFF_FILE for sequential multi-phase tickets.
+The Code agent prompt must include: task description, implementation plan (if one exists), relevant DECISIONS_CONTEXT (the index you loaded before authoring), the compliance lens (`COMPLIANCE_FRAMEWORKS` — every Code prompt carries it, fix prompts included), and any PRIOR_PHASE_SUMMARY / HANDOFF_FILE for sequential multi-phase tickets.
 
 Gate 2 runs at implementation acceptance — this matches devflow's deliberate placement: "evaluation is part of implementation acceptance, not post-review" (§6.1).
 
@@ -1240,4 +1254,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/dist/commands/dynamic-plan.md

@@ -65,7 +65,21 @@ The `budget` global governs depth. Scale Review agent roster and verification vo
 
 ### DECISIONS_CONTEXT — obtain BEFORE authoring
 
-Before you author the workflow script, read `.devflow/learning/index.md` for the current worktree. 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.
+
+Before you author the workflow script, 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`.
 
 The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into agent prompts using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Only agents that need architectural context (Code agent, Evaluate agent, Review agent, Scrutinize agent) need DECISIONS_CONTEXT injected; lightweight agents (Validate agent, Simplify agent) do not.
 
@@ -73,7 +87,7 @@ The script body cannot perform this read — you (the main model) do it before a
 
 When a ticket requires multiple sequential Code agent phases, each Code agent writes `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. The next Code agent reads it via HANDOFF_FILE input. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Always read the handoff file directly — code is authoritative, summaries are supplementary.
 
-### IRON RULE (ADR-008: LLM-vs-plumbing)
+### IRON RULE (LLM-vs-plumbing)
 
 **Author ZERO deterministic feature code.** No parsers, no schedulers, no topological-sort, no dependency-graph helpers, no confidence formulas. ALL issue reading, dependency reasoning, and scheduling decisions are LLM judgment at runtime, performed by the workflow's agents. The recipe is instructions. The workflow script Claude authors IS the runtime logic — keep it free of hand-coded feature algorithms.
 
@@ -233,7 +247,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" })
@@ -324,7 +338,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."
@@ -430,4 +444,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/dist/commands/dynamic-profile.md

@@ -65,7 +65,21 @@ The `budget` global governs depth. Scale Review agent roster and verification vo
 
 ### DECISIONS_CONTEXT — obtain BEFORE authoring
 
-Before you author the workflow script, read `.devflow/learning/index.md` for the current worktree. 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.
+
+Before you author the workflow script, 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`.
 
 The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into agent prompts using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Only agents that need architectural context (Code agent, Evaluate agent, Review agent, Scrutinize agent) need DECISIONS_CONTEXT injected; lightweight agents (Validate agent, Simplify agent) do not.
 
@@ -73,7 +87,7 @@ The script body cannot perform this read — you (the main model) do it before a
 
 When a ticket requires multiple sequential Code agent phases, each Code agent writes `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. The next Code agent reads it via HANDOFF_FILE input. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Always read the handoff file directly — code is authoritative, summaries are supplementary.
 
-### IRON RULE (ADR-008: LLM-vs-plumbing)
+### IRON RULE (LLM-vs-plumbing)
 
 **Author ZERO deterministic feature code.** No parsers, no schedulers, no topological-sort, no dependency-graph helpers, no confidence formulas. ALL issue reading, dependency reasoning, and scheduling decisions are LLM judgment at runtime, performed by the workflow's agents. The recipe is instructions. The workflow script Claude authors IS the runtime logic — keep it free of hand-coded feature algorithms.
 
@@ -217,4 +231,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/dist/commands/dynamic-tickets.md

@@ -65,7 +65,21 @@ The `budget` global governs depth. Scale Review agent roster and verification vo
 
 ### DECISIONS_CONTEXT — obtain BEFORE authoring
 
-Before you author the workflow script, read `.devflow/learning/index.md` for the current worktree. 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.
+
+Before you author the workflow script, 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`.
 
 The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into agent prompts using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Only agents that need architectural context (Code agent, Evaluate agent, Review agent, Scrutinize agent) need DECISIONS_CONTEXT injected; lightweight agents (Validate agent, Simplify agent) do not.
 
@@ -73,7 +87,7 @@ The script body cannot perform this read — you (the main model) do it before a
 
 When a ticket requires multiple sequential Code agent phases, each Code agent writes `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. The next Code agent reads it via HANDOFF_FILE input. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Always read the handoff file directly — code is authoritative, summaries are supplementary.
 
-### IRON RULE (ADR-008: LLM-vs-plumbing)
+### IRON RULE (LLM-vs-plumbing)
 
 **Author ZERO deterministic feature code.** No parsers, no schedulers, no topological-sort, no dependency-graph helpers, no confidence formulas. ALL issue reading, dependency reasoning, and scheduling decisions are LLM judgment at runtime, performed by the workflow's agents. The recipe is instructions. The workflow script Claude authors IS the runtime logic — keep it free of hand-coded feature algorithms.
 
@@ -210,7 +224,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" })
   ))
@@ -641,4 +655,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/dist/commands/release.md

@@ -48,7 +48,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

@@ -64,7 +64,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
 

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.
@@ -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)
@@ -793,8 +793,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 +831,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/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.
@@ -156,7 +156,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}`);
             }
         }

package/dist/core/agent-models.js

@@ -2,8 +2,8 @@
  * Agent model mapping engine — schema, persistence, and convergence for the
  * per-agent model configuration feature.
  *
- * applies ADR-013: pure core-layer module, no Claude Code adapter concerns.
- * avoids PF-014: all fallible operations return Result, no process.exit().
+ * Pure core-layer module, no Claude Code adapter concerns.
+ * All fallible operations return Result, no process.exit().
  *
  * Mapping file: ~/.devflow/agent-models.json
  *   { version: 1, agents: { [name]: { model?, effort? } } }
@@ -48,7 +48,7 @@ export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
 /**
  * Membership set typed as ReadonlySet<string> so .has() accepts a plain
  * string argument without a cast — TypeScript's Set<T>.has() requires T, and
- * EFFORT_LEVELS[number] is a literal union, not string (applies ADR-003).
+ * EFFORT_LEVELS[number] is a literal union, not string.
  */
 const EFFORT_LEVELS_SET = new Set(EFFORT_LEVELS);
 // ---------------------------------------------------------------------------
@@ -288,7 +288,7 @@ export async function readAgentMapping(devflowDir, opts) {
  * A missing directory returns an empty set rather than throwing (ENOENT is
  * not an error — the install dir may not exist on a fresh machine before
  * `devflow init` runs). Any other OS error also returns an empty set
- * (degrade-not-throw per PF-009) — a transient or misconfigured path must
+ * (degrade-not-throw) — a transient or misconfigured path must
  * not prevent the TUI or --list from starting.
  *
  * @param installDir - Path to ~/.claude/agents/devflow (or equivalent).
@@ -411,7 +411,7 @@ async function readDirDefaults(dir) {
  * keep rendering (`devflow agents --list`), so it warns instead. Staying silent
  * is what makes the gap dangerous: resolveEffective returns an undefined model,
  * reapplyAgentMapping buckets the agent 'unchanged', and disabling the proxy
- * leaves an externally-pinned agent unreverted with nothing said (PF-022).
+ * leaves an externally-pinned agent unreverted with nothing said.
  *
  * @param dirs - Agent directories, most-preferred first. Injectable so tests can
  *   prove the precedence against a temp tree; all real callers use the default.
@@ -480,7 +480,7 @@ export async function reapplyAgentMapping(opts) {
         // Guard: reject mapping keys that would read/write outside the install directory.
         // A corrupted or adversarial agent-models.json could contain path-traversal keys
         // such as '../../etc/passwd'; this check prevents any filesystem access beyond
-        // opts.installDir. Per PF-009 (degrade-not-throw), this emits a warning and skips gracefully.
+        // opts.installDir. Degrade-not-throw: this emits a warning and skips gracefully.
         if (!isContainedIn(opts.installDir, mdFileName(agentName))) {
             localWarn(`reapplyAgentMapping: agent name "${agentName}" resolves outside the install ` +
                 `directory — skipped (containment guard)`);

package/dist/core/agent-state.js

@@ -2,10 +2,10 @@
  * Agent installation-state classification.
  *
  * Single source of truth for the STATE column shared by `--list` and the TUI.
- * Centralised here (core layer) per ADR-013 so neither cli/commands nor
+ * Centralised here (core layer) so neither cli/commands nor
  * cli/agents-view owns the vocabulary.
  *
- * applies ADR-013: pure core-layer module, no CLI-adapter concerns.
+ * Pure core-layer module, no CLI-adapter concerns.
  */
 import { isDormantExternalModel } from './external-models.js';
 // ---------------------------------------------------------------------------

package/dist/core/ansi.js

@@ -6,9 +6,9 @@
  * feature module (src/hud/). Re-exported verbatim from src/hud/colors.ts
  * so all existing HUD call sites remain untouched.
  *
- * applies ADR-013: src/core/ = agent-neutral logic; ANSI primitives have no
+ * src/core/ = agent-neutral logic; ANSI primitives have no
  * feature coupling and belong here, not in a feature module.
- * applies PF-017 corollary: one shared definition over per-consumer copies.
+ * One shared definition over per-consumer copies.
  */
 const ESC = '\x1b[';
 const RESET = `${ESC}0m`;

package/dist/core/cache.js

@@ -15,8 +15,9 @@
  *   path.join()'s normalization of ".." components. safeEntryPath() enforces
  *   containment and returns null on violation; all callers treat null as a miss.
  *
- * applies ADR-013: core-layer module, no Claude Code adapter concerns.
- * avoids PF-011: entries written via tmp→rename (writeFileAtomicExclusive).
+ * Core-layer module, no Claude Code adapter concerns.
+ * Entries are written via tmp→rename (writeFileAtomicExclusive), so a reader
+ * sees the old entry or the new one, never a missing or partial file.
  */
 import * as fs from 'node:fs';
 import { promises as fsAsync } from 'node:fs';
@@ -38,9 +39,9 @@ export const MAX_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 // All callers that write or read the model-discovery catalog AND the uninstall
 // removal target derive their directory paths from these functions. Keeping
 // write-site and removal-site in the same module prevents silent orphaning of
-// cache data on future relocations (avoids PF-013).
+// cache data on future relocations.
 //
-// applies ADR-013: path layout owned by the core module, not scattered across
+// Path layout owned by the core module, not scattered across
 // callers in src/cli/ or src/hud/.
 /**
  * Returns the model-discovery cache directory for the given devflowDir.
@@ -137,8 +138,6 @@ export function readCache(cacheDir, key, validate) {
  * The single canonical envelope parser — used by readCacheEntry (which adds
  * the expiry check on top) and exported for model-discovery.ts (stale-fallback
  * and prune sorters) so all callers share one parser and cannot drift.
- *
- * applies ADR-003: eliminated private parseEnvelope duplicate; one parser, one truth.
  */
 export function parseRawEnvelope(raw) {
     let parsed;
@@ -166,7 +165,7 @@ export function parseRawEnvelope(raw) {
  * Write a value to cache with a TTL in milliseconds.
  *
  * - Creates cacheDir at mode 0700 if absent (owner-only access).
- * - Writes the entry via atomic tmp→rename (avoids PF-011 delete-then-write window).
+ * - Writes the entry via atomic tmp→rename (no delete-then-write window).
  * - Hardens the entry to 0600 after the write (owner-only read/write for cache data
  *   that will feed agent frontmatter in later phases).
  * - TTL is clamped to MAX_TTL_MS before storage.
@@ -196,7 +195,7 @@ export async function writeCache(cacheDir, key, data, ttlMs) {
     }
     // Harden entry to 0600 after the atomic write. writeFileAtomicExclusive
     // preserves the existing mode on re-writes; this chmod bootstraps 0600 on
-    // the first write to a fresh entry. Best-effort, non-fatal (avoids PF-009).
+    // the first write to a fresh entry. Best-effort, non-fatal.
     try {
         await fsAsync.chmod(filePath, 0o600);
     }

package/dist/core/codex-auth-inspect.js

@@ -1,8 +1,8 @@
 /**
  * Codex credential-file inspection for `devflow proxy --status`.
  *
- * applies ADR-013: pure core-layer module — no Claude Code adapter concerns and
- *   no presentation (colour/format lives with the other CLI formatters).
+ * Pure core-layer module — no Claude Code adapter concerns and
+ * no presentation (colour/format lives with the other CLI formatters).
  *
  * WHY THIS EXISTS RATHER THAN IMPORTING THE ROUTING RUNTIME
  * The routing runtime validates this same file and exposes an equivalent
@@ -62,8 +62,8 @@ function jwtAccountId(token) {
 /**
  * Classify an I/O error from reading ~/.codex/auth.json into a CodexAuthState.
  *
- * applies ADR-013: pure classification logic belongs in src/core/, not in the
- *   CLI presentation layer that calls it.
+ * Pure classification logic belongs in src/core/, not in the
+ * CLI presentation layer that calls it.
  *
  * ENOENT is the ordinary "not signed in" case: the file has never been written
  * by `codex login`. Every other error (EACCES, EISDIR, EMFILE, …) is a real

package/dist/core/compliance-compose.js

@@ -5,8 +5,8 @@
  * fragment files, so installed artifacts differ by selection rather than being
  * static all-six blobs.
  *
- * Applies ADR-013: pure helpers in src/core/, no I/O.
- * Applies PF-009: warn-not-throw for per-item failures.
+ * Pure helpers in src/core/, no I/O.
+ * Warn-not-throw for per-item failures.
  */
 import { COMPLIANCE_FRAMEWORKS, stampComplianceRule } from './compliance.js';
 // ── Constants ──────────────────────────────────────────────────────────────────
@@ -278,7 +278,7 @@ function buildReferences(activeFrameworks, fragments) {
  * Strict boundary parser: validates all required sections (## Mapping / ##
  * Reference / ## Checklist / ## Rule) and their structural constraints.
  * CRLF-tolerant: Windows line endings are normalised before parsing.
- * Never throws (PF-009): all errors return { ok: false, error }.
+ * Never throws: all errors return { ok: false, error }.
  */
 export function parseComplianceFragment(id, raw) {
     // CRLF tolerance

package/dist/core/compliance.js

@@ -2,7 +2,7 @@
  * Core compliance framework registry and utilities.
  *
  * Pure module — no I/O, no side effects.
- * Applies ADR-013: pure helpers in src/core/, I/O orchestration in src/targets/.
+ * Pure helpers in src/core/, I/O orchestration in src/targets/.
  */
 /**
  * Canonical compliance framework registry.
@@ -26,7 +26,7 @@ export const COMPLIANCE_RULE_PLACEHOLDER = '${DEVFLOW_COMPLIANCE_FRAMEWORKS}';
  *   detection.md — generic detection heuristics
  *   sources.md   — authoritative source index
  *
- * Exported (ADR-013: pure constant in src/core/) so both compliance-install.ts
+ * Exported (pure constant in src/core/) so both compliance-install.ts
  * (install) and compliance.ts CLI (status/drift detection) share a single
  * definition. Adding a third always-present ref requires only one change here.
  */
@@ -60,7 +60,7 @@ function normalizeId(s) {
  * This is the trust boundary for framework IDs that did not come through
  * `parseFrameworkList` — most importantly `manifest.features.compliance.frameworks`,
  * which `normalizeComplianceFeature` only type-checks (it cannot reject unknown IDs
- * without violating the ADR-014 self-heal contract). Every framework ID that is about
+ * without violating the self-heal contract). Every framework ID that is about
  * to become an fs path segment or be written into an installed artifact must pass
  * through here first (AC-35, AC-36).
  *
@@ -111,7 +111,6 @@ export function parseFrameworkList(input) {
  *
  * Absent, null, malformed, or partially-valid → {enabled:false, frameworks:[]}.
  * Preserves valid {enabled: boolean, frameworks: string[]}.
- * (Applies ADR-014 self-heal idiom)
  */
 export function normalizeComplianceFeature(raw) {
     const DEFAULT = { enabled: false, frameworks: [] };

package/dist/core/evidence-policy.js

@@ -3,7 +3,7 @@
  * `resolve-evidence-policy.cjs`, never a second implementation of it.
  *
  * D-POLICY-CJS-SEAM: the resolver is plain CommonJS under src/assets/scripts/,
- * outside every tsconfig (PF-043, PF-069), so the interfaces below are
+ * outside every tsconfig, so the interfaces below are
  * TRANSCRIBED from its JSDoc typedefs and are the only shape authority on this
  * side — open those typedefs before changing anything here. The module is loaded
  * with `require()` from `scriptsDir()`, which resolves under the package root both
@@ -20,7 +20,7 @@
  * `lib/project-config.cjs` (loadProjectConfigLib), so the CLI judges a config
  * file's bytes exactly as the resolvers do.
  *
- * D-POLICY-NO-WRITE (applies ADR-024): `.devflow/project.json` is team-owned, and
+ * D-POLICY-NO-WRITE: `.devflow/project.json` is team-owned, and
  * devflow never writes or replaces a shared file it cannot prove it wrote. This
  * module therefore imports no fs API; the CLI only PRINTS the bytes a team may
  * choose to commit (`evidencePolicySuggestion`, and the migration lines of
@@ -101,23 +101,24 @@ function surfaceMismatches(value, surface) {
  * require() one package script and shape-check it against `surface`. Never
  * throws: a missing file is `not-found`; a module that throws on load or lacks a
  * surface key is `unusable`. The caller's type parameter is justified by the
- * surface check, which `satisfies` ties to the interface's keys.
+ * surface check, which `satisfies` ties to the interface's keys. Exported for
+ * src/core/learning-store.ts, which loads the learning store the same way.
  */
-function loadScript(file, surface) {
+export function loadScript(scriptPath, surface) {
     let loaded;
     try {
-        loaded = createRequire(import.meta.url)(file);
+        loaded = createRequire(import.meta.url)(scriptPath);
     }
     catch (err) {
         const code = err.code;
         if (code === 'MODULE_NOT_FOUND')
-            return { ok: false, error: { kind: 'not-found', path: file } };
+            return { ok: false, error: { kind: 'not-found', path: scriptPath } };
         const detail = err instanceof Error ? err.message : String(err);
-        return { ok: false, error: { kind: 'unusable', path: file, detail } };
+        return { ok: false, error: { kind: 'unusable', path: scriptPath, detail } };
     }
     const mismatches = surfaceMismatches(loaded, surface);
     if (mismatches.length > 0) {
-        return { ok: false, error: { kind: 'unusable', path: file, detail: `missing or mistyped: ${mismatches.join(', ')}` } };
+        return { ok: false, error: { kind: 'unusable', path: scriptPath, detail: `missing or mistyped: ${mismatches.join(', ')}` } };
     }
     return { ok: true, value: loaded };
 }
@@ -167,10 +168,10 @@ export function formatEvidencePolicyUnavailable(error) {
 /**
  * The `compliance --status` line: the resolved policy for `opts.dir`, or the
  * unavailable line when the loader failed — that line is the whole handling
- * (ADR-028). The caller passes the compliance state it already read, so the
- * manifest is never read twice. `resolve()` makes at most three `gh` calls and
- * bounds every subprocess with a timeout, so an offline machine degrades to a
- * flagged result rather than a hang.
+ * (only a damaged package fails the load). The caller passes the compliance
+ * state it already read, so the manifest is never read twice. `resolve()` makes
+ * at most three `gh` calls and bounds every subprocess with a timeout, so an
+ * offline machine degrades to a flagged result rather than a hang.
  */
 export function evidencePolicyStatusLine(loaded, opts) {
     if (!loaded.ok)
@@ -198,7 +199,7 @@ function suggestedFrameworks(complianceState) {
  * count); `null` otherwise. The bytes come
  * from the settings resolver's `serializeProjectSuggestion`, which returns them
  * only when they read back through the shared parser as exactly what was asked.
- * Nothing is written (D-POLICY-NO-WRITE, applies ADR-024).
+ * Nothing is written (D-POLICY-NO-WRITE).
  */
 export function evidencePolicySuggestion(complianceState, policy, settings) {
     if (policy.complianceDefault(complianceState) !== 'required')

package/dist/core/external-models.js

@@ -9,7 +9,7 @@
  * in src/core/model-discovery.ts. The TUI picker and --set validation use the
  * ExternalModelCatalog returned by those functions.
  *
- * applies ADR-013: pure core-layer module, no Claude Code adapter concerns.
+ * Pure core-layer module, no Claude Code adapter concerns.
  *
  * NOTE: the internal routing runtime package name must NEVER appear in
  * user-visible strings, CLI output, or error messages. User-facing vocabulary: