gsdd-cli 0.22.0 → 0.24.0

package/README.md

@@ -69,7 +69,7 @@ Invariant suites (I-series), guard suites (G-series), and scenario suites (S-ser
 
 ### Smaller surface, stricter closure
 
-14 workflows. 10 roles. One CLI. Lifecycle progression goes through deterministic preflight gates — not conversational inference. Plans are checked by a separate agent in a separate context before execution begins. Closure requires evidence, not just file existence.
+4 main workflows, 14 public workflow surfaces, 10 roles, one CLI. The daily spine is `new-project -> plan -> execute -> verify`; milestone, quick, pause/resume, progress, audit, and mapping surfaces support that spine. Lifecycle progression goes through deterministic preflight gates — not conversational inference. Plans are checked by a separate agent in a separate context before execution begins. Closure requires evidence, not just file existence.
 
 <details>
 <summary>How it works</summary>
@@ -346,6 +346,7 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | `npx -y gsdd-cli init [--tools <platform>]` | Set up `.planning/`, generate skills/adapters |
 | `npx -y gsdd-cli update [--tools <platform>] [--templates]` | Regenerate skills/adapters and refresh the repo-local helper runtime; `--templates` refreshes `.planning/templates/` and role contracts |
 | `npx -y gsdd-cli health [--json]` | Check workspace integrity and generated-surface freshness (healthy/degraded/broken) |
+| `npx -y gsdd-cli control-map [--json] [--with-ignored]` | Report computed repo/worktree/planning state, dirty buckets, optional ignored-path scan, local annotations, and safe next interventions |
 | `npx -y gsdd-cli ui-proof validate <path> [--claim <public\|publication\|tracked\|delivery\|release>]` | Validate UI proof bundle metadata without requiring browser tooling; use `--claim` only when validating that stronger proof use |
 | `npx -y gsdd-cli file-op <copy\|delete\|regex-sub>` | Run deterministic workspace-confined file copy, delete, and regex substitution |
 | `npx -y gsdd-cli find-phase [N]` | Show phase info as JSON (for agent consumption) |
@@ -415,6 +416,7 @@ Model IDs pass through a two-layer injection guard: a regex whitelist (`/^[a-zA-
 | `.planning/research/` | Research outputs |
 | `.planning/codebase/` | Codebase maps (4 files) |
 | `.planning/quick/` | Quick task tracking |
+| `.planning/.local/` | Local-only operational annotations such as control-map intent; never product truth |
 | `.planning/.continue-here.md` | Session checkpoint (created by pause, consumed by resume) |
 
 ### Advisory Git Protocol

package/bin/gsdd.mjs

@@ -20,6 +20,7 @@ import { createCmdHealth } from './lib/health.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { cmdUiProof } from './lib/ui-proof.mjs';
+import { cmdControlMap } from './lib/control-map.mjs';
 import { resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -86,7 +87,6 @@ function createCliContext(cwd = process.cwd()) {
 }
 
 const INIT_CONTEXT = createCliContext(process.cwd());
-
 const cmdInit = createCmdInit(INIT_CONTEXT);
 const cmdHealth = createCmdHealth(INIT_CONTEXT);
 
@@ -109,6 +109,7 @@ const COMMANDS = {
   'lifecycle-preflight': cmdLifecyclePreflight,
   'session-fingerprint': cmdSessionFingerprint,
   'ui-proof': cmdUiProof,
+  'control-map': cmdControlMap,
   'find-phase': cmdFindPhase,
   'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
@@ -135,4 +136,4 @@ async function runCli(cliCommand = command, ...cliArgs) {
 }
 
 if (IS_MAIN) await runCli();
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdUiProof, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdUiProof, cmdControlMap, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/control-map.mjs

@@ -0,0 +1,629 @@
+// control-map.mjs - computed-first workspace/worktree control map
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { isAbsolute, join, relative, resolve } from 'path';
+import { spawnSync } from 'child_process';
+import { output, parseFlagValue } from './cli-utils.mjs';
+import { evaluateLifecycleState } from './lifecycle-state.mjs';
+import { checkDrift } from './session-fingerprint.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
+
+const DEFAULT_ANNOTATIONS_RELATIVE_PATH = '.planning/.local/control-map.annotations.json';
+const MAX_DIRTY_BUCKET_ENTRIES = 200;
+const CLEANUP_STATES = Object.freeze(['active', 'paused', 'merged', 'abandoned', 'superseded', 'cleanup_deferred']);
+const AUTHORITY_ORDER = Object.freeze([
+  'repo_truth',
+  'planning_artifacts',
+  'checkpoint_narrative',
+  'local_annotations',
+  'vendor_session_forensics',
+]);
+
+function runGit(cwd, args) {
+  const command = `git ${args.join(' ')}`;
+  try {
+    const result = spawnSync('git', args, {
+      cwd,
+      encoding: 'utf-8',
+      maxBuffer: 1024 * 1024 * 4,
+      timeout: 10000,
+    });
+    const errorMessage = result.error ? result.error.message : '';
+    return {
+      ok: result.status === 0 && !result.error,
+      status: result.status ?? (result.error ? -1 : null),
+      stdout: String(result.stdout || '').trimEnd(),
+      stderr: String(result.stderr || errorMessage || '').trimEnd(),
+      command,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: -1,
+      stdout: '',
+      stderr: error.message,
+      command,
+    };
+  }
+}
+
+function runIgnoredCount(cwd) {
+  const result = runGit(cwd, ['ls-files', '-o', '-i', '--exclude-standard']);
+  if (!result.ok) {
+    return {
+      ok: false,
+      count: 0,
+      error: result.stderr || result.stdout || 'git ls-files ignored count failed',
+    };
+  }
+
+  const count = result.stdout ? result.stdout.split('\n').filter(Boolean).length : 0;
+  return { ok: true, count };
+}
+
+function normalizeSlashes(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+function workspacePathLabel(workspaceRoot, targetPath) {
+  const absolute = resolve(targetPath);
+  const rel = relative(workspaceRoot, absolute);
+  if (rel === '') return '.';
+  if (!rel.startsWith('..') && !isAbsolute(rel)) return normalizeSlashes(rel);
+  return normalizeSlashes(absolute);
+}
+
+function isInsideOrSame(parentPath, targetPath) {
+  const rel = relative(resolve(parentPath), resolve(targetPath));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function safeReadJson(filePath) {
+  try {
+    return { ok: true, value: JSON.parse(readFileSync(filePath, 'utf-8')) };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+function parseStatusBuckets(statusOutput) {
+  const buckets = {
+    branch_line: null,
+    tracked: [],
+    untracked: [],
+    ignored: [],
+  };
+
+  for (const rawLine of String(statusOutput || '').split('\n')) {
+    const line = rawLine.trimEnd();
+    if (!line) continue;
+    if (line.startsWith('## ')) {
+      buckets.branch_line = line.slice(3);
+      continue;
+    }
+    const code = line.slice(0, 2);
+    const file = line.slice(3);
+    if (code === '??') buckets.untracked.push(file);
+    else if (code === '!!') buckets.ignored.push(file);
+    else buckets.tracked.push(line);
+  }
+
+  return buckets;
+}
+
+function capBucket(entries) {
+  return entries.length > MAX_DIRTY_BUCKET_ENTRIES ? entries.slice(0, MAX_DIRTY_BUCKET_ENTRIES) : entries;
+}
+
+function parseAheadBehind(branchLine) {
+  if (!branchLine) return { ahead: null, behind: null };
+  if (!branchLine.includes('...')) return { ahead: null, behind: null };
+  const ahead = branchLine.match(/ahead (\d+)/)?.[1];
+  const behind = branchLine.match(/behind (\d+)/)?.[1];
+  return {
+    ahead: ahead === undefined ? 0 : Number(ahead),
+    behind: behind === undefined ? 0 : Number(behind),
+  };
+}
+
+function readGitWorktree(pathValue, workspaceRoot, { includeIgnoredPaths = false, includeIgnoredCount = false } = {}) {
+  const status = runGit(pathValue, [
+    'status',
+    '--short',
+    '--branch',
+    ...(includeIgnoredPaths ? ['--ignored'] : []),
+    '--untracked-files=all',
+  ]);
+  const branch = runGit(pathValue, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const head = runGit(pathValue, ['rev-parse', 'HEAD']);
+  const gitTopLevel = runGit(pathValue, ['rev-parse', '--show-toplevel']);
+  const buckets = status.ok ? parseStatusBuckets(status.stdout) : parseStatusBuckets('');
+  const ignoredCountResult = includeIgnoredCount && !includeIgnoredPaths ? runIgnoredCount(pathValue) : null;
+  const ignoredEntries = includeIgnoredPaths ? capBucket(buckets.ignored) : [];
+  const ignoredCount = includeIgnoredPaths
+    ? buckets.ignored.length
+    : ignoredCountResult && ignoredCountResult.ok
+      ? ignoredCountResult.count
+      : null;
+
+  return {
+    id: workspacePathLabel(workspaceRoot, pathValue),
+    path: normalizeSlashes(resolve(pathValue)),
+    path_relative: workspacePathLabel(workspaceRoot, pathValue),
+    path_inside_workspace: isInsideOrSame(workspaceRoot, pathValue),
+    git_valid: status.ok && branch.ok && head.ok,
+    branch: branch.ok ? branch.stdout : null,
+    head: head.ok ? head.stdout : null,
+    git_top_level: gitTopLevel.ok ? normalizeSlashes(resolve(gitTopLevel.stdout)) : null,
+    dirty: {
+      tracked: capBucket(buckets.tracked),
+      untracked: capBucket(buckets.untracked),
+      ignored: ignoredEntries,
+      counts: {
+        tracked: buckets.tracked.length,
+        untracked: buckets.untracked.length,
+        ignored: ignoredCount,
+      },
+      omitted_counts: {
+        tracked: Math.max(0, buckets.tracked.length - MAX_DIRTY_BUCKET_ENTRIES),
+        untracked: Math.max(0, buckets.untracked.length - MAX_DIRTY_BUCKET_ENTRIES),
+        ignored: includeIgnoredPaths ? Math.max(0, buckets.ignored.length - MAX_DIRTY_BUCKET_ENTRIES) : null,
+      },
+      ignored_paths_included: includeIgnoredPaths,
+      ignored_count_included: includeIgnoredPaths || Boolean(ignoredCountResult),
+      ignored_count_error: ignoredCountResult && !ignoredCountResult.ok ? ignoredCountResult.error : null,
+    },
+    ahead_behind: parseAheadBehind(buckets.branch_line),
+    status_error: status.ok ? null : [status.stderr, status.stdout].filter(Boolean).join('\n') || 'git status failed',
+  };
+}
+
+function parseWorktreeList(outputText) {
+  const entries = [];
+  let current = null;
+
+  for (const line of String(outputText || '').split('\n')) {
+    if (!line.trim()) {
+      if (current) entries.push(current);
+      current = null;
+      continue;
+    }
+    const [key, ...rest] = line.split(' ');
+    const value = rest.join(' ');
+    if (key === 'worktree') {
+      if (current) entries.push(current);
+      current = { path: value, detached: false, bare: false };
+      continue;
+    }
+    if (!current) continue;
+    if (key === 'HEAD') current.head = value;
+    else if (key === 'branch') current.branch_ref = value;
+    else if (key === 'detached') current.detached = true;
+    else if (key === 'bare') current.bare = true;
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+
+function discoverGitWorktrees(workspaceRoot, { includeIgnoredPaths = false, includeIgnoredCount = false } = {}) {
+  const listed = runGit(workspaceRoot, ['worktree', 'list', '--porcelain']);
+  if (!listed.ok) {
+    return {
+      git_available: false,
+      worktrees: [readGitWorktree(workspaceRoot, workspaceRoot, { includeIgnoredPaths, includeIgnoredCount: includeIgnoredCount || includeIgnoredPaths })],
+      errors: [{ code: 'git_worktree_list_failed', message: listed.stderr || listed.stdout || 'git worktree list failed' }],
+    };
+  }
+
+  const rawEntries = parseWorktreeList(listed.stdout);
+  const paths = rawEntries.length > 0 ? rawEntries.map((entry) => entry.path) : [workspaceRoot];
+  const byPath = new Map(rawEntries.map((entry) => [resolve(entry.path), entry]));
+  return {
+    git_available: true,
+    worktrees: paths.map((pathValue) => {
+      const isCanonical = resolve(pathValue) === resolve(workspaceRoot);
+      const computed = readGitWorktree(pathValue, workspaceRoot, {
+        includeIgnoredPaths,
+        includeIgnoredCount: includeIgnoredPaths || (isCanonical && includeIgnoredCount),
+      });
+      const raw = byPath.get(resolve(pathValue)) || {};
+      return {
+        ...computed,
+        branch_ref: raw.branch_ref || null,
+        detached: raw.detached === true || computed.branch === 'HEAD',
+        bare: raw.bare === true,
+      };
+    }),
+    errors: [],
+  };
+}
+
+function discoverRuntimeDirs(workspaceRoot) {
+  const candidates = [
+    { runtime: 'claude-code', rel: '.claude/worktrees' },
+    { runtime: 'codex-cli', rel: '.codex/worktrees' },
+    { runtime: 'opencode', rel: '.opencode/worktrees' },
+  ];
+  const dirs = [];
+  for (const candidate of candidates) {
+    const root = join(workspaceRoot, candidate.rel);
+    if (!existsSync(root)) continue;
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const fullPath = join(root, entry.name);
+      const dotGit = join(fullPath, '.git');
+      dirs.push({
+        runtime: candidate.runtime,
+        path: normalizeSlashes(fullPath),
+        path_relative: normalizeSlashes(join(candidate.rel, entry.name)),
+        git_marker_exists: existsSync(dotGit),
+        appears_git_worktree: existsSync(dotGit),
+      });
+    }
+  }
+  return dirs;
+}
+
+function normalizeAnnotationPath(workspaceRoot, annotation) {
+  const raw = annotation.path || annotation.worktree_path || annotation.path_relative;
+  if (!raw) return null;
+  return normalizeSlashes(resolve(workspaceRoot, raw));
+}
+
+function loadAnnotations(workspaceRoot, planningDir, annotationPathArg = null) {
+  const annotationPath = annotationPathArg
+    ? resolve(workspaceRoot, annotationPathArg)
+    : join(planningDir, '.local', 'control-map.annotations.json');
+  if (!isInsideOrSame(workspaceRoot, annotationPath)) {
+    return {
+      path: workspacePathLabel(workspaceRoot, annotationPath),
+      exists: false,
+      valid: false,
+      errors: [{
+        code: 'annotations_path_outside_workspace',
+        path: workspacePathLabel(workspaceRoot, annotationPath),
+        message: 'Control-map annotations path must stay inside the workspace.',
+      }],
+      worktrees: [],
+    };
+  }
+  if (!existsSync(annotationPath)) {
+    return {
+      path: workspacePathLabel(workspaceRoot, annotationPath),
+      exists: false,
+      valid: true,
+      errors: [],
+      worktrees: [],
+    };
+  }
+
+  const parsed = safeReadJson(annotationPath);
+  if (!parsed.ok) {
+    return {
+      path: workspacePathLabel(workspaceRoot, annotationPath),
+      exists: true,
+      valid: false,
+      errors: [{ code: 'invalid_annotations_json', path: workspacePathLabel(workspaceRoot, annotationPath), message: parsed.error }],
+      worktrees: [],
+    };
+  }
+
+  const rawWorktrees = Array.isArray(parsed.value?.worktrees)
+    ? parsed.value.worktrees
+    : Array.isArray(parsed.value?.annotations)
+      ? parsed.value.annotations
+      : [];
+  const errors = [];
+  if (!parsed.value || typeof parsed.value !== 'object' || Array.isArray(parsed.value)) {
+    errors.push({ code: 'invalid_annotations_shape', path: workspacePathLabel(workspaceRoot, annotationPath), message: 'Control-map annotations must be a JSON object.' });
+  }
+  if (rawWorktrees.length === 0 && parsed.value?.worktrees !== undefined && !Array.isArray(parsed.value.worktrees)) {
+    errors.push({ code: 'invalid_worktrees_annotations', path: `${workspacePathLabel(workspaceRoot, annotationPath)}.worktrees`, message: 'worktrees must be an array.' });
+  }
+
+  const worktrees = rawWorktrees.filter((entry, index) => {
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) return true;
+    errors.push({ code: 'invalid_annotation', path: `worktrees[${index}]`, message: 'Annotation entries must be objects.' });
+    return false;
+  }).map((entry, index) => ({
+    id: entry.id || `annotation-${index + 1}`,
+    runtime_owner: entry.runtime_owner || entry.runtime || null,
+    path: entry.path || entry.worktree_path || null,
+    path_relative: entry.path_relative || null,
+    normalized_path: normalizeAnnotationPath(workspaceRoot, entry),
+    branch: entry.branch || null,
+    last_known_head: entry.last_known_head || entry.head || null,
+    intended_scope: entry.intended_scope || entry.scope || null,
+    write_set: Array.isArray(entry.write_set) ? entry.write_set : [],
+    cleanup_state: entry.cleanup_state || 'active',
+    proof_state: entry.proof_state || null,
+    next_step: entry.next_step || null,
+    updated_at: entry.updated_at || null,
+  }));
+
+  for (const [index, entry] of worktrees.entries()) {
+    if (!entry.normalized_path) errors.push({ code: 'missing_annotation_path', path: `worktrees[${index}].path`, message: 'Annotation must include path or path_relative.' });
+    if (!CLEANUP_STATES.includes(entry.cleanup_state)) {
+      errors.push({
+        code: 'invalid_cleanup_state',
+        path: `worktrees[${index}].cleanup_state`,
+        message: `Unsupported cleanup_state: ${entry.cleanup_state}`,
+      });
+    }
+  }
+
+  return {
+    path: workspacePathLabel(workspaceRoot, annotationPath),
+    exists: true,
+    valid: errors.length === 0,
+    errors,
+    worktrees,
+  };
+}
+
+function reconcileAnnotations(worktrees, annotations) {
+  const warnings = [];
+  const byPath = new Map(worktrees.map((entry) => [normalizeSlashes(resolve(entry.path)), entry]));
+  const attached = new Map();
+
+  for (const annotation of annotations.worktrees) {
+    const worktree = annotation.normalized_path ? byPath.get(annotation.normalized_path) : null;
+    if (!worktree) {
+      warnings.push({
+        code: 'stale_annotation_missing_worktree',
+        severity: 'warn',
+        message: `Annotation ${annotation.id} points at a missing or unlisted worktree.`,
+        annotation_id: annotation.id,
+      });
+      continue;
+    }
+    attached.set(worktree.path, annotation);
+    if (annotation.branch && worktree.branch && annotation.branch !== worktree.branch) {
+      warnings.push({
+        code: 'stale_annotation_branch_mismatch',
+        severity: 'warn',
+        message: `Annotation ${annotation.id} branch ${annotation.branch} does not match live branch ${worktree.branch}.`,
+        annotation_id: annotation.id,
+        worktree_id: worktree.id,
+      });
+    }
+    if (annotation.last_known_head && worktree.head && annotation.last_known_head !== worktree.head) {
+      warnings.push({
+        code: 'stale_annotation_head_mismatch',
+        severity: 'warn',
+        message: `Annotation ${annotation.id} last_known_head does not match live HEAD.`,
+        annotation_id: annotation.id,
+        worktree_id: worktree.id,
+      });
+    }
+  }
+
+  return {
+    worktrees: worktrees.map((worktree) => ({
+      ...worktree,
+      annotation: attached.get(worktree.path) || null,
+    })),
+    warnings,
+  };
+}
+
+function classifyWorkflowState(planningDir) {
+  const lifecycle = evaluateLifecycleState({ planningDir });
+  const checkpointPath = join(planningDir, '.continue-here.md');
+  const drift = existsSync(planningDir) ? checkDrift(planningDir) : { drifted: false, details: [] };
+  const milestoneVersion = lifecycle.currentMilestone?.version || null;
+  const milestoneTitle = lifecycle.currentMilestone?.title || null;
+  const milestone = milestoneVersion || milestoneTitle
+    ? { version: milestoneVersion, title: milestoneTitle }
+    : null;
+  return {
+    current_milestone: milestone,
+    current_phase: lifecycle.currentPhase?.number || null,
+    next_phase: lifecycle.nextPhase?.number || null,
+    non_phase_state: lifecycle.nonPhaseState || null,
+    checkpoint: {
+      exists: existsSync(checkpointPath),
+      path: '.planning/.continue-here.md',
+    },
+    planning_drift: {
+      drifted: drift.drifted,
+      details: drift.details || [],
+    },
+  };
+}
+
+function buildRisks({ canonical, worktrees, annotations, runtimeDirs, workflowState, gitErrors }) {
+  const risks = [];
+  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'}` });
+  }
+  if (canonical.dirty.counts.tracked > 0 || canonical.dirty.counts.untracked > 0) {
+    risks.push({
+      code: 'canonical_dirty',
+      severity: 'warn',
+      message: `Canonical worktree has tracked/untracked changes (${canonical.dirty.counts.tracked} tracked, ${canonical.dirty.counts.untracked} untracked).`,
+    });
+  }
+  if (canonical.dirty.counts.ignored > 0) {
+    risks.push({
+      code: 'ignored_local_surfaces_present',
+      severity: 'info',
+      message: `Canonical worktree has ${canonical.dirty.counts.ignored} ignored local surface(s); do not describe the workspace as simply clean.`,
+    });
+  }
+  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.` });
+    }
+    if (worktree.dirty.counts.tracked > 0 || worktree.dirty.counts.untracked > 0) {
+      risks.push({
+        code: 'sibling_worktree_dirty',
+        severity: 'warn',
+        worktree_id: worktree.id,
+        message: `Sibling worktree ${worktree.id} has tracked/untracked changes.`,
+      });
+    }
+    if (!worktree.annotation && (worktree.dirty.counts.tracked > 0 || worktree.dirty.counts.untracked > 0 || worktree.detached)) {
+      risks.push({
+        code: 'unannotated_candidate_worktree',
+        severity: 'info',
+        worktree_id: worktree.id,
+        message: `Worktree ${worktree.id} has candidate-work signals but no local control-map annotation.`,
+      });
+    }
+  }
+  for (const warning of annotations.warnings || []) risks.push(warning);
+  for (const error of annotations.errors || []) {
+    risks.push({ code: error.code, severity: 'warn', message: error.message, path: error.path });
+  }
+  for (const runtimeDir of runtimeDirs.filter((entry) => !entry.appears_git_worktree)) {
+    risks.push({
+      code: 'orphan_runtime_dir',
+      severity: 'info',
+      message: `${runtimeDir.runtime} local directory is not a git worktree: ${runtimeDir.path_relative}`,
+      path: runtimeDir.path_relative,
+    });
+  }
+  if (workflowState.planning_drift.drifted) {
+    risks.push({
+      code: 'planning_state_drift',
+      severity: 'warn',
+      message: `Planning state drifted since the last fingerprint: ${workflowState.planning_drift.details.join('; ')}`,
+    });
+  }
+  return risks;
+}
+
+function buildInterventions(risks) {
+  const codes = new Set(risks.map((risk) => risk.code));
+  const interventions = [];
+  if (codes.has('canonical_git_invalid')) interventions.push('Fix git/safe.directory access before mutating this checkout.');
+  if (codes.has('canonical_dirty')) interventions.push('Checkpoint or classify canonical dirty work before planning, cleanup, merge, or broad execution.');
+  if (codes.has('sibling_worktree_dirty') || codes.has('unannotated_candidate_worktree')) interventions.push('Review sibling worktree ownership and write set before starting overlapping implementation.');
+  if (codes.has('stale_annotation_missing_worktree') || codes.has('stale_annotation_branch_mismatch') || codes.has('stale_annotation_head_mismatch')) interventions.push('Refresh or remove stale local control-map annotations after reviewing repo truth.');
+  if (codes.has('planning_state_drift')) interventions.push('Review planning drift and rebaseline with session-fingerprint only after confirming the changes are intentional.');
+  if (interventions.length === 0) interventions.push('No control-map intervention required before read-only status work.');
+  return interventions;
+}
+
+export function buildControlMap({
+  workspaceRoot,
+  planningDir,
+  annotationPath = null,
+  includeIgnoredPaths = false,
+  now = new Date(),
+} = {}) {
+  const root = resolve(workspaceRoot || process.cwd());
+  const planning = planningDir || join(root, '.planning');
+  const discovered = discoverGitWorktrees(root, { includeIgnoredPaths, includeIgnoredCount: includeIgnoredPaths });
+  const annotations = loadAnnotations(root, planning, annotationPath);
+  const reconciled = reconcileAnnotations(discovered.worktrees, annotations);
+  const canonical = reconciled.worktrees.find((entry) => resolve(entry.path) === root)
+    || reconciled.worktrees[0]
+    || readGitWorktree(root, root, { includeIgnoredCount: true });
+  const workflowState = classifyWorkflowState(planning);
+  const runtimeDirs = discoverRuntimeDirs(root);
+  const annotationReport = {
+    path: annotations.path,
+    exists: annotations.exists,
+    valid: annotations.valid,
+    errors: annotations.errors,
+    warnings: reconciled.warnings,
+  };
+  const risks = buildRisks({
+    canonical,
+    worktrees: reconciled.worktrees,
+    annotations: annotationReport,
+    runtimeDirs,
+    workflowState,
+    gitErrors: discovered.errors,
+  });
+
+  return {
+    schema_version: 1,
+    generated_at: now.toISOString(),
+    operation: 'control-map',
+    repo_root_id: canonical.git_top_level || normalizeSlashes(root),
+    workspace_root: normalizeSlashes(root),
+    default_annotations_path: DEFAULT_ANNOTATIONS_RELATIVE_PATH,
+    authority: AUTHORITY_ORDER,
+    canonical_worktree: canonical,
+    worktrees: reconciled.worktrees,
+    workflow_state: workflowState,
+    annotations: annotationReport,
+    runtime_dirs: runtimeDirs,
+    risks,
+    interventions: buildInterventions(risks),
+  };
+}
+
+function printHuman(map) {
+  const milestone = map.workflow_state.current_milestone
+    ? [map.workflow_state.current_milestone.version, map.workflow_state.current_milestone.title].filter(Boolean).join(' ')
+    : 'none';
+  const ignoredLabel = map.canonical_worktree.dirty.ignored_count_included
+    ? String(map.canonical_worktree.dirty.counts.ignored)
+    : 'not scanned';
+  console.log('gsdd control-map - computed workspace control map\n');
+  console.log(`Workspace: ${map.workspace_root}`);
+  console.log(`Authority: ${map.authority.join(' > ')}`);
+  console.log(`Canonical: ${map.canonical_worktree.branch || 'unknown'} @ ${map.canonical_worktree.head || 'unknown'}`);
+  console.log(`Workflow: milestone=${milestone}, phase=${map.workflow_state.current_phase || 'none'}, next=${map.workflow_state.next_phase || 'none'}`);
+  console.log(`Checkpoint: ${map.workflow_state.checkpoint.path} (${map.workflow_state.checkpoint.exists ? 'present' : 'missing'})`);
+  console.log(`Dirty buckets: ${map.canonical_worktree.dirty.counts.tracked} tracked, ${map.canonical_worktree.dirty.counts.untracked} untracked, ${ignoredLabel} ignored`);
+  console.log(`Worktrees: ${map.worktrees.length}`);
+  for (const worktree of map.worktrees) {
+    const marker = worktree.path === map.canonical_worktree.path ? '*' : '-';
+    const annotation = worktree.annotation ? ` owner=${worktree.annotation.runtime_owner || 'unspecified'} cleanup=${worktree.annotation.cleanup_state}` : '';
+    const ignoredCount = worktree.dirty.ignored_count_included ? String(worktree.dirty.counts.ignored) : 'not-scanned';
+    console.log(`  ${marker} ${worktree.id} branch=${worktree.branch || 'unknown'} dirty=${worktree.dirty.counts.tracked}/${worktree.dirty.counts.untracked}/${ignoredCount}${annotation}`);
+  }
+  if (map.risks.length > 0) {
+    console.log('\nRisks:');
+    for (const risk of map.risks) console.log(`  - [${risk.severity || 'info'}] ${risk.code}: ${risk.message}`);
+  }
+  console.log('\nInterventions:');
+  for (const intervention of map.interventions) console.log(`  - ${intervention}`);
+}
+
+export function cmdControlMap(...args) {
+  const jsonMode = args.includes('--json');
+  const contextArgs = args.filter((arg) => arg !== '--json');
+  const context = resolveWorkspaceContext(contextArgs);
+  if (context.invalid) {
+    console.error(context.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const annotations = parseFlagValue(context.args, '--annotations');
+  if (annotations.invalid) {
+    console.error('Usage: gsdd control-map [--json] [--with-ignored] [--annotations <path>]');
+    process.exitCode = 1;
+    return;
+  }
+  const filteredArgs = context.args.filter((arg, index) => {
+    if (arg === '--annotations') return false;
+    if (index > 0 && context.args[index - 1] === '--annotations') return false;
+    if (arg === '--with-ignored') return false;
+    return true;
+  });
+  if (filteredArgs.length > 0) {
+    console.error('Usage: gsdd control-map [--json] [--with-ignored] [--annotations <path>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const includeIgnoredPaths = context.args.includes('--with-ignored');
+  const map = buildControlMap({
+    workspaceRoot: context.workspaceRoot,
+    planningDir: context.planningDir,
+    annotationPath: annotations.value,
+    includeIgnoredPaths,
+  });
+  if (jsonMode) output(map);
+  else printHuman(map);
+}