devflow-kit 3.10.0 → 3.12.0

package/dist/commands/self-review.md

@@ -1,10 +1,8 @@
 ---
-description: Self-review workflow - Polish agent (code clarity) then Harden agent (9-pillar quality gate)
+description: Polish (code clarity), then Harden (9-pillar quality gate)
 ---
 # Self-Review Command
 
-Run Polish agent and Harden agent sequentially on changed files for post-implementation quality refinement.
-
 ## Usage
 
 /self-review              (auto-detect changed files from git)
@@ -24,42 +22,33 @@ Detect changed files and build context:
 4. Build TASK_DESCRIPTION from recent commit messages or branch name
 5. Record `HEAD_BEFORE` (`git rev-parse HEAD`) now, before Polish runs — Phase 3 compares against it
 
-**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root in a one-worktree run:
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for:
 
 ```bash
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (including a script that cannot run) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
 
 The accepted line is the only source of these values.
 
 ### Load DECISIONS_CONTEXT
 
-When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, reading no index.
+
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy.
 
-The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-Line 1 is the checkout's toplevel, line 2 the 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 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 curation hooks apply, so you read the index the Curate agent writes.
-
-**Step 1 — Read the pre-rendered index:**
-
-Attempt to read `{ledger}/.devflow/curation/index.md`.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
-- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+**Step 1 — Read the pre-rendered index** `{ledger}/.devflow/curation/index.md`. Its content is `DECISIONS_CONTEXT`; if it is absent or empty, `DECISIONS_CONTEXT` is `(none)`.
 
-The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+The index is one direct file read.
 
 **Step 2 — Slice the index, then hand it on:**
 
@@ -67,51 +56,33 @@ When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contr
 
 Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
 
-Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
-
-Pass `DECISIONS_CONTEXT` to Harden agent — the compact index lists active ADR/PF entries; Harden agent uses `devflow:apply-decisions` to Read full entry bodies on demand. Known pitfalls help identify reintroduced issues, prior decisions help validate architectural consistency. (Polish agent does not consume decisions — it operates at code-shape level and Harden agent runs after to catch any architectural drift.)
+Pass `DECISIONS_CONTEXT` to the Harden agent only. The Polish agent takes no decisions.
 
 ### Load Feature Knowledge
 
-Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
-```
-
-and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
-
-**Step 1 — Read the index cache:**
-
-Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
-
-```
-- **{slug}** — {areas} — {Use-when description}
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-If `index.md` exists and contains at least one entry line, use it for relevance matching.
-
-**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
+All paths below are relative to `{worktree}`.
 
-**Step 3 — Pick relevant KBs:**
+**Step 1 — Read the index cache** `{worktree}/.devflow/features/index.md`. Each line has the form `- **{slug}** — {areas} — {Use-when description}`. If `index.md` is absent or has no entry line, glob `{worktree}/.devflow/features/*/KNOWLEDGE.md` and read only the YAML frontmatter of each file, in one turn.
 
-Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+**Step 2 — Pick relevant KBs:** select the entries whose documented area overlaps the current task (index line, or frontmatter `description` and `directories` on fallback).
 
-**Step 4 — Read each selected KB's Rules:**
+**Step 3 — Read each selected KB's Rules.** `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
-
-1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
-2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+1. List the `##` headings with line numbers of all selected KBs in one Bash call: `command grep -n '^## ' "{kb}" …`. With two or more paths, each line starts with its `{kb}:` path. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, all selected KBs in one turn, and choose the one to three bullets most relevant to the task.
 3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
 
-When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
-
-**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+When a KB contradicts the code you observe, **trust the code**.
 
-Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
+**Step 4 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES.** Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
 
 ```
 --- Feature knowledge: {slug} ---
@@ -122,14 +93,10 @@ Rules:
 Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 ```
 
-A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
-
-**One git call, then direct reads — no `.cjs` script.**
+A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
 Pass `FEATURE_KNOWLEDGE_RULES` to Harden agent.
 
-**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional), FEATURE_KNOWLEDGE_RULES (string, optional), HEAD_BEFORE (40-hex SHA)
-
 ### Phase 1: Polish agent (Code Refinement)
 
 **Produces:** POLISH_COMMITS
@@ -143,8 +110,6 @@ FILES_CHANGED: {files_changed}
 Polish and refine the code for clarity and consistency while preserving functionality.
 Commit any improvements with a conventional-commit message."
 
-**Wait for completion.** Polish agent commits changes directly.
-
 ### Phase 2: Harden agent (9-Pillar Quality Gate)
 
 **Produces:** HARDEN_STATUS
@@ -161,7 +126,7 @@ Evaluate against 9-pillar framework. Fix P0/P1 issues. Return structured report.
 Follow devflow:apply-decisions to scan DECISIONS_CONTEXT and Read full ADR/PF bodies on demand. Skip if (none).
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE. Skip if (none)."
 
-**Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED) from the `### Status` line
+Extract: STATUS (PASS|FIXED|BLOCKED) from the `### Status` line
 
 ### Phase 3: Conditional Validation
 
@@ -217,21 +182,18 @@ Display summary:
 
 **Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
 
-If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
-
-**Step 2 — Evaluate whether write-back is warranted:**
+If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The fail-closed line says `KNOWLEDGE=off` too.
 
-Only proceed if **at least one** of these is true:
+**Step 2 — Write back only if at least one is true:**
 - This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
-- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+- This workflow found durable, cross-cutting knowledge about a codebase area that future agents in that area need: patterns, anti-patterns, integration points, gotchas that a single file read does not show.
 
-**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+Otherwise skip write-back silently.
 
 **Step 3 — Spawn the Knowledge agent:**
 
-Spawn `Agent(subagent_type="Knowledge")` with the following context:
-
 ```
+Agent(subagent_type="Knowledge"):
 "WORKTREE_PATH: {worktree root}
 FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
@@ -252,45 +214,19 @@ Then commit the two files as your Commit Protocol directs."
 
 **Step 4 — Surface an uncommitted knowledge base:**
 
-When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files were written but deliberately not committed — a commit on a detached HEAD becomes unreachable once HEAD moves. Tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch before the worktree is removed. Never commit them yourself.
-
-**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
-
-## Architecture
-
-/self-review (orchestrator)
-│
-├─ Phase 0: Context gathering
-│  ├─ Git diff for changed files
-│  ├─ Record HEAD_BEFORE
-│  └─ Read index.md → DECISIONS_CONTEXT
-│
-├─ Phase 1: Polish agent
-│  └─ Code refinement (commits directly)
-│
-├─ Phase 2: Harden agent
-│  └─ 9-pillar quality gate (may fix and commit)
-│
-├─ Phase 3: Validate agent (conditional)
-│  └─ If HEAD moved: changed-only over HEAD_BEFORE..HEAD
-│
-└─ Phase 4: Report
-   └─ Display summary with pillar status
+When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch. Never commit them yourself.
+
+Non-blocking: if the Knowledge agent fails, log the failure and continue.
 
 ## Edge Cases
 
 | Case | Handling |
 |------|----------|
-| No changes | Report "No changes to review" and exit |
-| Polish agent finds nothing | Normal, continue to Harden agent |
 | Harden agent BLOCKED | Report blocking issue, halt workflow |
-| Validation fails | Report failures, halt |
-| Validate not PASS or FAIL | Report status and cause, halt |
 | Not in git repo | Report error, suggest running in git repo |
 
 ## Principles
 
 1. **Orchestration only** - Command spawns agents, doesn't do the work
-2. **Validation gate** - If Polish agent or Harden agent committed, the changes must pass validation
-3. **Honest reporting** - Display actual agent outputs
-4. **Fail fast** - Stop on BLOCKED or a Validate status other than PASS
+2. **Honest reporting** - Display actual agent outputs
+3. **Fail fast** - Stop on BLOCKED or a Validate status other than PASS

package/dist/compliance-off/agents/git.md

@@ -1,6 +1,6 @@
 ---
 name: Git
-description: Unified agent for all git/GitHub operations - issues, releases
+description: All git/GitHub operations - issues, releases
 model: haiku
 effort: medium
 skills:
@@ -12,15 +12,12 @@ omitClaudeMd: true
 
 # Git Agent
 
-You are the Git/GitHub operations specialist.
-
 ## Input
 
-The orchestrator provides:
 - **OPERATION**: Which task to perform
 - **Operation-specific parameters**: See the operation's `**Input:**` in its reference
 
-**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `devflow:worktree-support` skill for path resolution. If omitted, use cwd.
+**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `devflow:worktree-support` skill. If omitted, use cwd.
 
 **Degradation contract (D4):** Any operation that requires remote access (GitHub API, push, PR) MUST degrade gracefully:
 - No remote / the tracker unauthenticated or unreachable / no PR → emit `TRACEABILITY: DEGRADED ({reason})`, warn in output, and continue — never abort the caller's workflow.
@@ -65,25 +62,25 @@ A pipeline's exit status swallows a scrubber crash (fail-open). Chain with `&&`
 
 | Operation | Purpose |
 |-----------|---------|
-| `ensure-pr-ready` | Pre-flight: commit, push, open the PR |
-| `validate-branch` | Pre-flight for /resolve: check branch state |
-| `setup-task` | Create feature branch and optionally fetch/create issue |
-| `fetch-issue` | Fetch tracker issue for implementation |
-| `fetch-issues-batch` | Fetch multiple tracker issues for multi-issue planning |
-| `check-ci-status` | Check CI/PR check status for a branch |
+| `ensure-pr-ready` | Commit, push, open the PR |
+| `validate-branch` | Check branch state for /resolve |
+| `setup-task` | Create the branch; optionally fetch or create the issue |
+| `fetch-issue` | Fetch one tracker issue |
+| `fetch-issues-batch` | Fetch several tracker issues |
+| `check-ci-status` | Check the CI status of a branch |
 | `create-release` | Create GitHub release with version tag |
-| `gather-release-evidence` | Collect commits, shipped issues and a per-commit trace map since the last release (D4) |
-| `learn-conventions` | Bounded scan → write .devflow/conventions.md once (D1) |
-| `fetch-review-threads` | GraphQL reviewThreads, filter devflow-authored, return ext-* records (D2) |
-| `check-merge-readiness` | Report-only: unresolved threads + review decision + CI status (D6) |
-| `ensure-traceable-issue` | Create or enrich a tracker issue from the D3 template (D5) |
+| `gather-release-evidence` | Commits, shipped issues and trace map since the last release |
+| `learn-conventions` | Bounded scan, then write .devflow/conventions.md once |
+| `fetch-review-threads` | Return external review threads as ext-* records |
+| `check-merge-readiness` | Report-only: threads, review decision, CI status |
+| `ensure-traceable-issue` | Create or enrich a tracker issue |
 
 **Decision Marker Legend:**
 
 | Marker | Meaning |
 |--------|---------|
-| D4 | Degradation contract — every remote-dependent op degrades gracefully with `TRACEABILITY: DEGRADED ({reason})`, never aborting the caller's workflow |
-| D11 | Comment-sink scrub — unconditional secret redaction on every body-posting op; fail-closed (`TRACEABILITY: DEGRADED (redaction unavailable)`) on scrubber error or missing script |
+| D4 | Degradation contract (section above) |
+| D11 | Comment-sink scrub (section above) |
 
 D4 and D11 are defined here; every other `D{N}` label is defined in the `devflow:git` skill's `references/decision-markers.md`.
 

package/dist/compliance-off/agents/triage.md

@@ -1,6 +1,6 @@
 ---
 name: Triage
-description: Validates review issues against blast-radius disposition matrix. Assigns one verdict per issue. Never edits code.
+description: Assigns one blast-radius disposition verdict to each review issue. Never edits code.
 model: opus
 effort: high
 skills:
@@ -17,7 +17,7 @@ omitClaudeMd: true
 
 # Triage Agent
 
-You are an issue triage specialist. You validate every review issue and assign exactly one disposition from the blast-radius matrix. **You NEVER edit code, create commits, or run build commands.** Your role is judgment only.
+You validate every review issue and assign exactly one disposition from the blast-radius matrix. You judge only (see Boundaries).
 
 ## Input Context
 
@@ -33,11 +33,9 @@ You receive from orchestrator:
 
 ## Responsibilities
 
-1. **Read context per issue**: For each issue, Read 30 lines around the reported file:line to understand the actual code.
+1. **Read context per issue**: Read 30 lines around each reported file:line. Send the Reads of all issues in one message, with the Gate Level print at `standard` or `lean`, and the first evidence greps of all issues in one message; a grep that needs an earlier result follows it.
 2. **Apply Decisions**: Scan the DECISIONS_CONTEXT index to identify relevant ADR and PF entries. Read full bodies on demand. State each one that bears on a verdict in words in your Reasoning column, never by its ID — /resolve posts that column to the PR in its resolution summary. Skip when DECISIONS_CONTEXT is empty or `(none)`. Rely only on entries whose verbatim ID is in the index — do not fabricate.
 3. **Assign disposition**: Run the duplicate grouping pre-pass, then apply the blast-radius matrix to each group's primary. Every issue gets exactly one verdict (DUPLICATE included) — none may vanish.
-4. **Document evidence**: FALSE_POSITIVE requires cited grep/file:line. BY_DESIGN requires a recorded decision, stated in words, or an inline comment/doc citation.
-5. **Assign risk tier**: For every FIX_NOW issue, annotate Standard or Careful.
 
 ## Duplicate Grouping Pre-Pass
 
@@ -69,14 +67,14 @@ REQUIRES: an ADR whose body you have read, stated in words, or a comment/doc in
 - The affected file is in DIFF_FILES (touched in this branch)
 - The fix is isolated (Standard-risk) anywhere in the codebase
 - Security or correctness issue in any code path touched by this branch
-Annotate risk tier: **Standard** (isolated, low blast radius) or **Careful** (public API, shared state, >3 files, core logic, multi-service interface, auth flow).
+Annotate every FIX_NOW verdict, from any clause, Standard or Careful (Risk Tier Definitions).
 
 **4. FIX_SEPARATE** — valid but exceeds diff blast radius:
 - Unrelated files not in DIFF_FILES that require wide refactor
 - Public API changes unrelated to branch purpose
 - Branch is purpose-constrained (move-only refactor, release branch)
 
-**5. TECH_DEBT** — LAST RESORT: only for issues requiring complete architectural overhaul. "Touches many files" or "changes public API" are NOT reasons (those are FIX_NOW/Careful or FIX_SEPARATE). Use only when a fix requires complete system redesign or coordinated multi-service database migrations.
+**5. TECH_DEBT** — LAST RESORT: only when the fix requires complete system redesign or coordinated multi-service database migrations. "Touches many files" or "changes public API" are NOT reasons (those are FIX_NOW/Careful or FIX_SEPARATE).
 
 **Terminal catch-all (no clause matched):** Any valid issue that did not match clauses 3–5: assess blast radius — if the fix scope is contained within the branch's purpose, assign **FIX_NOW** at the appropriate risk tier (Standard or Careful); if the fix scope clearly exceeds the branch's purpose, assign **FIX_SEPARATE**.
 
@@ -92,7 +90,7 @@ Annotate risk tier: **Standard** (isolated, low blast radius) or **Careful** (pu
 - Adding tests or improving logging
 - Security fixes in isolated scope
 
-**Careful** (Code agent uses test-first protocol — understand → plan → test → implement → verify → commit):
+**Careful** (Code agent works test-first):
 - Public API or function signature changes
 - Shared state or data model modifications
 - Changes touching more than 3 files
@@ -168,12 +166,7 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 
 ## Boundaries
 
-**You are TRIAGE ONLY — read and judge, never write:**
-- Read files for 30-line context around each issue
-- Run grep/Read for FALSE_POSITIVE evidence
-- Read ADR/PF bodies through the decisions index
-
-**Never:**
+You read and judge, and never write. **Never:**
 - Edit any file
 - Run builds, tests, or lint
 - Create commits or branches

package/dist/compliance-off/commands/bug-analysis.md

@@ -1,10 +1,8 @@
 ---
-description: Proactive bug finding with static and semantic analysis — hunts real bugs in changed code before merge
+description: Proactive bug finding in changed code before merge, with static and semantic analysis
 ---
 # Bug Analysis Command
 
-Run a proactive bug analysis on the current branch: static analysis tools and parallel semantic analyzers, synthesized into one bug report.
-
 ## Usage
 
 `/bug-analysis [--full] [--no-static]`: `--full` ignores incremental state; `--no-static` skips static analysis.
@@ -21,17 +19,19 @@ Run a proactive bug analysis on the current branch: static analysis tools and pa
 node "$HOME/.devflow/scripts/resolve-evidence-policy.cjs" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name such as `main`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name. **Anything else** (including a script that cannot run) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
 
 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.
 
-**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
+**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path is `{worktree}/.devflow/docs/…`. A repo-relative docs path handed to an agent travels with a `WORKTREE_PATH` naming its checkout.
+
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-and using its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. Every docs path below is written `{worktree}/.devflow/docs/…`; a repo-relative docs path handed to an agent always travels with a `WORKTREE_PATH` naming the checkout it is relative to.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 When `EVIDENCE_POLICY` is `required`, record `TRACEABILITY: DEGRADED (compliance off on this machine; the repository requires evidence)` once, for the Phase 7 report.
 
 Spawn Git agent:
@@ -172,42 +172,33 @@ Set `STATIC_STATUS` to one `{tool}: {value}` per tool: `completed`, `not install
 
 #### Decisions Index
 
-**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root in a one-worktree run:
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for:
 
 ```bash
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (including a script that cannot run) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
 
 The accepted line is the only source of these values.
 
 ### Load DECISIONS_CONTEXT
 
-When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, reading no index.
+
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy.
 
-The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-Line 1 is the checkout's toplevel, line 2 the 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 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 curation hooks apply, so you read the index the Curate agent writes.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-**Step 1 — Read the pre-rendered index:**
+**Step 1 — Read the pre-rendered index** `{ledger}/.devflow/curation/index.md`. Its content is `DECISIONS_CONTEXT`; if it is absent or empty, `DECISIONS_CONTEXT` is `(none)`.
 
-Attempt to read `{ledger}/.devflow/curation/index.md`.
-
-- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
-- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
-
-The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+The index is one direct file read.
 
 **Step 2 — Slice the index, then hand it on:**
 
@@ -215,51 +206,33 @@ When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contr
 
 Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
 
-Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
-
 #### Feature Knowledge
 
 ### Load Feature Knowledge
 
-Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-**Step 1 — Read the index cache:**
+All paths below are relative to `{worktree}`.
 
-Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+**Step 1 — Read the index cache** `{worktree}/.devflow/features/index.md`. Each line has the form `- **{slug}** — {areas} — {Use-when description}`. If `index.md` is absent or has no entry line, glob `{worktree}/.devflow/features/*/KNOWLEDGE.md` and read only the YAML frontmatter of each file, in one turn.
 
-```
-- **{slug}** — {areas} — {Use-when description}
-```
+**Step 2 — Pick relevant KBs:** select the entries whose documented area overlaps the current task (index line, or frontmatter `description` and `directories` on fallback).
 
-If `index.md` exists and contains at least one entry line, use it for relevance matching.
+**Step 3 — Read each selected KB's Rules.** `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
-
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
-
-**Step 3 — Pick relevant KBs:**
-
-Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
-
-**Step 4 — Read each selected KB's Rules:**
-
-For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
-
-1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
-2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+1. List the `##` headings with line numbers of all selected KBs in one Bash call: `command grep -n '^## ' "{kb}" …`. With two or more paths, each line starts with its `{kb}:` path. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, all selected KBs in one turn, and choose the one to three bullets most relevant to the task.
 3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
 
