devflow-kit 3.4.0 → 3.6.0

package/dist/cli/commands/uninstall.js

@@ -7,7 +7,7 @@ import color from 'picocolors';
 import { getInstallationPaths, getClaudeDirectory, getHomeDirectory, getManagedSettingsPath } from '../../targets/claude-code/claude-paths.js';
 import { getGitRoot } from '../../core/git.js';
 import { isSameLocation } from '../../core/same-location.js';
-import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, buildAssetMaps, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
 import { readManifest, removeManifestPlugins } from '../../core/manifest.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
 import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
@@ -20,7 +20,7 @@ import { removeContextHook } from './context.js';
 import { applyProxyTeardownToSettings } from './proxy.js';
 import { readProxyState, proxyJsonExists } from '../../core/proxy-state.js';
 import { hudCacheDir } from '../../core/cache.js';
-import { TRACKER_ATTEMPTS_NAMES, TRACKER_CLAIM_FILE, TRACKER_CONVENTIONS_DIR, TRACKER_ENABLED_FILE, TRACKER_LEGACY_ATTEMPTS_FILE, TRACKER_LEGACY_CONVENTIONS_FILE, TRACKER_PROVIDER_IDS, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
+import { effectiveTrackerServers, TRACKER_ATTEMPTS_NAMES, TRACKER_CLAIM_FILE, TRACKER_CONVENTIONS_DIR, TRACKER_ENABLED_FILE, TRACKER_LEGACY_ATTEMPTS_FILE, TRACKER_LEGACY_CONVENTIONS_FILE, TRACKER_PROVIDER_IDS, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
 import { CLAUDE_MD_AUDIT_STAMP_FILE, CLAUDE_MD_AUDIT_STAMP_TMP_PREFIX } from '../../core/claude-md-audit.js';
 import { revertExternalAgents } from '../../core/agent-models.js';
 import { detectShell, getProfilePath } from '../../core/safe-delete.js';
@@ -32,6 +32,7 @@ import { stripDevflowTeammateModeFromJson } from '../../core/teammate-mode-clean
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
 import { restampInstalledCommands } from '../../targets/claude-code/language-stamp.js';
+import { installCommandsAndAgents } from '../../targets/claude-code/installer.js';
 /**
  * Where a retired repo-local install lives: `<gitRoot>/.claude` and `<gitRoot>/.devflow`.
  *
@@ -488,7 +489,7 @@ export function userContentPaths(devflowDir) {
             const name = `${TRACKER_LEGACY_CONVENTIONS_FILE}.${id}.bak`;
             return { relPath: name, label: `${name} (previous issue tracker conventions)` };
         }),
-        // learning.json — global learning agent tuning config
+        // learning.json — global curate agent tuning config
         { relPath: 'learning.json', label: 'learning.json' },
         // hud.json — user HUD enable/disable preference and display config
         { relPath: 'hud.json', label: 'hud.json (HUD configuration)' },
@@ -885,6 +886,89 @@ export async function runDryRunPhase(opts) {
         }
     }
 }
+/**
+ * After a selective uninstall removed a retired agent file, write the current commands
+ * and agents of the plugins that stay installed.
+ *
+ * A retired agent file only exists on a machine that ran an older release. That
+ * release's commands, for the plugins that stay, still spawn the retired name, and the
+ * agents that replaced it are not installed. Removing the file without this step would
+ * leave those plugins unable to spawn their agents until the next full `devflow init`.
+ *
+ * Writes only commands and agents, through the same copy path `devflow init` uses
+ * ({@link installCommandsAndAgents}). It does not touch the hooks, the scripts or
+ * settings.json, so the notice tells the user to run `devflow init` for those.
+ *
+ * Never runs in a legacy local scope (D-CLI-NO-SYMLINK): a repository can commit a command
+ * file as a symbolic link, and the copy writes through it. The folder guard below does not
+ * check files. `devflow init` can not update a legacy local install either, so the warning
+ * tells the user to remove it in full.
+ *
+ * Skipped, with a warning, when there is no readable manifest or it lists no known plugin (the
+ * retained set would be a guess), or when a folder is behind a link the caller's guard
+ * refuses. Those warnings name `devflow init` as the remedy. When the copy fails, it stops
+ * at the first failure: files it wrote before then stay, and the warning names the same
+ * remedy. Never throws: an uninstall must finish.
+ * Agent model lines are reverted again after the copy, as the selective phase does before
+ * its removal, so a freshly written agent carries no external-model line. Like the
+ * selective phase, it prints the warnings of that revert only with `verbose`.
+ */
+export async function refreshRetainedCommandsAndAgents(opts) {
+    const { claudeDir, devflowDir, retained, retiredAgents } = opts;
+    const scope = opts.scope ?? 'user';
+    const verbose = opts.verbose ?? false;
+    const mayChange = opts.mayChange ?? changeAnything;
+    const agentsDir = path.join(claudeDir, 'agents', 'devflow');
+    const commandsDir = path.join(claudeDir, 'commands', 'devflow');
+    const retired = `Removed the agent file(s) of an older Devflow release: ${retiredAgents.join(', ')}.`;
+    const remedy = 'Run `devflow init` to update the commands, agents, hooks and scripts of the plugins that stay installed.';
+    if (retained.length === 0)
+        return;
+    if (scope === 'local') {
+        p.log.warn(`${retired} Devflow does not rewrite files in a legacy local install, so the remaining commands can still name the removed agents. Remove the legacy local install in full with \`devflow uninstall --scope local\`.`);
+        return;
+    }
+    // readManifest returns null for a missing file and for one it can not parse or validate.
+    const manifest = await readManifest(devflowDir).catch(() => null);
+    if (manifest === null) {
+        p.log.warn(`${retired} There is no readable manifest, so Devflow did not rewrite the remaining files. ${remedy}`);
+        return;
+    }
+    if (manifest.plugins.length === 0) {
+        p.log.warn(`${retired} The manifest lists no plugins, so Devflow did not rewrite the remaining files. ${remedy}`);
+        return;
+    }
+    // resolveInstalledPlugins falls back to the whole registry when no manifest name resolves, so
+    // the retained set would hold plugins that were never installed.
+    if (!manifest.plugins.some(name => DEVFLOW_PLUGINS.some(plugin => plugin.name === name))) {
+        p.log.warn(`${retired} The manifest lists no known plugin, so Devflow did not rewrite the remaining files. ${remedy}`);
+        return;
+    }
+    if (!(await mayChange(agentsDir)) || !(await mayChange(commandsDir))) {
+        p.log.warn(`${retired} A linked folder blocks the rewrite. ${remedy}`);
+        return;
+    }
+    try {
+        await installCommandsAndAgents({
+            plugins: retained,
+            agentsMap: buildAssetMaps(retained).agentsMap,
+            claudeDir,
+            learning: manifest.features.learning,
+            trackerServers: effectiveTrackerServers(manifest.features.tracker),
+            warn: (msg) => p.log.warn(msg),
+        });
+    }
+    catch (err) {
+        p.log.warn(`${retired} Devflow could not write the current commands and agents (${err instanceof Error ? err.message : String(err)}). ${remedy}`);
+        return;
+    }
+    try {
+        await revertExternalAgents({ installDir: agentsDir, devflowDir, onWarning: (msg) => { if (verbose)
+                p.log.warn(msg); } });
+    }
+    catch { /* the revert is best effort, as in the selective phase */ }
+    p.log.info(`${retired} Devflow wrote the current commands and agents of the plugins that stay installed. Run \`devflow init\` to update the hooks and scripts.`);
+}
 /**
  * SELECTIVE PHASE (per scope): revert agent model overrides, remove the
  * selected plugins' assets, and clean up the ambient hook if the ambient
@@ -919,7 +1003,23 @@ export async function runSelectivePhaseForScope(opts) {
         }
         catch { /* agents dir absent or revert failed — non-fatal */ }
     }
