gsdd-cli 0.24.0 → 0.26.0

package/bin/lib/global-manifest.mjs

@@ -0,0 +1,122 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+
+export const GLOBAL_MANIFEST_FILENAME = 'workspine-file-manifest.json';
+
+export function sha256(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function fileHash(filePath) {
+  return sha256(readFileSync(filePath));
+}
+
+export function readGlobalManifest(rootDir) {
+  const manifestPath = join(rootDir, GLOBAL_MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeGlobalManifest(rootDir, manifest) {
+  mkdirSync(rootDir, { recursive: true });
+  writeFileSync(join(rootDir, GLOBAL_MANIFEST_FILENAME), JSON.stringify(manifest, null, 2));
+}
+
+export function toManifestPath(rootDir, absolutePath) {
+  return relative(rootDir, absolutePath).replace(/\\/g, '/');
+}
+
+export function writeManifestTrackedFile({
+  rootDir,
+  relativePath,
+  content,
+  previousManifest,
+  nextFiles,
+  dryRun = false,
+}) {
+  const absolutePath = join(rootDir, relativePath);
+  const normalizedRelativePath = relativePath.replace(/\\/g, '/');
+  const expectedHash = sha256(content);
+  const previousHash = previousManifest?.files?.[normalizedRelativePath] || null;
+
+  if (existsSync(absolutePath)) {
+    const currentHash = fileHash(absolutePath);
+    if (currentHash === expectedHash) {
+      nextFiles[normalizedRelativePath] = expectedHash;
+      return { relativePath: normalizedRelativePath, status: 'unchanged' };
+    }
+    if (!previousHash) {
+      return {
+        relativePath: normalizedRelativePath,
+        status: 'skipped_unmanaged',
+        message: 'existing file is not tracked by Workspine manifest',
+      };
+    }
+    if (currentHash !== previousHash) {
+      return {
+        relativePath: normalizedRelativePath,
+        status: 'skipped_modified',
+        message: 'existing Workspine-managed file was modified by the user',
+      };
+    }
+  }
+
+  nextFiles[normalizedRelativePath] = expectedHash;
+  if (!dryRun) {
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, content);
+  }
+  return { relativePath: normalizedRelativePath, status: dryRun ? 'would_write' : 'written' };
+}
+
+export function pruneStaleManifestTrackedFiles({
+  rootDir,
+  previousManifest,
+  nextFiles,
+  dryRun = false,
+}) {
+  if (!previousManifest?.files) return [];
+
+  const root = resolve(rootDir);
+  const results = [];
+  for (const [relativePath, previousHash] of Object.entries(previousManifest.files)) {
+    const normalizedRelativePath = relativePath.replace(/\\/g, '/');
+    if (nextFiles[normalizedRelativePath]) continue;
+
+    const absolutePath = resolve(rootDir, normalizedRelativePath);
+    if (absolutePath !== root && !absolutePath.startsWith(`${root}\\`) && !absolutePath.startsWith(`${root}/`)) {
+      results.push({
+        relativePath: normalizedRelativePath,
+        status: 'skipped_unsafe',
+        message: 'previous manifest path resolves outside the install root',
+      });
+      continue;
+    }
+
+    if (!existsSync(absolutePath)) {
+      results.push({ relativePath: normalizedRelativePath, status: 'removed_missing' });
+      continue;
+    }
+
+    const currentHash = fileHash(absolutePath);
+    if (currentHash !== previousHash) {
+      results.push({
+        relativePath: normalizedRelativePath,
+        status: 'skipped_modified',
+        message: 'stale Workspine-managed file was modified by the user',
+      });
+      continue;
+    }
+
+    if (!dryRun) rmSync(absolutePath, { force: true });
+    results.push({ relativePath: normalizedRelativePath, status: dryRun ? 'would_remove' : 'removed_stale' });
+  }
+
+  return results;
+}

package/bin/lib/health.mjs

@@ -14,21 +14,19 @@ import { findUiProofBundleFiles, readUiProofBundleFile, validateUiProofBundle }
 import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 /**
- * Factory function returning the health command.
- * ctx should provide: { frameworkVersion, workflows }
+ * Build the structured health report without printing or mutating workspace
+ * state. ctx should provide: { frameworkVersion, workflows }.
  */
-export function createCmdHealth(ctx) {
-  return async function cmdHealth(...healthArgs) {
-    const jsonMode = healthArgs.includes('--json');
+export function buildHealthReport(ctx, healthArgs = []) {
     const { planningDir, workspaceRoot, invalid, error } = resolveWorkspaceContext(healthArgs);
     if (invalid) {
-      if (jsonMode) {
-        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: error, fix: 'Pass --workspace-root with a real path or remove the flag.' }], warnings: [], info: [] });
-      } else {
-        console.log(error);
-      }
-      process.exitCode = 1;
-      return;
+      return {
+        status: 'broken',
+        errors: [{ id: 'E1', severity: 'ERROR', message: error, fix: 'Pass --workspace-root with a real path or remove the flag.' }],
+        warnings: [],
+        info: [],
+        humanMessage: error,
+      };
     }
     const cwd = workspaceRoot;
     const frameworkSourceMode = isFrameworkSourceRepo(cwd);
@@ -36,13 +34,13 @@ export function createCmdHealth(ctx) {
 
     // Pre-init guard
     if (!existsSync(join(planningDir, 'config.json'))) {
-      if (jsonMode) {
-        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: '.planning/config.json missing', fix: 'Run `npx -y gsdd-cli init`' }], warnings: [], info: [] });
-      } else {
-        console.log('Not initialized. Run `npx -y gsdd-cli init`. If `gsdd` is installed globally, `gsdd init` is also fine.');
-      }
-      process.exitCode = 1;
-      return;
+      return {
+        status: 'broken',
+        errors: [{ id: 'E1', severity: 'ERROR', message: '.planning/config.json missing', fix: 'Run `npx -y gsdd-cli init`' }],
+        warnings: [],
+        info: [],
+        humanMessage: 'Not initialized. Run `npx -y gsdd-cli init`. If `gsdd` is installed globally, `gsdd init` is also fine.',
+      };
     }
 
     const errors = [];
