devflow-kit 3.10.0 → 3.12.0

package/dist/core/plugins.js

@@ -86,7 +86,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-plan',
         description: 'Unified design planning with gap analysis and design review',
         commands: ['/plan'],
-        agents: ['git', 'skim', 'synthesize', 'design', 'explore'],
+        agents: ['git', 'skim', 'synthesize', 'design', 'architect', 'explore'],
         skills: ['gap-analysis', 'design-review', 'patterns', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
         // D-CHARTER-BOUNDED-INLINE: /plan's main thread orchestrates and loads no
         // companion skills, so `requires:` lists only skills this plugin's command,
@@ -275,7 +275,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-ambient',
         description: 'Orchestrator ambient mode — session charter, per-prompt reminder, plan handoff',
         commands: [],
-        agents: ['code', 'refactor', 'validate', 'polish', 'harden', 'evaluate', 'test', 'skim', 'review', 'git', 'synthesize', 'triage', 'design', 'knowledge', 'research', 'curate', 'explore'],
+        agents: ['code', 'refactor', 'validate', 'polish', 'harden', 'evaluate', 'test', 'skim', 'review', 'git', 'synthesize', 'triage', 'design', 'architect', 'knowledge', 'research', 'curate', 'explore'],
         skills: [
             'review-methodology',
             'security',
@@ -316,7 +316,7 @@ export const DEVFLOW_PLUGINS = [
         description: 'Dynamic workflow recipes - dependency-aware tickets→plan→build delivery pipeline',
         // Commands compiled from commands/*.mds at build time (build:mds).
         commands: ['/dynamic-tickets', '/dynamic-plan', '/dynamic-build', '/dynamic-profile'],
-        agents: ['code', 'fix', 'validate', 'polish', 'harden', 'evaluate', 'test', 'review', 'git', 'synthesize', 'knowledge', 'design'],
+        agents: ['code', 'fix', 'validate', 'polish', 'harden', 'evaluate', 'test', 'review', 'git', 'synthesize', 'knowledge', 'design', 'architect'],
         skills: ['apply-decisions', 'apply-feature-knowledge', 'worktree-support', 'docs-framework'],
         requires: [
             'architecture',
@@ -640,11 +640,12 @@ export function parsePluginSelection(input, validPlugins) {
 /**
  * Deprecated command names from old installations.
  * Used during init to clean up stale command files on upgrade.
+ *
+ * Each name is a command file that a release installed. The cleanup removes such a file with no
+ * backup, so a name that no release shipped does not belong here.
  */
 export const LEGACY_COMMAND_NAMES = [
-    'review',
     'specify',
-    'specify-teams',
 ];
 /** A command entry of a plugin without its leading `/`. */
 function commandName(cmd) {

package/dist/core/reference-sweep.js

@@ -14,7 +14,9 @@ import * as path from 'path';
  * two providers may legitimately both carry a `comment.md`, so the registry name has to
  * be the relative PATH, and the walk has to descend.
  *
- * Never writes, only removes — no delete-then-write window.
+ * Never writes. The sweep names what stays and what goes; a {@link ReferenceSweepDelegate}
+ * acts on every entry the manifest does not name, and the sweep itself never removes a
+ * folder recursively. No delete-then-write window.
  */
 /**
  * Descent bound for every walk over the generated reference tree — this sweep and the
@@ -42,24 +44,27 @@ export const MAX_REFERENCE_SWEEP_DEPTH = 8;
  * @param root - Directory to converge (the installed `references/tracker/` tree).
  * @param knownRelPaths - POSIX paths relative to `root` that must survive. Derived from
  *   the build's own module registries by the caller — never hand-listed.
+ * @param delegate - Acts on every entry the manifest does not name. Required: a sweep with
+ *   no delegate would have to delete what it cannot name.
  *
  * @returns A {@link SweepResult} whose `removed` entries are POSIX relative paths. A
- *   directory into which no manifest path descends is removed WHOLE and reported by its
- *   own relative path — leaving it empty would be a convergence that stops one step
- *   short, and an empty provider directory is indistinguishable from a provider whose
- *   references failed to install. A subtree left unswept because it breached
+ *   directory into which no manifest path descends is handed to the delegate WHOLE and
+ *   reported by its own relative path once the delegate removed it — leaving it empty
+ *   would be a convergence that stops one step short, and an empty provider directory is
+ *   indistinguishable from a provider whose references failed to install. A subtree left
+ *   unswept because it breached
  *   {@link MAX_REFERENCE_SWEEP_DEPTH} is reported in `failed` under its own relative
  *   path, for the same reason: everything this sweep did not converge is named.
  *
  * A missing or unreadable `root` is a no-op, not an error: the overlay creates the tree
  * it converges, so an absent one simply means there is nothing to prune yet.
  */
-export async function sweepOrphanedReferences(root, knownRelPaths) {
+export async function sweepOrphanedReferences(root, knownRelPaths, delegate) {
     const acc = { scanned: 0, removed: [], failed: [] };
-    await sweepDirectory(root, '', 0, knownRelPaths, directoryPrefixes(knownRelPaths), acc);
+    await sweepDirectory(root, '', 0, knownRelPaths, directoryPrefixes(knownRelPaths), delegate, acc);
     return { scanned: acc.scanned, removed: acc.removed, failed: acc.failed };
 }
-async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc) {
+async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, delegate, acc) {
     if (depth > MAX_REFERENCE_SWEEP_DEPTH) {
         // A breached bound means this subtree is never visited, so any orphan inside it
         // survives. Report it through the same channel as a failed removal: a silent return
@@ -82,35 +87,47 @@ async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc)
         const relPath = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
         const fullPath = path.join(dir, entry.name);
         // A real subdirectory is either an ancestor of something the manifest names — in
-        // which case descend — or dead weight, in which case take the whole subtree.
-        // isDirectory() is false for a symlink-to-dir, so a planted link is treated as a
-        // leaf and removed rather than followed.
+        // which case descend — or dead weight, in which case the delegate takes the whole
+        // subtree. isDirectory() is false for a symlink-to-dir, so a planted link is treated
+        // as a leaf and handed over rather than followed.
         if (entry.isDirectory()) {
             if (knownDirPrefixes.has(`${relPath}/`)) {
-                await sweepDirectory(fullPath, relPath, depth + 1, known, knownDirPrefixes, acc);
+                await sweepDirectory(fullPath, relPath, depth + 1, known, knownDirPrefixes, delegate, acc);
                 continue;
             }
             acc.scanned++;
-            try {
-                await fs.rm(fullPath, { recursive: true, force: true });
-                acc.removed.push(relPath);
-            }
-            catch (err) {
-                acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
-            }
+            await dispose(fullPath, relPath, true, delegate, acc);
             continue;
         }
         acc.scanned++;
         if (known.has(relPath))
             continue;
-        try {
-            await fs.rm(fullPath, { force: true });
-            acc.removed.push(relPath);
-        }
-        catch (err) {
-            acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
+        await dispose(fullPath, relPath, false, delegate, acc);
+    }
+}
+/** Hand one entry to the delegate and record the outcome; a throw from the delegate is a per-item failure. */
+async function dispose(fullPath, relPath, isDirectory, delegate, acc) {
+    try {
+        const disposition = await delegate.dispose(fullPath, isDirectory);
+        switch (disposition.outcome) {
+            case 'removed':
+                acc.removed.push(relPath);
+                break;
+            case 'failed':
+                acc.failed.push({ name: relPath, error: disposition.error });
+                break;
+            case 'moved':
+            case 'kept':
+                break;
+            default: {
+                const _exhaustive = disposition;
+                void _exhaustive;
+            }
         }
     }
+    catch (err) {
+        acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
+    }
 }
 /**
  * Every directory prefix some manifest path sits under, trailing slash included:

package/dist/core/retired-shipped-names.js

@@ -0,0 +1,278 @@
+import { createPathSet } from './path-set.js';
+const names = (list) => Object.freeze([...list]);
+export const RETIRED_SHIPPED = Object.freeze({
+    commands: names([
+        'ambient',
+        'audit-claude',
+        'brainstorm',
+        'breakdown',
+        'catch-up',
+        'commit',
+        'design',
+        'devlog',
+        'get-issue',
+        'plan-next-steps',
+        'pre-commit',
+        'pre-pr',
+        'pull-request',
+        'resolve-comments',
+        'specify',
+    ]),
+    agents: names([
+        'audit-architecture',
+        'audit-complexity',
+        'audit-database',
+        'audit-dependencies',
+        'audit-documentation',
+        'audit-performance',
+        'audit-security',
+        'audit-tests',
+        'audit-typescript',
+        'brainstorm',
+        'catch-up',
+        'claude-md-auditor',
+        'code-edit',
+        'code-fix',
+        'code-review',
+        'coder',
+        'commit',
+        'diagnose',
+        'get-issue',
+        'learning',
+        'pr-comments',
+        'project-state',
+        'pull-request',
+        'release',
+        'resolver',
+        'reviewer',
+        'scrutinize',
+        'scrutinizer',
+        'shepherd',
+        'simplifier',
+        'simplify',
+        'skimmer',
+        'synthesizer',
+        'tech-debt',
+        'validator',
+    ]),
+    rules: names([]),
+    skills: names([
+        'accessibility',
+        'agent-teams',
+        'ambient-router',
+        'apply-feature-kb',
+        'apply-knowledge',
+        'architecture-patterns',
+        'code-smell',
+        'codebase-navigation',
+        'commit',
+        'complexity-patterns',
+        'consistency-patterns',
+        'core-patterns',
+        'database-patterns',
+        'debug',
+        'debug-orchestration',
+        'debug:guided',
+        'debug:orch',
+        'debug:triage',
+        'decisions-format',
+        'dependencies-patterns',
+        'devflow',
+        'devflow-accessibility',
+        'devflow-agent-teams',
+        'devflow-architecture-patterns',
+        'devflow-code-smell',
+        'devflow-codebase-navigation',
+        'devflow-commit',
+        'devflow-complexity-patterns',
+        'devflow-consistency-patterns',
+        'devflow-core-patterns',
+        'devflow-database-patterns',
+        'devflow-debug',
+        'devflow-dependencies-patterns',
+        'devflow-docs-framework',
+        'devflow-documentation-patterns',
+        'devflow-error-handling',
+        'devflow-frontend-design',
+        'devflow-git-safety',
+        'devflow-git-workflow',
+        'devflow-github-patterns',
+        'devflow-implementation-patterns',
+        'devflow-input-validation',
+        'devflow-pattern-check',
+        'devflow-performance-patterns',
+        'devflow-pull-request',
+        'devflow-react',
+        'devflow-regression-patterns',
+        'devflow-review-methodology',
+        'devflow-security-patterns',
+        'devflow-self-review',
+        'devflow-test-design',
+        'devflow-tests-patterns',
+        'devflow-typescript',
+        'devflow:agent-teams',
+        'devflow:ambient-router',
+        'devflow:apply-feature-kb',
+        'devflow:apply-knowledge',
+        'devflow:architecture-patterns',
+        'devflow:complexity-patterns',
+        'devflow:consistency-patterns',
+        'devflow:core-patterns',
+        'devflow:database-patterns',
+        'devflow:debug',
+        'devflow:debug-orchestration',
+        'devflow:debug:guided',
+        'devflow:debug:orch',
+        'devflow:debug:triage',
+        'devflow:dependencies-patterns',
+        'devflow:documentation-patterns',
+        'devflow:dream-curation',
+        'devflow:dream-decisions',
+        'devflow:dream-knowledge',
+        'devflow:dream-memory',
+        'devflow:explore',
+        'devflow:explore:guided',
+        'devflow:explore:orch',
+        'devflow:explore:triage',
+        'devflow:feature-kb',
+        'devflow:frontend-design',
+        'devflow:git-safety',
+        'devflow:git-workflow',
+        'devflow:github-patterns',
+        'devflow:implement',
+        'devflow:implement:guided',
+        'devflow:implement:orch',
+        'devflow:implement:triage',
+        'devflow:implementation-orchestration',
+        'devflow:implementation-patterns',
+        'devflow:input-validation',
+        'devflow:knowledge-persistence',
+        'devflow:performance-patterns',
+        'devflow:pipeline',
+        'devflow:pipeline-orchestration',
+        'devflow:pipeline:orch',
+        'devflow:plan',
+        'devflow:plan-orchestration',
+        'devflow:plan:guided',
+        'devflow:plan:orch',
+        'devflow:plan:triage',
+        'devflow:regression-patterns',
+        'devflow:release:guided',
+        'devflow:release:orch',
+        'devflow:release:triage',
+        'devflow:research',
+        'devflow:research:guided',
+        'devflow:research:orch',
+        'devflow:research:triage',
+        'devflow:resolve',
+        'devflow:resolve-orchestration',
+        'devflow:resolve:orch',
+        'devflow:review',
+        'devflow:review-orchestration',
+        'devflow:review:guided',
+        'devflow:review:orch',
+        'devflow:review:triage',
+        'devflow:router',
+        'devflow:search-first',
+        'devflow:security-patterns',
+        'devflow:self-review',
+        'devflow:sidecar',
+        'devflow:test-patterns',
+        'docs-framework',
+        'documentation-patterns',
+        'dream-curation',
+        'dream-decisions',
+        'dream-knowledge',
+        'dream-memory',
+        'error-handling',
+        'explore',
+        'explore:guided',
+        'explore:orch',
+        'explore:triage',
+        'feature-kb',
+        'frontend-design',
+        'git-safety',
+        'git-workflow',
+        'github-patterns',
+        'go',
+        'implement',
+        'implement:guided',
+        'implement:orch',
+        'implement:triage',
+        'implementation-orchestration',
+        'implementation-patterns',
+        'input-validation',
+        'java',
+        'knowledge-persistence',
+        'pattern-check',
+        'performance-patterns',
+        'pipeline',
+        'pipeline-orchestration',
+        'pipeline:orch',
+        'plan',
+        'plan-orchestration',
+        'plan:guided',
+        'plan:orch',
+        'plan:triage',
+        'pull-request',
+        'python',
+        'react',
+        'regression-patterns',
+        'release:guided',
+        'release:orch',
+        'release:triage',
+        'research',
+        'research:guided',
+        'research:orch',
+        'research:triage',
+        'resolve',
+        'resolve-orchestration',
+        'resolve:orch',
+        'review',
+        'review-methodology',
+        'review-orchestration',
+        'review:guided',
+        'review:orch',
+        'review:triage',
+        'router',
+        'rust',
+        'search-first',
+        'security-patterns',
+        'self-review',
+        'sidecar',
+        'test-design',
+        'test-driven-development',
+        'test-patterns',
+        'tests-patterns',
+        'typescript',
+        'worktree-support',
+    ]),
+    skillFiles: Object.freeze({
+        'devflow:agent-references': names([
+            'references/learning/maintain.md',
+        ]),
+        'devflow:git': names([
+            'references/pr/ensure-pr-ready.md',
+        ]),
+    }),
+});
+/**
+ * The files of {@link RETIRED_SHIPPED} as paths relative to the Claude dir: the command, agent and
+ * rule files, and the listed files of a skill folder. A skill folder of `skills` is not a path
+ * here, since the install moves it whole.
+ */
+export function retiredPathSet() {
+    const paths = [];
+    for (const name of RETIRED_SHIPPED.commands)
+        paths.push(`commands/devflow/${name}.md`);
+    for (const name of RETIRED_SHIPPED.agents)
+        paths.push(`agents/devflow/${name}.md`);
+    for (const name of RETIRED_SHIPPED.rules)
+        paths.push(`rules/devflow/${name}.md`);
+    for (const [skill, files] of Object.entries(RETIRED_SHIPPED.skillFiles)) {
+        for (const file of files)
+            paths.push(`skills/${skill}/${file}`);
+    }
+    return createPathSet(paths);
+}
+//# sourceMappingURL=retired-shipped-names.js.map

package/dist/curation-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:
@@ -16,7 +16,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
 
@@ -31,10 +31,8 @@ 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. **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.
-3. **Document evidence**: FALSE_POSITIVE requires cited grep/file:line. BY_DESIGN requires a recorded decision, stated in words, or an inline comment/doc citation.
-4. **Assign risk tier**: For every FIX_NOW issue, annotate Standard or Careful.
 
 ## Duplicate Grouping Pre-Pass
 
@@ -66,14 +64,14 @@ REQUIRES: a comment/doc in the code itself that explicitly documents the intent.
 - 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**.
 
@@ -89,7 +87,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
@@ -165,11 +163,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
-
-**Never:**
+You read and judge, and never write. **Never:**
 - Edit any file
 - Run builds, tests, or lint
 - Create commits or branches

package/dist/curation-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:
@@ -174,45 +174,29 @@ Set `STATIC_STATUS` to one `{tool}: {value}` per tool: `completed`, `not install
 
 ### 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}`.
-
-**Step 1 — Read the index cache:**
-
-Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
-
-```
-- **{slug}** — {areas} — {Use-when description}
-```
+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 `index.md` exists and contains at least one entry line, use it for relevance matching.
+All paths below are relative to `{worktree}`.
 
-**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+**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.
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
+**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 3 — Pick relevant KBs:**
+**Step 3 — Read each selected KB's Rules.** `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-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.
+When a KB contradicts the code you observe, **trust the code**.
 
-**Step 5 — 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.
+**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} ---
@@ -223,9 +207,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
 
@@ -253,9 +235,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, 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}.
@@ -332,7 +312,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