devflow-kit 2.4.0 → 2.5.0

package/dist/cli/commands/uninstall.js

@@ -6,7 +6,9 @@ import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getInstallationPaths, getClaudeDirectory, getManagedSettingsPath } from '../../targets/claude-code/claude-paths.js';
 import { getGitRoot } from '../../core/git.js';
-import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { readManifest } from '../../core/manifest.js';
+import { TRACKER_ATTEMPTS_FILE, TRACKER_CLAIM_FILE, TRACKER_ENABLED_FILE } from '../../core/tracker.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
 import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
 import { removeAmbientHook } from './ambient.js';
@@ -18,6 +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_CONVENTIONS_FILE, TRACKER_CONVENTIONS_BACKUP_NAMES, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
 import { revertExternalAgents } from '../../core/agent-models.js';
 import { detectShell, getProfilePath } from '../../core/safe-delete.js';
 import { isAlreadyInstalled, removeFromProfile } from '../../core/safe-delete-install.js';
@@ -26,20 +29,51 @@ import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { stripFlags } from '../../core/flags.js';
 import { stripDevflowTeammateModeFromJson } from '../../core/teammate-mode-cleanup.js';
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
+/**
+ * The plugins the manifest records as installed, as registry definitions.
+ *
+ * Falls back to the whole registry when there is no readable manifest, or when
+ * it names nothing this registry still has: that is the pre-manifest and the
+ * corrupt-manifest case, and retaining too much is the safe direction for a
+ * removal. Names the manifest carries that the registry has since dropped are
+ * skipped rather than invented — a definition is what the retained-set
+ * arithmetic needs, and there is none for a deleted plugin.
+ */
+export async function resolveInstalledPlugins(devflowDir) {
+    const manifest = await readManifest(devflowDir).catch(() => null);
+    const names = new Set(manifest?.plugins ?? []);
+    if (names.size === 0)
+        return DEVFLOW_PLUGINS;
+    const resolved = DEVFLOW_PLUGINS.filter(plugin => names.has(plugin.name));
+    return resolved.length === 0 ? DEVFLOW_PLUGINS : resolved;
+}
 /**
  * Compute which assets should be removed during selective plugin uninstall.
  * Skills and agents shared by remaining plugins are retained.
  * Rules shared by remaining plugins are also retained.
+ *
+ * D-RETAIN-FROM-MANIFEST: `installedPlugins` is what the MANIFEST records as
+ * installed, not the whole registry. Once skills are plugin-scoped the two stop
+ * agreeing, and taking the registry retains assets on behalf of plugins the user
+ * never installed — so `devflow uninstall --plugin=X` keeps X's skills alive
+ * because some unselected plugin also declares them, and the user is left with
+ * exactly the files they asked to remove. Skills are retained across the CLOSURE
+ * (`skills ∪ requires`) of the remaining plugins, for the same reason the
+ * install set is a closure: a skill another installed plugin merely requires is
+ * still a skill it needs.
+ *
+ * @param installedPlugins - The plugins the manifest records. Callers pass the
+ *   registry only when there is no manifest to read, and the dry-run and the
+ *   real removal must always be given the SAME list or they describe different
+ *   outcomes.
  */