-    await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, mayChange);
+    const sweeps = await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, mayChange);
+    // A retired agent file means the install is from an older release, and the commands of the
+    // plugins that stay installed still spawn the name that was just removed. Write their
+    // current commands and agents so the install stays whole. Runs before the language stamp
+    // below, which then restamps the command this wrote.
+    if (sweeps.agents.removed.length > 0) {
+        const removed = new Set(selectedPlugins.map(sp => sp.name));
+        await refreshRetainedCommandsAndAgents({
+            claudeDir,
+            devflowDir,
+            retained: installedPlugins.filter(plugin => !removed.has(plugin.name)),
+            retiredAgents: sweeps.agents.removed,
+            scope,
+            verbose,
+            mayChange,
+        });
+    }
     // D-LANGUAGE-FOCUS-STAMP: re-stamp the installed /code-review from the selection that REMAINS.
     // A language plugin owns a skill and no command, so removing it deletes the skill while its
     // name would stay on the stamped line, and /code-review would spawn a focus whose skill is gone.
@@ -1627,6 +1727,9 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, ma
  * A folder `mayChange` refuses is not swept at all (D-CLI-NO-SYMLINK,
  * legacyLocalChangeGuard). An entry in a swept folder that is itself a link is
  * only unlinked: `fs.rm` never follows the link it is given.