-When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
-
-**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+When a KB contradicts the code you observe, **trust the code**.
 
-Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
+**Step 4 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES.** Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
 
 ```
 --- Feature knowledge: {slug} ---
@@ -270,9 +243,7 @@ Rules:
 Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 ```
 
-A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
-
-**One git call, then direct reads — no `.cjs` script.**
+A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
 #### Plan Artifact
 
@@ -300,9 +271,7 @@ Pick the focus analyzers from `CHANGED_FILES` (Step 2b; do not re-run `git diff`
 **Produces:** ANALYZER_OUTPUTS
 **Requires:** DIFF_RANGE, ANALYSIS_DIR, ACTIVE_FOCUSES, STATIC_FINDINGS, ACCEPTANCE_RULES, PLAN_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 
-Spawn ALL active Debug agents **in a single message** (parallel, NOT background):
-
-For each active focus, spawn:
+Spawn one Debug agent for each active focus, all in a single message (parallel, not background):
 ```
 Agent(subagent_type="Debug", run_in_background=false):
 "Analyze focusing on {focus}.
@@ -381,7 +350,7 @@ Seven phases: Phase 1 to Phase 7.
 |------|----------|
 | Rebase invalidates `.last-analysis-head` SHA | `git cat-file -t` check fails → fallback to full diff |
 | Zero changed files in DIFF_RANGE with exit 0 | Stop: "No changes to analyze." |
-| `--full` flag | Bypass incremental detection (Step 2a), run full diff from base |
+| `--full` flag | Step 2a takes the full-range path |
 | A scanner did not run or did not complete | Name the tool and why in `STATIC_FINDINGS`, not `(none)`; a tool that did not complete keeps the marker |
 
 ## Resolve Compatibility