gsdd-cli 0.25.0 → 0.27.0

package/bin/adapters/claude.mjs

@@ -36,7 +36,20 @@ ${delegateContent.trim()}
 `;
 }
 
-function renderClaudePlanSkill() {
+function renderClaudePlanSkill({ portableContractPath = '.agents/skills/gsdd-plan/SKILL.md' } = {}) {
+  const contractSection = portableContractPath
+    ? `Portable contract:
+- Read \`${portableContractPath}\` first. That file remains the canonical vendor-agnostic plan contract.
+- Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
+- If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this Claude-native adapter path.`
+    : `Workflow contract:
+- This globally installed skill is the canonical Claude-native \`gsdd-plan\` workflow contract.
+- Keep the workflow portable: use repo-local \`.planning/\` artifacts for project state and do not require repo-local \`.agents/skills/\` files to exist.
+- Do not claim that other runtimes have the same behavior unless their own adapters explicitly implement and prove it.`;
+  const planningContract = portableContractPath
+    ? `\`${portableContractPath}\``
+    : 'this skill';
+
   return `---
 name: gsdd-plan
 description: Claude-native Phase planning with fresh-context plan checking for GSDD
@@ -45,10 +58,7 @@ argument-hint: [phase-number]
 
 You are the Claude-native \`/gsdd-plan\` skill for GSDD phase planning.
 
-Portable contract:
-- Read \`.agents/skills/gsdd-plan/SKILL.md\` first. That file remains the canonical vendor-agnostic plan contract.
-- Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
-- If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this Claude-native adapter path.
+${contractSection}
 
 Native Claude adapter rule:
 - This skill is the canonical Claude-native entry surface for \`/gsdd-plan\`.
@@ -66,7 +76,7 @@ Execution flow:
    d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
    e. Before planning, confirm APPROACH.md records all canonical proof fields: \`alignment_status\`, \`alignment_method\`, \`user_confirmed_at\`, \`explicit_skip_approved\`, \`skip_scope\`, \`skip_rationale\`, and \`confirmed_decisions\`. For \`alignment_status: user_confirmed\`, \`confirmed_decisions\` must name the locked decisions and skip fields may be \`false\`/\`N/A\`; for \`alignment_status: approved_skip\`, \`explicit_skip_approved: true\`, \`skip_scope\`, and \`skip_rationale\` must be substantive. Agent-only "No questions needed" is not valid proof under \`workflow.discuss: true\`.
    f. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
-4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
+4. Produce the initial phase plan according to ${planningContract}. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
 5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance. This only skips the independent checker; it does not skip the step 3 alignment-proof gate when \`workflow.discuss: true\`.
 6. If \`workflow.planCheck: true\`, invoke the native \`gsdd-plan-checker\` subagent with fresh context.
 7. Pass only explicit inputs to the checker:
@@ -107,14 +117,14 @@ Never return raw checker JSON without summarizing it.
 `;
 }
 