@@ -210,11 +208,12 @@ export function createCmdHealth(ctx) {
     // W5: Phase dir has PLAN but no SUMMARY (stale in-progress)
     if (lifecycle.incompletePlans.length > 0) {
       for (const plan of lifecycle.incompletePlans) {
+        const expectedSummary = `.planning/phases/${plan.dir}/${plan.baseId}-SUMMARY.md`;
         warnings.push({
           id: 'W5',
           severity: 'WARN',
           message: `${plan.displayPath} exists but no matching SUMMARY found (stale in-progress?)`,
-          fix: 'Resume or complete the phase',
+          fix: `Run \`gsdd execute ${plan.phaseToken}\` to write ${expectedSummary}.`,
         });
       }
     }
@@ -272,22 +271,41 @@ export function createCmdHealth(ctx) {
     const hasWarnings = warnings.length > 0;
     const status = hasErrors ? 'broken' : hasWarnings ? 'degraded' : 'healthy';
 
-    if (hasErrors) process.exitCode = 1;
+    return { status, errors, warnings, info };
+}
+/**
+ * Factory function returning the health command.
+ * ctx should provide: { frameworkVersion, workflows }
+ */
+export function createCmdHealth(ctx) {
+  return async function cmdHealth(...healthArgs) {
+    const jsonMode = healthArgs.includes('--json');
+    const report = buildHealthReport(ctx, healthArgs);
+    const printableReport = {
+      status: report.status,
+      errors: report.errors,
+      warnings: report.warnings,
+      info: report.info,
+    };
+
+    if (report.status === 'broken') process.exitCode = 1;
 
     if (jsonMode) {
-      output({ status, errors, warnings, info });
+      output(printableReport);
+    } else if (report.humanMessage) {
+      console.log(report.humanMessage);
     } else {
-      console.log(`\ngsdd health — workspace integrity check\n`);
-      if (errors.length > 0) {
-        for (const e of errors) console.log(`  ERROR: [${e.id}] ${e.message}\n    Fix: ${e.fix}`);
+      console.log(`\ngsdd health - workspace integrity check\n`);
+      if (report.errors.length > 0) {
+        for (const e of report.errors) console.log(`  ERROR: [${e.id}] ${e.message}\n    Fix: ${e.fix}`);
       }
-      if (warnings.length > 0) {
-        for (const w of warnings) console.log(`  WARN:  [${w.id}] ${w.message}\n    Fix: ${w.fix}`);
+      if (report.warnings.length > 0) {
+        for (const w of report.warnings) console.log(`  WARN:  [${w.id}] ${w.message}\n    Fix: ${w.fix}`);
       }
-      if (info.length > 0) {
-        for (const i of info) console.log(`  INFO:  [${i.id}] ${i.message}${i.fix ? `\n    Fix: ${i.fix}` : ''}`);
+      if (report.info.length > 0) {
+        for (const i of report.info) console.log(`  INFO:  [${i.id}] ${i.message}${i.fix ? `\n    Fix: ${i.fix}` : ''}`);
       }
-      console.log(`\n  Verdict: ${status.toUpperCase()}\n`);
+      console.log(`\n  Verdict: ${report.status.toUpperCase()}\n`);
     }
   };
 }

package/bin/lib/init-flow.mjs

@@ -320,6 +320,7 @@ function ensureGitignoreEntry(cwd, entry, message) {
 
 function printInitSummary(config) {
   console.log('Config summary:');
+  console.log(`  - rigorProfile: ${config.rigorProfile}`);
   console.log(`  - researchDepth: ${config.researchDepth}`);
   console.log(`  - parallelization: ${config.parallelization}`);
   console.log(`  - commitDocs: ${config.commitDocs}`);
@@ -330,6 +331,8 @@ function printInitSummary(config) {
     console.log(`  - workflow.discuss: ${config.workflow.discuss}`);
     console.log(`  - workflow.planCheck: ${config.workflow.planCheck}`);
     console.log(`  - workflow.verifier: ${config.workflow.verifier}`);
+    console.log(`  - workflow.showCode: ${config.workflow.showCode}`);
+    console.log(`  - workflow.askBeforeDecide: ${config.workflow.askBeforeDecide}`);
   }
   console.log('');
 }

package/bin/lib/init-prompts.mjs

@@ -54,11 +54,12 @@ export async function promptForConfig(cwd, { input = process.stdin, output = pro
   const rigor = await promptSingleSelect({
     input,
     output,
-    title: 'Rigor',
+    title: 'Rigor - how much the assistant does on its own vs. shows you and asks',
     choices: [
-      { value: 'quick', label: 'quick', description: 'Faster setup with lighter planning rigor' },
-      { value: 'balanced', label: 'balanced', description: 'Recommended default for most projects' },
-      { value: 'thorough', label: 'thorough', description: 'Maximum research and plan review rigor' },
+      { value: 'low', label: 'low', description: 'Autopilot. Skips research, plan-check, and asking - it proceeds on its best guess.' },
+      { value: 'medium', label: 'medium', description: 'Recommended default. Research + a fresh-context plan-check. No helpers, no extra asking.' },
+      { value: 'high', label: 'high', description: 'Helpers propose options; shows you the code before writing; asks when something is genuinely unclear.' },
+      { value: 'max', label: 'max', description: 'Most hands-on. Asks before deciding and shows the running screen. Pick low if you just want it to go.' },
     ],
     defaultIndex: 1,
   });
@@ -88,6 +89,7 @@ export async function promptForConfig(cwd, { input = process.stdin, output = pro
   const costConfig = resolveCost(cost);
 
   return {
+    rigorProfile: rigor,
     ...rigorConfig,
     ...costConfig,
     commitDocs,

package/bin/lib/init-runtime.mjs

@@ -172,11 +172,16 @@ Commands:
                               Launch guided install wizard in TTYs, or use --tools for manual/headless setup
                               --auto: non-interactive mode with smart defaults (requires --tools)
                               --brief <file>: copy project brief to .planning/PROJECT_BRIEF.md
+  install --global [--tools <platform>] [--dry]
+                              Install reusable Workspine skills and native runtime surfaces into agent home directories
+                              In TTYs, omitting --tools opens an agent picker
   update [--tools <platform>] [--templates] [--dry]
                               Regenerate adapters from latest framework sources
                               --templates: also refresh .planning/templates/ and roles
                               --dry: preview changes without writing files
   health [--json]             Check workspace integrity (healthy/degraded/broken)
+  next [--json] [--format auto|json|human] [--init]
+                              Read \`.work\` continuity state and emit the next coherent agent action
   models [subcommand]         Inspect or update model profile / runtime overrides
   find-phase [N]              Show phase info as JSON (for agent consumption)
   verify <N>                  Run artifact checks for phase N
@@ -194,6 +199,10 @@ Commands:
                               Compare planned UI proof slots against observed bundles
   control-map [--json] [--with-ignored] [--annotations <path>]
                               Report computed repo/worktree/planning state and local annotations
+  control-map annotate <set|clear>
+                              Maintain optional local intent annotations under .planning/.local/
+  closeout-report [--json] [--phase <N>]
+                              Replay read-only closeout status from control-map, health, preflight, verify, and UI-proof signals
   help                        Show this summary
 
 Platforms (for --tools):
@@ -206,19 +215,31 @@ Platforms (for --tools):
   gemini    Generate root AGENTS.md governance block; workflows are already discovered natively from .agents/skills/ (legacy alias kept for backward compatibility)
   all       Generate all adapters (Claude, OpenCode, Codex, AGENTS.md, Cursor, Copilot, Gemini)
 
+Global install targets:
+  claude    Install ~/.claude skills, commands, and agents
+  opencode  Install ~/.agents skills plus ~/.config/opencode commands and agents
+  codex     Install ~/.agents skills plus ~/.codex agents
+  copilot   Install ~/.agents skills plus ~/.copilot agent profiles
+  all       Install all global targets above
+
 Notes:
+  - use \`npx -y gsdd-cli init\` for repo-local setup; use \`npx -y gsdd-cli install --global\` when you want reusable skills in agent homes
   - init always generates open-standard skills at .agents/skills/gsdd-*; this is the shared workflow entry surface
   - init also generates a local .planning/bin/gsdd* helper surface for workflow-embedded lifecycle helpers; it is internal/advanced, not the normal first-run user entrypoint
+  - install --global never creates .planning/ in the current repo; it writes only selected agent-home surfaces and per-runtime Workspine manifests
+  - repair or refresh a global install by rerunning \`npx -y gsdd-cli install --global --tools <targets>\`; runtime probes stay in test harnesses
   - Workspine is the public product name; the retained package, command, workflow, and workspace contracts stay gsdd-cli, gsdd, gsdd-*, and .planning/
   - running \`npx -y gsdd-cli init\` in a terminal opens the guided runtime-selection wizard; bare \`gsdd init\` is equivalent only when globally installed
   - the wizard lets you pick runtimes first, then separately decide whether repo-wide AGENTS.md governance is worth installing
-  - \`npx -y gsdd-cli health\` compares any installed generated runtime surfaces against current render output and points back to \`npx -y gsdd-cli update\` when they drift
+  - \`npx -y gsdd-cli health\` is for repo-local .planning/ workspaces; it compares local generated surfaces and points back to \`npx -y gsdd-cli update\` when they drift
+  - \`npx -y gsdd-cli next --init\` bootstraps the local .work continuity surface; plain \`next\` is read-only and emits a typed next-action packet
+  - \`gsdd next\` defaults to JSON when stdout is captured; use \`--format human\` for the compact supervisor card
   - directly validated launch surfaces in this repo are Claude Code, OpenCode, and Codex CLI
   - Cursor, Copilot, and Gemini are qualified support through the shared .agents/skills/ surface plus optional governance
   - --tools remains the advanced/manual path and preserves legacy runtime aliases for backward compatibility
   - --tools codex generates .codex/agents/gsdd-plan-checker.toml (portable skill is the entry surface; $gsdd-plan is plan-only until explicit $gsdd-execute)
   - root AGENTS.md is only written on init when explicitly requested via --tools agents, --tools all, or the wizard governance opt-in
-  - normal user path: npx -y gsdd-cli init -> run /gsdd-* or $gsdd-* -> npx -y gsdd-cli health -> npx -y gsdd-cli update when repair or refresh is needed
+  - normal repo path: npx -y gsdd-cli init -> run /gsdd-* or $gsdd-* -> npx -y gsdd-cli health -> npx -y gsdd-cli update when local repair or refresh is needed
   - post-init, choose your starting lane honestly: new-project for greenfield or fuzzy/milestone work, quick for a concrete bounded change, map-codebase first when the repo needs deeper orientation
 
 Examples:
@@ -234,9 +255,16 @@ Examples:
   npx -y gsdd-cli models clear --runtime opencode --agent plan-checker
   npx -y gsdd-cli init --tools agents
   npx -y gsdd-cli init --tools all
+  npx -y gsdd-cli install --global
+  npx -y gsdd-cli install --global --tools claude,opencode,codex,copilot
   npx -y gsdd-cli update
+  npx -y gsdd-cli next --json
+  npx -y gsdd-cli next --format human
+  npx -y gsdd-cli next --init
   npx -y gsdd-cli find-phase
   npx -y gsdd-cli verify 1
+  npx -y gsdd-cli control-map annotate set --id canonical --write-set src/app.ts
+  npx -y gsdd-cli control-map annotate clear --id canonical
   npx -y gsdd-cli scaffold phase 4 Payments
 
 Workflows (run via skills/adapters generated by init, not direct CLI):
@@ -265,7 +293,9 @@ Advanced/internal helpers (kept available, but not the primary first-run user st
   session-fingerprint       Rebaseline the local planning-state fingerprint after review
   phase-status              Update ROADMAP.md phase status through the local helper surface
   ui-proof                  Validate UI proof metadata and compare planned slots to observed bundles
-  control-map               Report computed repo/worktree/planning state and local annotations
+  control-map               Report computed repo/worktree/planning state; annotate only records local intent
+  closeout-report           Read-only post-merge closure replay; reports blockers, warnings, and next safe action
+  next                      Read-only \`.work\` continuity router for the next coherent agent action
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/lifecycle-preflight.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { output } from './cli-utils.mjs';
+import { buildControlMap } from './control-map.mjs';
 import {
   DELIVERY_POSTURES,
   EVIDENCE_KINDS,
@@ -74,12 +75,14 @@ const RELEASE_CONTRADICTION_CHECKS = Object.freeze([
 ]);
 
 const RELEASE_CONTRADICTION_STATUSES = Object.freeze(['passed', 'failed', 'not_applicable']);
+const PREFLIGHT_CONTROL_MAP_SKIP_CODES = Object.freeze(['planning_state_drift']);
 
 export function evaluateLifecyclePreflight({
   planningDir,
   surface,
   phaseNumber = null,
   expectsMutation = 'none',
+  controlMapReport = null,
 } = {}) {
   if (!planningDir) {
     throw new Error('planningDir is required');
@@ -184,6 +187,17 @@ export function evaluateLifecyclePreflight({
     }
   }
 
+  const controlMap = buildPreflightControlMap({
+    planningDir,
+    policy,
+    existingBlockerCodes: new Set(blockers.map((entry) => entry.code)),
+    controlMapReport,
+  });
+  for (const notice of controlMap.notices) {
+    if (notice.severity === 'block') blockers.push(notice);
+    else warnings.push(notice);
+  }
+
   if (lifecycle.phaseStatusAlignment.mismatches.length > 0) {
     warnings.push({
       code: 'roadmap_phase_status_mismatch',
@@ -206,6 +220,7 @@ export function evaluateLifecyclePreflight({
     blockers,
     warnings,
     planningState,
+    controlMap: controlMap.summary,
     lifecycle: {
       currentMilestone: lifecycle.currentMilestone,
       currentPhase: lifecycle.currentPhase ? lifecycle.currentPhase.number : null,
@@ -215,6 +230,48 @@ export function evaluateLifecyclePreflight({
   };
 }
 
+function buildPreflightControlMap({ planningDir, policy, existingBlockerCodes, controlMapReport = null }) {
+  const empty = {
+    summary: null,
+    notices: [],
+  };
+  if (policy.classification !== 'owned_write' || !existsSync(planningDir)) return empty;
+
+  const map = controlMapReport || buildControlMap({
+    workspaceRoot: resolve(planningDir, '..'),
+    planningDir,
+  });
+  const risks = (map.risks || []).filter((risk) => (
+    !PREFLIGHT_CONTROL_MAP_SKIP_CODES.includes(risk.code)
+    && !(existingBlockerCodes.has(risk.code) && risk.severity !== 'block')
+  ));
+  const notices = risks.map((risk) => ({
+    ...controlMapNotice(risk),
+    severity: risk.severity || 'info',
+  }));
+
+  return {
+    summary: {
+      riskCount: map.risks.length,
+      noticeCount: notices.length,
+      blockerCount: notices.filter((notice) => notice.severity === 'block').length,
+      warningCount: notices.filter((notice) => notice.severity !== 'block').length,
+      interventions: map.interventions || [],
+    },
+    notices,
+  };
+}
+
+function controlMapNotice(risk) {
+  return {
+    code: risk.code,
+    source: 'control-map',
+    message: risk.message,
+    artifacts: ['gsdd control-map --json'],
+    risk,
+  };
+}
+
 function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
   const blockers = [];
   const phaseEntry = lifecycle.phases.find((phase) => phase.number === phaseToken);

package/bin/lib/models.mjs

@@ -15,21 +15,49 @@ export const DEFAULT_GIT_PROTOCOL = {
   pr: 'Follow the existing repo or team review workflow. Do not assume PR creation, timing, or naming unless explicitly requested.',
 };
 
+// The rigor knob: one setting that decides how much the assistant does on its own
+// versus how much it shows you and asks. low = autopilot; max = most hands-on.
+// showCode + askBeforeDecide are read by the workflow markdown (=== true means on,
+// a missing key means off), so existing projects whose config predates these flags
+// are unaffected.
 export const RIGOR_PROFILES = {
-  quick:    { researchDepth: 'fast',     workflow: { research: false, discuss: false, planCheck: false, verifier: true } },
-  balanced: { researchDepth: 'balanced', workflow: { research: true,  discuss: false, planCheck: true,  verifier: true } },
-  thorough: { researchDepth: 'deep',     workflow: { research: true,  discuss: true,  planCheck: true,  verifier: true } },
+  low:    { researchDepth: 'fast',     workflow: { research: false, discuss: false, planCheck: false, verifier: true, showCode: false, askBeforeDecide: false } },
+  medium: { researchDepth: 'balanced', workflow: { research: true,  discuss: false, planCheck: true,  verifier: true, showCode: false, askBeforeDecide: false } },
+  high:   { researchDepth: 'deep',     workflow: { research: true,  discuss: true,  planCheck: true,  verifier: true, showCode: true,  askBeforeDecide: false } },
+  max:    { researchDepth: 'deep',     workflow: { research: true,  discuss: true,  planCheck: true,  verifier: true, showCode: true,  askBeforeDecide: true  } },
 };
 
+// Legacy rigor names map silently to the new levels so old configs and callers keep
+// working. medium is behaviorally identical to the old balanced default.
+export const RIGOR_ALIASES = { quick: 'low', balanced: 'medium', thorough: 'high' };
+
+export const RIGOR_LEVELS = ['low', 'medium', 'high', 'max'];
+export const RIGOR_STEPS = ['plan', 'execute', 'verify'];
+
 export const COST_PROFILES = {
   budget:   { modelProfile: 'budget',   parallelization: false },
   balanced: { modelProfile: 'balanced', parallelization: true  },
   quality:  { modelProfile: 'quality',  parallelization: true  },
 };
 
-export function resolveRigor(id) { return RIGOR_PROFILES[id] ?? RIGOR_PROFILES.balanced; }
+export function resolveRigor(id) {
+  const key = RIGOR_ALIASES[id] ?? id;
+  return RIGOR_PROFILES[key] ?? RIGOR_PROFILES.medium;
+}
 export function resolveCost(id)  { return COST_PROFILES[id]  ?? COST_PROFILES.balanced;  }
 
+// Per-step rigor: an explicit rigorOverrides[step] wins, else the project rigorProfile,
+// else medium. A missing override is not "off" — it just means "follow the main knob".
+export function resolveStepRigor(config, step) {
+  const overrideName = config?.rigorOverrides?.[step];
+  const baseName = config?.rigorProfile;
+  return resolveRigor(overrideName ?? baseName ?? 'medium');
+}
+
+export function effectiveRigorLevel(config, step) {
+  return config?.rigorOverrides?.[step] ?? config?.rigorProfile ?? 'medium';
+}
+
 export const VALID_MODEL_PROFILES = ['quality', 'balanced', 'budget'];
 export const PORTABLE_AGENT_IDS = ['plan-checker', 'approach-explorer'];
 export const MODEL_RUNTIME_IDS = ['claude', 'opencode', 'codex'];
@@ -40,9 +68,10 @@ export function normalizeModelProfile(value) {
 }
 
 export function buildDefaultConfig({ autoAdvance = false } = {}) {
-  const rigor = resolveRigor('balanced');
+  const rigor = resolveRigor('medium');
   const cost = resolveCost('balanced');
   const config = {
+    rigorProfile: 'medium',
     ...rigor,
     ...cost,
     commitDocs: true,
@@ -409,3 +438,105 @@ function cmdModelsClearRuntimeOverride(args) {
   console.log(`  - cleared ${runtime} runtime override for ${agent}`);
   console.log('  Run gsdd update to regenerate adapter files.');
 }
+
+// --- The rigor knob ---------------------------------------------------------
+// gsdd rigor                      -> show the current level + per-step overrides
+// gsdd rigor <low|medium|high|max>-> set the project-wide level
+// gsdd rigor <plan|execute|verify> <level> -> override a single step
+
+function describeRigorFlags(config) {
+  const w = config.workflow ?? {};
+  return {
+    researchDepth: config.researchDepth,
+    research: w.research,
+    discuss: w.discuss,
+    planCheck: w.planCheck,
+    verifier: w.verifier,
+    showCode: w.showCode,
+    askBeforeDecide: w.askBeforeDecide,
+  };
+}
+
+function printChangedFlags(before, after) {
+  for (const key of Object.keys(after)) {
+    if (before[key] !== after[key]) {
+      console.log(`    ${key}: ${before[key]} -> ${after[key]}`);
+    }
+  }
+}
+
+export function cmdRigor(...rigorArgs) {
+  const [first, second] = rigorArgs;
+  if (!first || first === 'show') return cmdRigorShow();
+  if (RIGOR_STEPS.includes(first)) return cmdRigorSetStep(first, second);
+  if (RIGOR_LEVELS.includes(first)) return cmdRigorSetProfile(first);
+  console.error(
+    `ERROR: Invalid rigor argument "${first}". Usage: gsdd rigor [show | ${RIGOR_LEVELS.join('|')} | <${RIGOR_STEPS.join('|')}> <level>]`,
+  );
+  process.exitCode = 1;
+}
+
+function cmdRigorShow() {
+  const config = loadProjectModelConfig(process.cwd());
+  const base = config.rigorProfile ?? 'medium';
+  output({
+    rigorProfile: base,
+    rigorOverrides: config.rigorOverrides ?? {},
+    effective: {
+      plan: effectiveRigorLevel(config, 'plan'),
+      execute: effectiveRigorLevel(config, 'execute'),
+      verify: effectiveRigorLevel(config, 'verify'),
+    },
+    workflow: config.workflow ?? resolveRigor(base).workflow,
+  });
+}
+
+function cmdRigorSetProfile(level) {
+  if (!isProjectInitialized()) {
+    console.error('ERROR: Project not initialized. Run gsdd init first.');
+    process.exitCode = 1;
+    return;
+  }
+  const result = loadConfigForMutation();
+  if (!result.ok) {
+    console.error(`ERROR: .planning/config.json is malformed (${result.error}). Fix the file manually before running rigor mutations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const before = describeRigorFlags(result.config);
+  const resolved = resolveRigor(level);
+  result.config.rigorProfile = level;
+  result.config.researchDepth = resolved.researchDepth;
+  result.config.workflow = { ...resolved.workflow };
+  const after = describeRigorFlags(result.config);
+  writeProjectConfig(result.config);
+
+  console.log(`  - set rigor to ${level}`);
+  printChangedFlags(before, after);
+}
+
+function cmdRigorSetStep(step, level) {
+  if (!RIGOR_LEVELS.includes(level)) {
+    console.error(`ERROR: Invalid rigor level "${level}". Valid levels: ${RIGOR_LEVELS.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!isProjectInitialized()) {
+    console.error('ERROR: Project not initialized. Run gsdd init first.');
+    process.exitCode = 1;
+    return;
+  }
+  const result = loadConfigForMutation();
+  if (!result.ok) {
+    console.error(`ERROR: .planning/config.json is malformed (${result.error}). Fix the file manually before running rigor mutations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  result.config.rigorOverrides = result.config.rigorOverrides || {};
+  const previous = result.config.rigorOverrides[step] ?? `(follows ${result.config.rigorProfile ?? 'medium'})`;
+  result.config.rigorOverrides[step] = level;
+  writeProjectConfig(result.config);
+  console.log(`  - set ${step} rigor override: ${previous} -> ${level}`);
+}