-export function computeAssetsToRemove(selectedPlugins, allPlugins) {
+export function computeAssetsToRemove(selectedPlugins, installedPlugins) {
     const selectedNames = new Set(selectedPlugins.map(p => p.name));
-    const remainingPlugins = allPlugins.filter(p => !selectedNames.has(p.name));
-    const retainedSkills = new Set();
+    const remainingPlugins = installedPlugins.filter(p => !selectedNames.has(p.name));
+    const retainedSkills = skillsOf(remainingPlugins);
     const retainedAgents = new Set();
     const retainedRules = new Set();
     for (const rp of remainingPlugins) {
-        for (const s of rp.skills)
-            retainedSkills.add(s);
         for (const a of rp.agents)
             retainedAgents.add(a);
         for (const r of rp.rules)
@@ -49,11 +83,11 @@ export function computeAssetsToRemove(selectedPlugins, allPlugins) {
     const agents = [];
     const commands = [];
     const rules = [];
+    for (const skill of skillsOf(selectedPlugins)) {
+        if (!retainedSkills.has(skill))
+            skills.push(skill);
+    }
     for (const plugin of selectedPlugins) {
-        for (const skill of plugin.skills) {
-            if (!retainedSkills.has(skill))
-                skills.push(skill);
-        }
         for (const agent of plugin.agents) {
             if (!retainedAgents.has(agent))
                 agents.push(agent);
@@ -183,21 +217,69 @@ export function resolveDevflowDirCleanup(opts) {
     return 'prompt';
 }
 /**
- * Enumerate user-authored content in devflowDir that would be deleted by a
- * full cleanup of the directory.
+ * Single source of truth for user-authored content under `devflowDir`.
  *
- * Checks for items that exist on disk and are worth backing up:
- *   devflowDir/skills/              — skill shadow overrides (user-maintained)
- *   devflowDir/rules/               — rule shadow overrides (user-maintained)
- *   devflowDir/preference-profile.md — dynamic-plan preference profile
- *   devflowDir/learning.json         — global learning agent tuning config
- *   devflowDir/hud.json              — HUD enable/disable preference and display config
+ * The counterpart to `installArtifactPaths`: together the two lists describe
+ * every Devflow-created entry in `~/.devflow`, and they never overlap (@D8).
+ * Membership here means "survives every path but a confirmed full-dir rm";
+ * membership there means "removed on decline, cancel, non-interactive and
+ * --keep-docs alike".
  *
  * NOT listed here: agent-models.json — reclassified as an INSTALL ARTIFACT (AC-P1-F4).
  * Stale per-agent model overrides silently re-apply to renamed/deleted agents on reinstall,
  * so it must be cleaned up by removeDevFlowInstallArtifacts, not preserved behind a confirm gate.
  *
- * Returns labels for each item that actually exists. Empty array means nothing
+ * @param devflowDir - Absolute path to ~/.devflow (labels quote the shadow dirs).
+ */
+export function userContentPaths(devflowDir) {
+    return [
+        // Skill shadow overrides (~/.devflow/skills/{name}/)
+        { relPath: 'skills', isDir: true, label: `skill shadows (${path.join(devflowDir, 'skills')})` },
+        // Rule shadow overrides (~/.devflow/rules/{name}.md)
+        { relPath: 'rules', isDir: true, label: `rule shadows (${path.join(devflowDir, 'rules')})` },
+        // preference-profile.md — user-curated decision-preference profile
+        { relPath: 'preference-profile.md', label: 'preference-profile.md' },
+        // tracker.md — the inferred, hand-editable issue-tracker conventions file.
+        //
+        // USER CONTENT (OD-15), classified the same way as preference-profile.md above
+        // rather than as an install artifact like agent-models.json, because it is
+        // inferred ONCE per machine and then hand-editable: absence is the trigger that
+        // re-runs inference, so deleting it on every decline/cancel/--keep-docs path
+        // would silently discard work the user may have corrected by hand.
+        //
+        // REVERSAL CONDITION, recorded: this classification is CONDITIONAL on the
+        // provider-mismatch guard shipping. agent-models.json was reclassified to an
+        // artifact precisely because stale overrides re-apply *silently*; "silently" is
+        // the load-bearing word. A stale tracker.md whose frontmatter provider
+        // disagrees with the resolved provider produces
+        // `TRACEABILITY: DEGRADED (tracker configuration mismatch (conventions file))`
+        // and no tracker call — that is what removes the silence, and the reason names
+        // THIS file rather than the per-repo override so the user is told which of the
+        // two to edit. If that guard is ever dropped,
+        // reclassify tracker.md to an install artifact IN THE SAME CHANGE, otherwise a
+        // silently-authoritative stale file survives uninstall.
+        { relPath: TRACKER_CONVENTIONS_FILE, label: `${TRACKER_CONVENTIONS_FILE} (issue tracker conventions)` },
+        // tracker.md.{provider}.bak — what renameStaleTrackerConventions leaves behind
+        // on a provider change. Same inferred content as tracker.md (the user's site
+        // and project key), so the same classification: named by the confirm prompt,
+        // kept by every artifacts-only pass. The names come from the registry, so a
+        // fourth provider is covered the day it lands.
+        ...TRACKER_CONVENTIONS_BACKUP_NAMES.map(name => ({
+            relPath: name,
+            label: `${name} (previous issue tracker conventions)`,
+        })),
+        // learning.json — global learning 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)' },
+    ];
+}
+/**
+ * Enumerate user-authored content in devflowDir that would be deleted by a
+ * full cleanup of the directory.
+ *
+ * Walks `userContentPaths` and returns the label of every entry that exists on
+ * disk — a directory counts only when it is non-empty. Empty array means nothing
  * user-authored is present in the directory.
  *
  * Pure I/O — no side effects, no output, fully testable.
@@ -207,41 +289,54 @@ export function resolveDevflowDirCleanup(opts) {
  */
 export async function enumerateUserDevFlowContent(devflowDir) {
     const items = [];
-    // Skill shadow overrides (~/.devflow/skills/{name}/)
-    try {
-        const entries = await fs.readdir(path.join(devflowDir, 'skills'));
-        if (entries.length > 0) {
-            items.push(`skill shadows (${path.join(devflowDir, 'skills')})`);
+    for (const entry of userContentPaths(devflowDir)) {
+        const fullPath = path.join(devflowDir, entry.relPath);
+        try {
+            if (entry.isDir) {
+                const children = await fs.readdir(fullPath);
+                if (children.length === 0)
+                    continue;
+            }
+            else {
+                await fs.access(fullPath);
+            }
+            items.push(entry.label);
         }
+        catch { /* absent or unreadable */ }
     }
-    catch { /* dir absent or unreadable */ }
-    // Rule shadow overrides (~/.devflow/rules/{name}.md)
-    try {
-        const entries = await fs.readdir(path.join(devflowDir, 'rules'));
-        if (entries.length > 0) {
-            items.push(`rule shadows (${path.join(devflowDir, 'rules')})`);
+    return items;
+}
+/**
+ * Expand `installArtifactPaths` against real disk.
+ *
+ * Exact entries pass through untouched; a prefix entry becomes one entry per
+ * matching direct child of `devflowDir`. This is the ONE place a prefix turns
+ * into paths, so the removal loop and the dry-run preview cannot disagree about
+ * what a prefix covers. An unreadable or absent `devflowDir` yields the exact
+ * entries alone — absent is the ordinary case here, never an error.
+ */
+export async function resolveInstallArtifactPaths(devflowDir) {
+    const resolved = [];
+    let children = null;
+    for (const entry of installArtifactPaths(devflowDir)) {
+        if (entry.isPrefix !== true) {
+            resolved.push({ relPath: entry.relPath, isDir: entry.isDir });
+            continue;
+        }
+        if (children === null) {
+            try {
+                children = await fs.readdir(devflowDir);
+            }
+            catch {
+                children = [];
+            }
+        }
+        for (const child of children) {
+            if (child.startsWith(entry.relPath))
+                resolved.push({ relPath: child, isDir: entry.isDir });
         }
     }
-    catch { /* dir absent or unreadable */ }
-    // preference-profile.md — user-curated decision-preference profile
-    try {
-        await fs.access(path.join(devflowDir, 'preference-profile.md'));
-        items.push('preference-profile.md');
-    }
-    catch { /* absent */ }
-    // learning.json — global learning agent tuning config
-    try {
-        await fs.access(path.join(devflowDir, 'learning.json'));
-        items.push('learning.json');
-    }
-    catch { /* absent */ }
-    // hud.json — user HUD enable/disable preference and display config
-    try {
-        await fs.access(path.join(devflowDir, 'hud.json'));
-        items.push('hud.json (HUD configuration)');
-    }
-    catch { /* absent */ }
-    return items;
+    return resolved;
 }
 /**
  * Single source of truth for Devflow-owned install artifacts under `devflowDir`.
@@ -252,9 +347,18 @@ export async function enumerateUserDevFlowContent(devflowDir) {
  * lets callers (dry-run display, tests) enumerate the artifact set without
  * duplicating the list.
  *
- * @D8 Nothing returned here may overlap with the items enumerated by
- * `enumerateUserDevFlowContent` — the disjointness invariant is tested by test 9f
- * and enforced by keeping both lists in one place.
+ * @D8 Nothing returned here may overlap with `userContentPaths` — the two lists
+ * are the whole of what Devflow puts in `~/.devflow`, and a name in both is
+ * deleted whatever the user answers to the full-wipe prompt. Checked two ways:
+ * mechanically, by intersecting the `relPath` sets of the two functions and
+ * checking no user path falls UNDER a prefix entry (so an entry added to either
+ * list is covered the day it lands), and behaviourally, by test 9f — every
+ * enumerated user item survives an artifact-only removal.
+ *
+ * Entries marked `isPrefix` name a FAMILY of per-invocation basenames rather
+ * than one path; `resolveInstallArtifactPaths` is what turns them into paths.
+ * Every consumer goes through that resolver, so a prefix entry is never treated
+ * as a literal filename.
  *
  * @param devflowDir - Absolute path to ~/.devflow (used to resolve cache dir).
  */
@@ -274,6 +378,20 @@ export function installArtifactPaths(devflowDir) {
         { relPath: 'proxy-routing.json' },
         { relPath: 'proxy.pid' },
         { relPath: '.proxy-spawn.lock', isDir: true },
+        // tracker runtime artifacts — the Tracker agent's atomic claim file, its
+        // inference attempt counter, and the provider presence sentinel the
+        // SessionStart hook stats. All three are machine state with no user-authored
+        // content, so they go on this list; `tracker.md` beside them and the
+        // `tracker.md.{provider}.bak` a provider change leaves are USER CONTENT
+        // (OD-15) and are deliberately NOT here (@D8: the two lists stay disjoint).
+        { relPath: TRACKER_CLAIM_FILE },
+        { relPath: TRACKER_ATTEMPTS_FILE },
+        { relPath: TRACKER_ENABLED_FILE },
+        // The agent's scrubbed staging file, one per invocation under a mktemp name
+        // it removes from a trap — a SIGKILL outruns the trap and leaves it behind.
+        // A prefix, because the names exist only on disk. Content is a scrubbed copy
+        // that was never placed, so it is machine state like the three above.
+        { relPath: TRACKER_STAGED_PREFIX, isPrefix: true },
         // per-project hook logs (logs/{project-slug}/) AND global logs — remove the
         // whole logs/ tree; covers proxy.log, debug logs, and any project-slug dirs.
         { relPath: 'logs', isDir: true },
@@ -295,7 +413,8 @@ export function installArtifactPaths(devflowDir) {
  * @D8 Nothing enumerated by enumerateUserDevFlowContent may appear in this list.
  * This function runs on the decline, cancel, non-interactive AND --keep-docs paths,
  * so an entry here is deleted even when the user answers "no" to the full wipe.
- * User-authored state (skill/rule shadows, preference-profile.md, learning.json,
+ * User-authored state (everything in `userContentPaths`: skill/rule shadows,
+ * preference-profile.md, tracker.md and its provider backups, learning.json,
  * hud.json) is removed only by the confirmed full-dir rm.
  * agent-models.json is an INSTALL ARTIFACT (stale per-agent overrides silently
  * re-apply to renamed/deleted agents on reinstall — AC-P1-F4) and therefore
@@ -327,8 +446,10 @@ export async function removeDevFlowInstallArtifacts(devflowDir, verbose) {
         }
     }
     catch { /* proxy.pid absent or unreadable — non-fatal */ }
-    // All install artifacts removed non-fatally (avoids PF-009).
-    for (const artifact of installArtifactPaths(devflowDir)) {
+    // All install artifacts removed non-fatally (avoids PF-009). Resolved against
+    // disk first, so a per-run staging basename is a real path by the time the
+    // containment guard below sees it.
+    for (const artifact of await resolveInstallArtifactPaths(devflowDir)) {
         const fullPath = path.join(devflowDir, artifact.relPath);
         // Containment invariant: every artifact must resolve to a path STRICTLY inside
         // devflowDir. A derived relPath that ever collapsed to '' or '..' would turn the
@@ -456,7 +577,7 @@ export async function enumerateDryRunExtras(claudeDir, devflowDir) {
     //    Guard with fs.access so files that never existed don't pollute the preview.
     //    (F7: previously pushed unconditionally, inflating the dry-run list with
     //    paths that were never on disk.)
-    for (const artifact of installArtifactPaths(devflowDir)) {
+    for (const artifact of await resolveInstallArtifactPaths(devflowDir)) {
         const fullPath = path.join(devflowDir, artifact.relPath);
         try {
             await fs.access(fullPath);
@@ -476,13 +597,18 @@ export async function enumerateDryRunExtras(claudeDir, devflowDir) {
  * @param opts.scopesToUninstall - Scopes detected in the setup phase.
  * @param opts.isSelectiveUninstall - true when --plugin was given.
  * @param opts.selectedPlugins - The plugin subset for selective mode.
+ * @param opts.installedPlugins - What the manifest records as installed. The
+ *   dry-run and the real removal MUST receive the same list, or the preview
+ *   describes an outcome the removal does not produce.
  */
 export async function runDryRunPhase(opts) {
-    const { scopesToUninstall, isSelectiveUninstall, selectedPlugins } = opts;
+    const { scopesToUninstall, isSelectiveUninstall, selectedPlugins, installedPlugins } = opts;
     p.log.info(`Scope(s): ${[...scopesToUninstall].join(', ')} (dry-run shows all detected scopes)`);
     if (isSelectiveUninstall) {
-        // Selective: compute from registry — this accurately reflects what would be removed.
-        const assets = computeAssetsToRemove(selectedPlugins, DEVFLOW_PLUGINS);
+        // Selective: computed against the INSTALLED list, the same argument the real
+        // removal is given below — a preview computed from a different list is a
+        // preview of a different uninstall.
+        const assets = computeAssetsToRemove(selectedPlugins, installedPlugins);
         const plan = formatDryRunPlan(assets);
         for (const line of plan.split('\n')) {
             p.log.info(line);
@@ -527,6 +653,7 @@ export async function runDryRunPhase(opts) {
  */
 export async function runSelectivePhaseForScope(opts) {
     const { claudeDir, devflowDir, selectedPlugins, verbose } = opts;
+    const installedPlugins = opts.installedPlugins ?? DEVFLOW_PLUGINS;
     // Revert GPT agent frontmatter BEFORE removing agent files — strips GPT model
     // lines from installed agent frontmatter while the files are still present.
     // Non-fatal: tolerate missing agents dir or revert errors.
@@ -543,7 +670,7 @@ export async function runSelectivePhaseForScope(opts) {
         }
         catch { /* agents dir absent or revert failed — non-fatal */ }
     }
-    await removeSelectedPlugins(claudeDir, selectedPlugins, verbose);
+    await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins);
     // Clean up ambient hook if ambient plugin is being removed
     if (selectedPlugins.some(sp => sp.name === 'devflow-ambient')) {
         const settingsPath = path.join(claudeDir, 'settings.json');
@@ -972,7 +1099,20 @@ export const uninstallCommand = new Command('uninstall')
     }
     // === DRY RUN: show plan and exit ===
     if (dryRun) {
-        await runDryRunPhase({ scopesToUninstall, isSelectiveUninstall, selectedPlugins });
+        // One resolution, handed to the dry-run and (below) to the real removal,
+        // so the preview and the outcome are computed from the same list.
+        let dryRunInstalled = DEVFLOW_PLUGINS;
+        try {
+            const paths = await getInstallationPaths(scopesToUninstall[0]);
+            dryRunInstalled = await resolveInstalledPlugins(paths.devflowDir);
+        }
+        catch { /* scope path resolution failed — fall back to the registry */ }
+        await runDryRunPhase({
+            scopesToUninstall,
+            isSelectiveUninstall,
+            selectedPlugins,
+            installedPlugins: dryRunInstalled,
+        });
         p.outro(color.dim('No changes made (dry run)'));
         return;
     }
@@ -1021,7 +1161,13 @@ export const uninstallCommand = new Command('uninstall')
             continue;
         }
         if (isSelectiveUninstall) {
-            await runSelectivePhaseForScope({ claudeDir, devflowDir, selectedPlugins, verbose });
+            await runSelectivePhaseForScope({
+                claudeDir,
+                devflowDir,
+                selectedPlugins,
+                verbose,
+                installedPlugins: await resolveInstalledPlugins(devflowDir),
+            });
         }
         else {
             await runFullPhaseForScope({ scope, claudeDir, devflowDir, devflowScriptsDir, verbose, keepDocs: !!options.keepDocs, isTTY: !!process.stdin.isTTY });
@@ -1161,8 +1307,8 @@ export async function sweepDevflowNamespaces(claudeDir, verbose) {
  * registry (retired agents/commands survive indefinitely without the sweep).
  * For skills: only remove skills that are NOT used by any remaining plugin.
  */
-export async function removeSelectedPlugins(claudeDir, plugins, verbose) {
-    const { skills, agents, commands, rules } = computeAssetsToRemove(plugins, DEVFLOW_PLUGINS);
+export async function removeSelectedPlugins(claudeDir, plugins, verbose, installedPlugins = DEVFLOW_PLUGINS) {
+    const { skills, agents, commands, rules } = computeAssetsToRemove(plugins, installedPlugins);
     const commandsDir = path.join(claudeDir, 'commands', 'devflow');
     for (const cmd of commands) {
         const cmdFileName = mdFileName(cmd.replace(/^\//, ''));

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 { trackerCommand } from './cli/commands/tracker.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read version from package.json
@@ -47,6 +48,7 @@ program.addCommand(safeDeleteCommand);
 program.addCommand(proxyCommand);
 program.addCommand(agentsCommand);
 program.addCommand(complianceCommand);
+program.addCommand(trackerCommand);
 // Handle no command (bare `devflow`) or unknown subcommand.
 // When Commander sees an unrecognised first argument it does not route to any
 // registered subcommand; instead the root action fires with that argument

package/dist/commands/bug-analysis.md

@@ -17,17 +17,35 @@ Run a proactive bug analysis on the current branch by combining static analysis
 
 ### Phase 1: Pre-flight
 
-**Produces:** BRANCH_INFO, PR_DESCRIPTION, COMPLIANCE_SKILL_INSTALLED
+**Produces:** BRANCH_INFO, PR_DESCRIPTION, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
 
-**Resolve `COMPLIANCE_SKILL_INSTALLED` once per run:** Check whether `~/.claude/skills/devflow:compliance/SKILL.md` exists (one file-existence check, read-only, silent). Set `COMPLIANCE_SKILL_INSTALLED = true` if the file exists, `false` otherwise.
-Reuse this result for every downstream phase.
+**Resolve the evidence policy once per run**, from the repository root, before any step reads the values:
+
+```bash
+node "${DEVFLOW_DIR:-$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.
+
+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.
+
+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 `-`.
+2. Only when `branch_slug` matches `^[A-Za-z0-9._-]{1,200}$` and the file exists, run (the path double-quoted):
+
+```bash
+node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" render --plan ".devflow/docs/evidence-{branch_slug}.md"; echo "exit=$?"
+```
+
+3. On `exit=0`, `PR_TEST_PLAN_BLOCK` is its stdout byte for byte without that `exit=` line; in every other case it is `(none)`. Nothing here waits on it: the Git agent pastes it only behind its own check, and only into a PR it creates.
 
 Spawn Git agent:
 
 ```
 Agent(subagent_type="Git", run_in_background=false):
 "OPERATION: ensure-pr-ready
-COMPLIANCE: {COMPLIANCE_SKILL_INSTALLED ? "enabled" : "(none)"}
+PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
 Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, branch-slug, PR#"
 ```

package/dist/commands/code-review.md

@@ -37,6 +37,20 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 **Resolve `COMPLIANCE_SKILL_INSTALLED` once per run:** Check whether `~/.claude/skills/devflow:compliance/SKILL.md` exists (one file-existence check, read-only, silent). Set `COMPLIANCE_SKILL_INSTALLED = true` if the file exists, `false` otherwise.
 Reuse this result for every worktree and every downstream phase.
 
+#### Step 0b-ii: Resolve the evidence policy
+
+**Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
+
+**Resolve the evidence policy once per run**, from the repository root, before any step reads the values:
+
+```bash
+node "${DEVFLOW_DIR:-$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.
+
+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.
+
 #### Step 0c: Per-Worktree Pre-Flight (Git Agent)
 
 **Produces:** BRANCH_INFO, PR_INFO, PR_DESCRIPTION, PR_DESCRIPTION_GUIDANCE
@@ -48,6 +62,16 @@ Discover PR description guidance from plan artifact (per worktree):
 3. Read the most recent file, 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:
+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
+node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" render --plan "{worktree}/.devflow/docs/evidence-{branch_slug}.md"; echo "exit=$?"
+```
+
+3. On `exit=0`, `PR_TEST_PLAN_BLOCK` is its stdout byte for byte without that `exit=` line; in every other case it is `(none)`. Nothing here waits on it: the Git agent pastes it only behind its own check, and only into a PR it creates.
+
 For each reviewable worktree, spawn Git agent:
 
 ```
@@ -55,7 +79,8 @@ Agent(subagent_type="Git", run_in_background=false):
 "OPERATION: ensure-pr-ready
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
 PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
-COMPLIANCE: {COMPLIANCE_SKILL_INSTALLED ? "enabled" : "(none)"}
+PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK verbatim, or (none)}
+APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
 Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, branch-slug, PR#"
 ```
@@ -133,13 +158,15 @@ MAX_REVIEW_CYCLES = 10
 #### Step 0f: Resolve Publication Mode (Per Worktree)
 
 **Produces:** REVIEW_PUBLICATION
-**Requires:** WORKTREES
+**Requires:** WORKTREES, EVIDENCE_POLICY
 
 For each reviewable worktree, call:
 
 **Resolve `REVIEW_PUBLICATION` per worktree:** Read the current worktree's `.devflow/config.json` (a single, direct file read — multi-worktree repos may have different publication settings per worktree root). If the file exists and `reviewPublication` is one of `auto`, `full`, or `off`, set `REVIEW_PUBLICATION` to that value; otherwise set `REVIEW_PUBLICATION = "auto"`.
 
-Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB).
+**Evidence stub:** only when `EVIDENCE_POLICY` is `required`, a resolved `off` becomes `stub`, so a counts-only record still reaches the PR. `stub` is never a config value: a configured `stub` is unrecognised and resolves to `auto` like any other.
+
+Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB). What each value does is decided by the Git agent's publication gate (`references/publication-gate.md` step 2); this partial only resolves the value.
 
 ### Phase 1: Analyze Changed Files
 
@@ -165,6 +192,8 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio
 
 If `COMPLIANCE_SKILL_INSTALLED` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): add `compliance` to REVIEW_FOCUS_LIST for this worktree.
 
+**Language focus presence gate.** The eight language focuses — `typescript`, `react`, `accessibility`, `ui-design`, `go`, `java`, `python`, `rust` — ship with optional plugins, so their pattern skills are installed only when the user selected that plugin. Gate them exactly as `compliance` is gated: for each language focus the table above would add, check whether `~/.claude/skills/devflow:{focus}/SKILL.md` exists (one file-existence check per candidate focus, read-only, silent). If it does not exist, do NOT add that focus to `REVIEW_FOCUS_LIST` and do NOT spawn a Review agent for it — the file-type condition alone never spawns a language focus. The eight core focuses are unconditional and are never presence-gated.
+
 ### Phase 1b: Load Decisions Index
 
 **Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_SKILL_INSTALLED (carried from Step 0b)
@@ -248,14 +277,14 @@ Spawn Review agents **in a single message**. Always run 8 core reviews; conditio
 | regression | ✓ | devflow:regression |
 | testing | ✓ | devflow:testing |
 | reliability | ✓ | devflow:reliability |
-| typescript | conditional | devflow:typescript |
-| react | conditional | devflow:react |
-| accessibility | conditional | devflow:accessibility |
-| ui-design | conditional | devflow:ui-design |
-| go | conditional | devflow:go |
-| java | conditional | devflow:java |
-| python | conditional | devflow:python |
-| rust | conditional | devflow:rust |
+| typescript | presence-gated | devflow:typescript |
+| react | presence-gated | devflow:react |
+| accessibility | presence-gated | devflow:accessibility |
+| ui-design | presence-gated | devflow:ui-design |
+| go | presence-gated | devflow:go |
+| java | presence-gated | devflow:java |
+| python | presence-gated | devflow:python |
+| rust | presence-gated | devflow:rust |
 | database | conditional | devflow:database |
 | dependencies | conditional | devflow:dependencies |
 | documentation | conditional | devflow:documentation |
@@ -309,7 +338,7 @@ Output: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-s
 Agent(subagent_type="Git", run_in_background=false):
 "OPERATION: post-review-summary
 PR_NUMBER: {pr_number}
-REVIEW_SUMMARY_PATH: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md
+REVIEW_SUMMARY_PATH: .devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md
 CYCLE_NUMBER: {cycle_number}
 REVIEW_TIMESTAMP: {timestamp}
 REVIEW_PUBLICATION: {REVIEW_PUBLICATION}
@@ -327,7 +356,7 @@ Per worktree, after successful completion:
    - Merge recommendation (from Synthesize agent)
    - Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing)
    - Review comment status: POSTED / POSTED+TRUNCATED (body exceeded 60k after redaction) / SKIPPED (D7 dedup) / DEGRADED (from Git)
-   - Publication status: FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) (from Git agent)
+   - Publication status: FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) | STUB (visibility undeterminable) | STUB (evidence policy) (from Git agent)
    - Artifact paths
 
 In multi-worktree mode, report results per worktree.
@@ -378,14 +407,14 @@ In multi-worktree mode, report results per worktree.
 | 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 `<!-- devflow:review-summary cycle:{N} ts:{REVIEW_TIMESTAMP}` pair → skip silently (D7); a re-review in the same cycle (different timestamp) posts its own comment |
+| 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 |
 | Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full report stays local |
-| `reviewPublication: off` | Git agent skips posting the review comment (OFF) |
+| `reviewPublication: off` | Git agent skips posting the review comment (OFF) — except that, only when `EVIDENCE_POLICY` is `required`, Step 0f passes `stub` and a counts-only STUB comment posts |
 
 ## Backwards Compatibility