-function renderClaudePlanCommand() {
+function renderClaudePlanCommand({ skillPath = '.claude/skills/gsdd-plan/SKILL.md' } = {}) {
   return `---
 description: Compatibility alias for the Claude-native \`/gsdd-plan\` skill
 argument-hint: [phase-number]
 allowed-tools: Read
 ---
 
-Read \`.claude/skills/gsdd-plan/SKILL.md\` and execute that skill as the canonical Claude-native \`/gsdd-plan\` entry.
+Read \`${skillPath}\` and execute that skill as the canonical Claude-native \`/gsdd-plan\` entry.
 
 Rules:
 - Do NOT duplicate orchestration logic here.

package/bin/adapters/opencode.mjs

@@ -145,7 +145,7 @@ ${delegateContent.trim()}
 `;
 }
 
-function renderOpenCodePlanCommand() {
+function renderOpenCodePlanCommand({ skillPath = '.agents/skills/gsdd-plan/SKILL.md' } = {}) {
   return `---
 description: OpenCode-native phase planning with fresh-context plan checking for GSDD
 subtask: false
@@ -154,7 +154,7 @@ subtask: false
 You are the OpenCode-native \`/gsdd-plan\` command for GSDD phase planning.
 
 Portable contract:
-- Read \`.agents/skills/gsdd-plan/SKILL.md\` first. That file remains the canonical vendor-agnostic plan contract.
+- Read \`${skillPath}\` first. That file remains the canonical vendor-agnostic plan contract.
 - Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
 - If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this OpenCode-native adapter path.
 
@@ -174,7 +174,7 @@ Execution flow:
    d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
    e. Before planning, confirm APPROACH.md records all canonical proof fields: \`alignment_status\`, \`alignment_method\`, \`user_confirmed_at\`, \`explicit_skip_approved\`, \`skip_scope\`, \`skip_rationale\`, and \`confirmed_decisions\`. For \`alignment_status: user_confirmed\`, \`confirmed_decisions\` must name the locked decisions and skip fields may be \`false\`/\`N/A\`; for \`alignment_status: approved_skip\`, \`explicit_skip_approved: true\`, \`skip_scope\`, and \`skip_rationale\` must be substantive. Agent-only "No questions needed" is not valid proof under \`workflow.discuss: true\`.
    f. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
-4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
+4. Produce the initial phase plan according to \`${skillPath}\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
 5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance. This only skips the independent checker; it does not skip the step 3 alignment-proof gate when \`workflow.discuss: true\`.
 6. If \`workflow.planCheck: true\`, invoke the hidden \`gsdd-plan-checker\` subagent with fresh context.
 7. Pass only explicit inputs to the checker:

package/bin/gsdd.mjs

@@ -11,8 +11,9 @@ import {
   upsertBoundedBlock,
   getDelegateContent,
 } from './lib/rendering.mjs';
-import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels } from './lib/models.mjs';
+import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels, cmdRigor } from './lib/models.mjs';
 import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
+import { createCmdInstall } from './lib/global-install.mjs';
 import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phase.mjs';
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
@@ -21,7 +22,9 @@ import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { cmdUiProof } from './lib/ui-proof.mjs';
 import { cmdControlMap } from './lib/control-map.mjs';
 import { createCmdCloseoutReport } from './lib/closeout-report.mjs';
+import { createCmdNext } from './lib/next.mjs';
 import { resolveWorkspaceContext } from './lib/workspace-root.mjs';
+import { FRAMEWORK_VERSION, WORKFLOWS } from './lib/workflows.mjs';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', 'distilled');
@@ -31,33 +34,6 @@ const IS_MAIN = process.argv[1] ? realpathSync(process.argv[1]) === realpathSync
 
 const [,, command, ...args] = process.argv;
 
-function defineWorkflow({ mutatesArtifacts = true, ...workflow }) {
-  return {
-    ...workflow,
-    mutatesArtifacts,
-    agent: mutatesArtifacts ? 'Code' : 'Plan',
-    opencodeType: mutatesArtifacts ? 'edit' : 'plan',
-  };
-}
-
-const WORKFLOWS = [
-  defineWorkflow({ name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap' }),
-  defineWorkflow({ name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan' }),
-  defineWorkflow({ name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation' }),
-  defineWorkflow({ name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions' }),
-  defineWorkflow({ name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan' }),
-  defineWorkflow({ name: 'gsdd-verify-work', workflow: 'verify-work.md', description: 'Conversational UAT testing - validate user-facing behavior with structured gap tracking' }),
-  defineWorkflow({ name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows' }),
-  defineWorkflow({ name: 'gsdd-complete-milestone', workflow: 'complete-milestone.md', description: 'Complete milestone - archive, evolve spec, collapse roadmap' }),
-  defineWorkflow({ name: 'gsdd-new-milestone', workflow: 'new-milestone.md', description: 'New milestone - gather goals, define requirements, create roadmap phases' }),
-  defineWorkflow({ name: 'gsdd-plan-milestone-gaps', workflow: 'plan-milestone-gaps.md', description: 'Plan gap closure phases from audit results' }),
-  defineWorkflow({ name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle' }),
-  defineWorkflow({ name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption' }),
-  defineWorkflow({ name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action' }),
-  defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
-];
-
-const FRAMEWORK_VERSION = 'v1.4';
 function createCliContext(cwd = process.cwd()) {
   return {
     cwd,
@@ -68,6 +44,9 @@ function createCliContext(cwd = process.cwd()) {
     packageVersion: PACKAGE_JSON.version,
     workflows: WORKFLOWS,
     frameworkVersion: FRAMEWORK_VERSION,
+    loadProjectModelConfig,
+    getRuntimeModelOverride,
+    resolveRuntimeAgentModel,
     adapters: createAdapterRegistry({
       cwd,
       workflows: WORKFLOWS,
@@ -86,8 +65,10 @@ function createCliContext(cwd = process.cwd()) {
 
 const INIT_CONTEXT = createCliContext(process.cwd());
 const cmdInit = createCmdInit(INIT_CONTEXT);
+const cmdInstall = createCmdInstall(INIT_CONTEXT);
 const cmdHealth = createCmdHealth(INIT_CONTEXT);
 const cmdCloseoutReport = createCmdCloseoutReport(INIT_CONTEXT);
+const cmdNext = createCmdNext(INIT_CONTEXT);
 
 const cmdUpdate = (...updateArgs) => {
   const { args: normalizedArgs, workspaceRoot, invalid, error } = resolveWorkspaceContext(updateArgs, { cwd: INIT_CONTEXT.cwd });
@@ -98,12 +79,14 @@ const cmdUpdate = (...updateArgs) => {
   }
   return createCmdUpdate(createCliContext(workspaceRoot))(...normalizedArgs);
 };
-
 const COMMANDS = {
   init: cmdInit,
+  install: cmdInstall,
   update: cmdUpdate,
   models: cmdModels,
+  rigor: cmdRigor,
   health: cmdHealth,
+  next: cmdNext,
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
   'session-fingerprint': cmdSessionFingerprint,
@@ -136,4 +119,4 @@ async function runCli(cliCommand = command, ...cliArgs) {
 }
 
 if (IS_MAIN) await runCli();
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdUiProof, cmdControlMap, cmdCloseoutReport, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdInstall, cmdUpdate, cmdModels, cmdRigor, cmdHealth, cmdNext, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdUiProof, cmdControlMap, cmdCloseoutReport, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/closeout-report.mjs

@@ -21,7 +21,7 @@ function notice(source, severity, entry) {
     severity,
     code: entry.code || entry.id || 'unknown',
     message: entry.message,
-    fix: entry.fix || entry.fix_hint || null,
+    fix: entry.fix_hint || entry.fix || null,
     path: entry.path || null,
   };
 }
@@ -160,18 +160,38 @@ function nextSafeAction({ blockers, warnings, phaseNumber }) {
   if (blockers.length > 0) {
     return {
       command: `gsdd verify ${phaseNumber}`,
-      reason: 'Repair blockers before treating closeout as replayed.',
+      reason: 'Fix blockers first, then re-run closeout replay.',
+    };
+  }
+  const hasWarn = warnings.some((entry) => entry.severity === 'warn');
+  if (warnings.length > 0 && hasWarn) {
+    const sources = new Set(warnings.filter((entry) => entry.severity === 'warn').map((entry) => entry.source));
+    if (sources.has('health')) {
+      return {
+        command: 'gsdd health --json',
+        reason: 'Resolve workspace health warnings before claiming the environment is clean.',
+      };
+    }
+    if (sources.has('ui_proof') || sources.has('phase_verification')) {
+      return {
+        command: `gsdd verify ${phaseNumber}`,
+        reason: 'Resolve phase verification warnings before claiming closeout is replay-clean.',
+      };
+    }
+    return {
+      command: 'gsdd control-map --json',
+      reason: 'Resolve local state warnings before claiming the environment is clean.',
     };
   }
   if (warnings.length > 0) {
     return {
       command: 'gsdd control-map --json',
-      reason: 'Review warnings before claiming the local environment is clean.',
+      reason: 'Review the informational notices before claiming the local environment is clean.',
     };
   }
   return {
     command: `gsdd verify ${phaseNumber}`,
-    reason: 'Phase implementation is replay-clean; run formal verification for closure if it has not already been recorded.',
+    reason: 'Closeout replay is clean; run formal verification for closure if it has not already been recorded.',
   };
 }
 
@@ -266,11 +286,17 @@ function printHuman(report) {
   console.log(`Status: ${report.status}`);
   if (report.blockers.length > 0) {
     console.log('\nBlockers:');
-    for (const blocker of report.blockers) console.log(`  - [${blocker.source}] ${blocker.code}: ${blocker.message}`);
+    for (const blocker of report.blockers) {
+      console.log(`  - [${blocker.source}] ${blocker.code}: ${blocker.message}`);
+      if (blocker.fix) console.log(`    Fix: ${blocker.fix}`);
+    }
   }
   if (report.warnings.length > 0) {
     console.log('\nWarnings:');
-    for (const warning of report.warnings) console.log(`  - [${warning.source}] ${warning.code}: ${warning.message}`);
+    for (const warning of report.warnings) {
+      console.log(`  - [${warning.source}] ${warning.code}: ${warning.message}`);
+      if (warning.fix) console.log(`    Fix: ${warning.fix}`);
+    }
   }
   console.log(`\nNext safe action: ${report.next_safe_action.command}`);
   console.log(`Reason: ${report.next_safe_action.reason}`);

package/bin/lib/control-map.mjs

@@ -982,29 +982,73 @@ function buildRisks({ canonical, worktrees, annotations, rawAnnotations, runtime
   const writeSetOverlaps = findWriteSetOverlaps(writeEntries);
   const dirtyWriteSetOverlaps = findDirtyWriteSetOverlaps(writeEntries, dirtyEntries);
 
+  function fixHintForRisk(risk) {
+    const code = risk.code;
+    switch (code) {
+      case 'canonical_git_invalid':
+      case 'worktree_git_invalid': {
+        const targetPath = risk.worktree_id || canonical.path;
+        return `Run \`git config --global --add safe.directory ${targetPath}\`, then re-run \`gsdd control-map --json\`.`;
+      }
+      case 'canonical_dirty':
+        return 'Commit, stash, or checkpoint the canonical changes before planning, cleanup, merge, or broad execution.';
+      case 'canonical_dirty_behind_upstream':
+        return 'Commit/stash the canonical changes or sync the branch; do not mutate a dirty checkout that is behind upstream.';
+      case 'canonical_branch_behind_upstream':
+      case 'canonical_branch_diverged_upstream':
+      case 'worktree_branch_behind_upstream':
+      case 'worktree_branch_diverged_upstream':
+        return 'Review upstream divergence (fetch/merge/rebase) before treating this branch state as an execution surface.';
+      case 'detached_candidate_worktree':
+        return 'Classify the detached worktree intent (active vs abandoned) before using it for execution or cleanup decisions.';
+      case 'sibling_worktree_dirty':
+      case 'unannotated_candidate_worktree':
+        return 'Review sibling worktree ownership and write set before starting overlapping implementation.';
+      case 'write_set_overlap':
+        return 'Resolve overlapping local annotation write sets before starting another owned-write workflow.';
+      case 'dirty_path_write_set_overlap':
+        return 'Checkpoint or classify dirty paths that overlap annotated write sets before owned-write transitions.';
+      case 'planning_state_drift':
+        return 'Review drift and rebaseline with session-fingerprint only after confirming the planning changes are intentional.';
+      default:
+        return null;
+    }
+  }
+
   for (const error of gitErrors) {
     risks.push({ code: error.code, severity: 'warn', message: error.message });
   }
   if (!canonical.git_valid) {
-    risks.push({ code: 'canonical_git_invalid', severity: 'warn', message: `Canonical worktree git status failed: ${canonical.status_error || 'unknown error'}` });
+    const risk = {
+      code: 'canonical_git_invalid',
+      severity: 'warn',
+      path: normalizeSlashes(canonical.path),
+      message: `Canonical worktree git status failed: ${canonical.status_error || 'unknown error'}`,
+    };
+    risk.fix_hint = fixHintForRisk(risk);
+    risks.push(risk);
   }
   addBranchStateRisks(risks, canonical, { canonical: true });
   if (canonical.dirty.counts.tracked > 0 || canonical.dirty.counts.untracked > 0) {
-    risks.push({
+    const risk = {
       code: 'canonical_dirty',
       severity: 'warn',
       message: `Canonical worktree has tracked/untracked changes (${canonical.dirty.counts.tracked} tracked, ${canonical.dirty.counts.untracked} untracked).`,
-    });
+    };
+    risk.fix_hint = fixHintForRisk(risk);
+    risks.push(risk);
   }
   if (canonical.dirty.counts.tracked > 0 && (canonical.ahead_behind?.behind || 0) > 0) {
-    risks.push({
+    const risk = {
       code: 'canonical_dirty_behind_upstream',
       severity: 'block',
       branch: canonical.branch,
       ahead: canonical.ahead_behind?.ahead,
       behind: canonical.ahead_behind?.behind,
       message: `Canonical worktree has tracked changes while behind upstream by ${canonical.ahead_behind.behind} commit(s).`,
-    });
+    };
+    risk.fix_hint = fixHintForRisk(risk);
+    risks.push(risk);
   }
   if (canonical.dirty.counts.ignored > 0) {
     risks.push({
@@ -1015,51 +1059,68 @@ function buildRisks({ canonical, worktrees, annotations, rawAnnotations, runtime
   }
   for (const worktree of worktrees.filter((entry) => entry.path !== canonical.path)) {
     if (!worktree.git_valid) {
-      risks.push({ code: 'worktree_git_invalid', severity: 'warn', worktree_id: worktree.id, message: `Worktree ${worktree.id} could not be inspected by git.` });
+      const risk = {
+        code: 'worktree_git_invalid',
+        severity: 'warn',
+        worktree_id: worktree.id,
+        message: `Worktree ${worktree.id} could not be inspected by git.`,
+      };
+      risk.fix_hint = fixHintForRisk(risk);
+      risks.push(risk);
     }
     addBranchStateRisks(risks, worktree);
     if (worktree.detached) {
-      risks.push({
+      const risk = {
         code: 'detached_candidate_worktree',
         severity: 'warn',
         worktree_id: worktree.id,
         message: `Worktree ${worktree.id} is detached; classify its intent before treating it as an execution surface.`,
-      });
+      };
+      risk.fix_hint = fixHintForRisk(risk);
+      risks.push(risk);
     }
     if (worktree.dirty.counts.tracked > 0 || worktree.dirty.counts.untracked > 0) {
-      risks.push({
+      const risk = {
         code: 'sibling_worktree_dirty',
         severity: 'warn',
         worktree_id: worktree.id,
         message: `Sibling worktree ${worktree.id} has tracked/untracked changes.`,
-      });
+      };
+      risk.fix_hint = fixHintForRisk(risk);
+      risks.push(risk);
     }
     if (!worktree.annotation && (worktree.dirty.counts.tracked > 0 || worktree.dirty.counts.untracked > 0 || worktree.detached)) {
-      risks.push({
+      const risk = {
         code: 'unannotated_candidate_worktree',
         severity: 'info',
         worktree_id: worktree.id,
         message: `Worktree ${worktree.id} has candidate-work signals but no local control-map annotation.`,
-      });
+      };
+      risk.fix_hint = fixHintForRisk(risk);
+      risks.push(risk);
     }
   }
   if (writeSetOverlaps.length > 0) {
-    risks.push({
+    const risk = {
       code: 'write_set_overlap',
       severity: 'block',
       message: `Active control-map annotations have ${writeSetOverlaps.length} concrete write-set overlap(s).`,
       overlaps: writeSetOverlaps.slice(0, MAX_DIRTY_BUCKET_ENTRIES),
       omitted_count: Math.max(0, writeSetOverlaps.length - MAX_DIRTY_BUCKET_ENTRIES),
-    });
+    };
+    risk.fix_hint = fixHintForRisk(risk);
+    risks.push(risk);
   }
   if (dirtyWriteSetOverlaps.length > 0) {
-    risks.push({
+    const risk = {
       code: 'dirty_path_write_set_overlap',
       severity: 'block',
       message: `Live dirty paths overlap annotated write sets (${dirtyWriteSetOverlaps.length} overlap(s)).`,
       overlaps: dirtyWriteSetOverlaps.slice(0, MAX_DIRTY_BUCKET_ENTRIES),
       omitted_count: Math.max(0, dirtyWriteSetOverlaps.length - MAX_DIRTY_BUCKET_ENTRIES),
-    });
+    };
+    risk.fix_hint = fixHintForRisk(risk);
+    risks.push(risk);
   }
   for (const warning of annotations.warnings || []) risks.push(warning);
   for (const error of annotations.errors || []) {
@@ -1074,11 +1135,22 @@ function buildRisks({ canonical, worktrees, annotations, rawAnnotations, runtime
     });
   }
   if (workflowState.planning_drift.drifted) {
-    risks.push({
+    const risk = {
       code: 'planning_state_drift',
       severity: 'warn',
       message: `Planning state drifted since the last fingerprint: ${workflowState.planning_drift.details.join('; ')}`,
-    });
+    };
+    risk.fix_hint = fixHintForRisk(risk);
+    risks.push(risk);
+  }
+
+  // Ensure the common closure risks expose actionable fix guidance even when
+  // the originating helper (for example branch-state risks) didn't attach it.
+  for (const risk of risks) {
+    if (!risk.fix_hint) {
+      const hint = fixHintForRisk(risk);
+      if (hint) risk.fix_hint = hint;
+    }
   }
   return risks;
 }
@@ -1175,7 +1247,10 @@ function printHuman(map) {
   }
   if (map.risks.length > 0) {
     console.log('\nRisks:');
-    for (const risk of map.risks) console.log(`  - [${risk.severity || 'info'}] ${risk.code}: ${risk.message}`);
+    for (const risk of map.risks) {
+      console.log(`  - [${risk.severity || 'info'}] ${risk.code}: ${risk.message}`);
+      if (risk.fix_hint) console.log(`    Fix: ${risk.fix_hint}`);
+    }
   }
   console.log('\nInterventions:');
   for (const intervention of map.interventions) console.log(`  - ${intervention}`);