+ *
+ * Returns what each sweep removed and failed to remove, so a caller can tell that
+ * a retired agent was removed (see {@link refreshRetainedCommandsAndAgents}).
  */
 export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = changeAnything) {
     const agentsDir = path.join(claudeDir, 'agents', 'devflow');
@@ -1656,6 +1759,7 @@ export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = cha
             p.log.warn(`Could not remove orphaned ${kind} "${failure.name}" (${reason}) — remove it manually`);
         }
     }
+    return { agents: agentsSweep, commands: commandsSweep, skills: skillsSweep };
 }
 /**
  * Remove only specific plugin assets (selective uninstall).
@@ -1665,6 +1769,8 @@ export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = cha
  * For skills: only remove skills that are NOT used by any remaining plugin.
  * Each removal passes `mayChange` first, which skips one a symbolic link would
  * redirect in a legacy local install (D-CLI-NO-SYMLINK, legacyLocalChangeGuard).
+ *
+ * Returns what the closing registry-diff sweep removed.
  */
 export async function removeSelectedPlugins(claudeDir, plugins, verbose, installedPlugins = DEVFLOW_PLUGINS, mayChange = changeAnything) {
     const { skills, agents, commands, rules } = computeAssetsToRemove(plugins, installedPlugins);
@@ -1734,6 +1840,6 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
     // Removes any orphaned files whose names left the registry (retired, renamed,
     // or deleted from all plugins). Spans ALL plugins so assets belonging to
     // non-selected plugins are never swept.
-    await sweepDevflowNamespaces(claudeDir, verbose, mayChange);
+    return sweepDevflowNamespaces(claudeDir, verbose, mayChange);
 }
 //# sourceMappingURL=uninstall.js.map

package/dist/cli.js

@@ -19,6 +19,7 @@ import { safeDeleteCommand } from './cli/commands/safe-delete.js';
 import { proxyCommand } from './cli/commands/proxy.js';
 import { agentsCommand } from './cli/commands/agents.js';
 import { complianceCommand } from './cli/commands/compliance.js';
+import { behaviorCommand } from './cli/commands/behavior.js';
 import { trackerCommand } from './cli/commands/tracker.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -48,6 +49,7 @@ program.addCommand(safeDeleteCommand);
 program.addCommand(proxyCommand);
 program.addCommand(agentsCommand);
 program.addCommand(complianceCommand);
+program.addCommand(behaviorCommand);
 program.addCommand(trackerCommand);
 // Handle no command (bare `devflow`) or unknown subcommand.
 // When Commander sees an unrecognised first argument it does not route to any

package/dist/commands/bug-analysis.md

@@ -38,7 +38,7 @@ git -C "{start}" rev-parse --show-toplevel
 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.
 
 Render the test-plan block from `/implement`'s evidence file, and from nothing else:
-1. `branch_slug` is `git branch --show-current` with every `/` replaced by `-`.
+1. `branch_slug` is `git -C "{worktree}" branch --show-current` with every `/` replaced by `-`.
 2. Only when `branch_slug` matches `^[A-Za-z0-9._-]{1,200}$` and the file exists, run (the path double-quoted):
 
 ```bash
@@ -195,19 +195,19 @@ The accepted line is the only source of these values: the script alone folds the
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-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`):
+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`):
 
 ```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:
+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 learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
 
 **Step 1 — Read the pre-rendered index:**
 
@@ -216,11 +216,15 @@ Attempt to read `{ledger}/.devflow/learning/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` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Slice the index, then hand it on:**
 
-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.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
+
+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
 
@@ -246,7 +250,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **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). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+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:**
 
@@ -277,12 +281,12 @@ 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.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
 #### Plan Artifact
 
-1. List `{worktree}/.devflow/docs/design/*.md` — sort descending by filename (timestamps are naturally sortable), scan the 10 most recent
-2. Read the most recent file if it exists
+1. List the design plans: `{worktree}/.devflow/docs/design/*.md` (a `/plan` artifact) and `{worktree}/.devflow/docs/design/*/*/*-plan.md` (a `/dynamic-plan` per-ticket plan). Sort by timestamp, newest first, and scan the 10 most recent. A `/plan` artifact's timestamp is the `YYYY-MM-DD_HHMM` before its `.md`; a per-ticket plan's is the name of its parent directory. Never sort by file name, which starts with an issue ID or a ticket slug. A per-ticket plan counts only when its `{ticket-slug}` (its file name without `-plan.md`) appears in the worktree's branch name
+2. Read the most recent file that carries an `## Acceptance Criteria` section
 3. Extract `## Acceptance Criteria` section → parse into table: `| ID | Criterion | Type | Testable Condition |`
 4. Set `PLAN_CONTEXT` to plan summary; `ACCEPTANCE_RULES` to the table
 5. If no plan files exist or section not found: `PLAN_CONTEXT=(none)`, `ACCEPTANCE_RULES=(none)`
@@ -306,11 +310,11 @@ Determine which focus analyzers to run using `CHANGED_FILES` (already computed i
 **Produces:** ANALYZER_OUTPUTS
 **Requires:** DIFF_RANGE, ANALYSIS_DIR, ACTIVE_FOCUSES, STATIC_FINDINGS, ACCEPTANCE_RULES, PLAN_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 
-Spawn ALL active Diagnose agents **in a single message** (parallel, NOT background):
+Spawn ALL active Debug agents **in a single message** (parallel, NOT background):
 
 For each active focus, spawn:
 ```
-Agent(subagent_type="Diagnose", run_in_background=false):
+Agent(subagent_type="Debug", run_in_background=false):
 "Analyze focusing on {focus}.
 FOCUS: {focus}
 DIFF_COMMAND: git diff {DIFF_RANGE}
@@ -408,10 +412,10 @@ Run `/resolve` to process and fix these findings.
 │  └─ Detect active focuses (security + functional always; integration + usability conditional)
 │
 ├─ Phase 5: Bug Analysis (PARALLEL)
-│  ├─ Diagnose agent: security (+ STATIC_FINDINGS)
-│  ├─ Diagnose agent: functional
-│  ├─ Diagnose agent: integration (conditional)
-│  └─ Diagnose agent: usability (conditional)
+│  ├─ Debug agent: security (+ STATIC_FINDINGS)
+│  ├─ Debug agent: functional
+│  ├─ Debug agent: integration (conditional)
+│  └─ Debug agent: usability (conditional)
 │
 ├─ Phase 6: Synthesis
 │  └─ Synthesize agent (mode: bug-analysis)
@@ -448,7 +452,7 @@ Run `/resolve` after `/bug-analysis` to fix identified bugs. `/resolve` automati
 2. **Parallel, not background** — Analyzers spawn in one message with `run_in_background=false`
 3. **Static + semantic** — Two complementary tracks, each validates the other
 4. **Incremental by default** — Only analyze new changes unless `--full` specified
-5. **Verify before reporting** — Diagnose agents self-verify every finding
+5. **Verify before reporting** — Debug agents self-verify every finding
 6. **Honest reporting** — Display risk level and counts directly from synthesis
 
 ## Phase Completion Checklist

package/dist/commands/code-review.md

@@ -22,9 +22,10 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 **Produces:** WORKTREES
 
-1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
-   - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
-   - Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill
+1. **Discover reviewable worktrees**:
+   - Run `git worktree list --porcelain` and count the worktrees it lists
+   - **More than one listed:** Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill. Parse the list, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - **Exactly one listed:** load neither the skill nor the reference — that worktree is the only candidate, and Step 0c's Git agent validates its branch
 2. **If `--path` flag provided:** use only that worktree, skip discovery
    **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
 3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
@@ -71,9 +72,9 @@ Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AU
 **Requires:** WORKTREES
 
 Discover PR description guidance from plan artifact (per worktree):
-1. List `{worktree}/.devflow/docs/design/*.md` files
-2. Sort by timestamp in filename (descending -- timestamps are YYYY-MM-DD_HHMM, naturally sortable)
-3. Read the most recent file, extract `## PR Description Guidance` section
+1. List the design plans: `{worktree}/.devflow/docs/design/*.md` (a `/plan` artifact) and `{worktree}/.devflow/docs/design/*/*/*-plan.md` (a `/dynamic-plan` per-ticket plan)
+2. Sort by timestamp, newest first, and scan the 10 most recent. A `/plan` artifact's timestamp is the `YYYY-MM-DD_HHMM` before its `.md`; a per-ticket plan's is the name of its parent directory. Never sort by file name, which starts with an issue ID or a ticket slug. A per-ticket plan counts only when its `{ticket-slug}` (its file name without `-plan.md`) appears in the worktree's branch name
+3. Read the most recent file that carries the section, extract `## PR Description Guidance` section
 4. If no plan files exist or section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`
 
 Render the test-plan block (per worktree) from `/implement`'s evidence file, and from nothing else:
@@ -287,19 +288,19 @@ The core, database, dependencies, documentation and compliance focuses, and ever
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-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`):
+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`):
 
 ```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:
+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 learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
 
 **Step 1 — Read the pre-rendered index:**
 
@@ -308,13 +309,17 @@ Attempt to read `{ledger}/.devflow/learning/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` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Slice the index, then hand it on:**
 
-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.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
 
-This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.
+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.
+
+This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents as one shared slice, cut over the diff's files. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.
 
 ### Load Feature Knowledge
 
@@ -338,7 +343,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **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). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+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:**
 
@@ -369,7 +374,7 @@ 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.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
 Pass `FEATURE_KNOWLEDGE` to all Review agents alongside `DECISIONS_CONTEXT`.
 
@@ -408,6 +413,10 @@ Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` sele
 
 Review agent count: `code` runs 8 core, +1-12 added by Phase 1 (max 20 total per worktree); a reduced class or a mix runs 2-6.
 
+**Set the compliance focus directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_FOCUS_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`; only the compliance focus's spawn carries it:
+
+> For this compliance focus, invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
 Each Review agent invocation (all in one message, **NOT background**):
 ```
 Agent(subagent_type="Review", run_in_background=false):
@@ -421,7 +430,7 @@ DECISIONS_CONTEXT: {decisions_context}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
 PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}  (compliance focus only)
+{COMPLIANCE_FOCUS_DIRECTIVE}  (compliance focus only)
 If PRIOR_RESOLUTIONS is not (none), follow Cross-Cycle Awareness in review.md.
 Follow devflow:apply-decisions to scan the index and Read full ADR/PF bodies on demand.
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specific patterns and anti-patterns inform findings.
@@ -517,21 +526,8 @@ In multi-worktree mode, report results per worktree.
 
 | Case | Handling |
 |------|----------|
-| No new commits since last review | Skip review, report: "No new commits since last review. Use --full for a full re-review." |
-| Rebase invalidates `.last-review-head` SHA | `git cat-file -t` check fails → fallback to full diff |
-| Same-minute review collision | `mkdir` fails → retry with seconds appended (`YYYY-MM-DD_HHMMSS`) |
-| Worktree in detached HEAD | Filtered out (no branch name → not reviewable) |
-| Worktree mid-rebase or mid-merge | Filtered out by status check |
-| Two worktrees on same branch | Deduplicate by branch — review once, use first worktree's path |
-| Worktree on protected branch | Filtered out (not reviewable) |
-| Worktree pre-flight fails | Report failure, continue with other worktrees |
 | `--full` in multi-worktree mode | Applies to all worktrees (global modifier) |
-| Many worktrees (5+) | Report count and proceed — user manages their worktree count |
 | Review comment already posted | Git agent matches its own marker on the `{cycle, timestamp}` pair → skip silently (D7); a re-review in the same cycle (different timestamp) posts its own comment. The marker's format belongs to the operation; this caller passes the pair and never restates the literal |
-| First review (no prior resolution) | PRIOR_RESOLUTIONS=(none), no convergence check |
-| fp_ratio denominator = 0 | fp_ratio = 0, no warning |
-| `--full` flag | Bypass incremental detection (Step 0d), still load PRIOR_RESOLUTIONS for cross-cycle awareness |
-| Parsing failure on resolution-summary.md | fp_ratio = 0, convergence tracking degraded (see Step 0e-ii) |
 | Concurrent sessions | Advisory only, each session computes independently |
 | Docs-only diff | `docs-only`: documentation, consistency, security on `diff.patch`; no language or conditional focus |
 | Tests-only diff | `tests-only`: testing, reliability, consistency, security on `diff.patch`; no language or conditional focus |

package/dist/commands/debug.md

@@ -42,23 +42,31 @@ Accept the output only when it is exactly two lines: `exit=0` last and, before i
 
 The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
 
+From the same line: `COMPLIANCE_FRAMEWORKS` is the settings line's `COMPLIANCE` with `generic` written `none`: `off`, `none`, or the framework ids the machine and this repository declare.
+
+**Set the compliance directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_DIRECTIVE` is empty when `COMPLIANCE_FRAMEWORKS` is `off`: a spawn line that holds only `{COMPLIANCE_DIRECTIVE}` is then left out, so a lens-off spawn carries nothing about compliance. Otherwise `COMPLIANCE_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`:
+
+> When the task touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention), invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
+Phase 7 passes `COMPLIANCE_DIRECTIVE` to the Code agent that implements the fix, on a line of its own.
+
 ### Load DECISIONS_CONTEXT
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-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`):
+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`):
 
 ```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:
+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 learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
 
 **Step 1 — Read the pre-rendered index:**
 
@@ -67,11 +75,15 @@ Attempt to read `{ledger}/.devflow/learning/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` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+
+**Step 2 — Slice the index, then hand it on:**
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
 
-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.
+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.
 
 The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Phase 2) — prior pitfalls and decisions can suggest specific root causes to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore investigators** — decisions context stays in the orchestrator; investigators examine code directly.
 
@@ -226,7 +238,20 @@ Produce the final report:
 
 Ask user via AskUserQuestion: "Want me to implement this fix?"
 
-- **YES** → Load `devflow:patterns` and `devflow:test-driven-development` skills, implement the fix, then spawn `Agent(subagent_type="Simplify")` on changed files.
+- **YES** → implement the fix through the Code agent, never in this thread, then spawn `Agent(subagent_type="Polish")` on the changed files. /debug loads no feature knowledge, so the fix gets none:
+
+  ```
+  Agent(subagent_type="Code"):
+  "OPERATION: implement
+  TASK_ID: debug-{YYYY-MM-DD_HHMM}
+  TASK_DESCRIPTION: Implement the fix for this root cause: {bug description}
+  EXECUTION_PLAN: {Root Cause, Key Findings and Recommended Fix from Phase 6, with their file:line references}
+  PUSH: false
+  DECISIONS_CONTEXT: {decisions_context}
+  FEATURE_KNOWLEDGE: (none)
+  {COMPLIANCE_DIRECTIVE}"
+  ```
+
 - **NO** → Done. Report stands as documentation.
 
 ### Feature Knowledge Write-Back (Conditional)
@@ -261,21 +286,17 @@ FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
 DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
-DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+DECISIONS_CONTEXT: {the slice for these directories, else (none)}
 
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
-Then update the index cache by performing a read-modify-write on:
+Then update the index cache:
   {worktree}/.devflow/features/index.md
 
 Index line format: `- **{slug}** — {areas} — {Use-when description}` — at most 300 characters, the description at most 220; reword a longer one, never cut it.
 
-If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
-
-The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
-
-After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+Then commit the two files as your Commit Protocol directs."
 ```
 
 **Step 4 — Surface an uncommitted knowledge base:**
@@ -307,7 +328,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 ├─ Phase 6: Root cause report with confidence level
 │
 ├─ Phase 7: Offer Fix
-│  └─ AskUserQuestion → implement fix + Simplify agent, or done
+│  └─ AskUserQuestion → Code agent (fix) + Polish agent, or done
 │
 └─ Feature Knowledge Write-Back (Conditional)
    └─ Knowledge agent (if investigation surfaced durable cross-cutting knowledge)