gsdd-cli 0.22.0 → 0.23.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);
+}

package/bin/lib/init-flow.mjs

@@ -100,6 +100,7 @@ export function createCmdInit(ctx) {
       promptApi,
       preselectedConfig: interactiveSession.config,
     });
+    ensureGitignoreEntry(ctx.cwd, '.planning/.local/', '  - ensured .planning/.local/ is gitignored');
 
     if (briefSource) {
       cpSync(briefSource, join(ctx.planningDir, 'PROJECT_BRIEF.md'));
@@ -273,7 +274,7 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
   if (preselectedConfig) {
     writeFileSync(configFile, JSON.stringify(preselectedConfig, null, 2));
     console.log('  - saved .planning/config.json (guided wizard)\n');
-    if (!preselectedConfig.commitDocs) ensureGitignoreEntry(cwd);
+    if (!preselectedConfig.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
     return;
   }
 
@@ -281,7 +282,7 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
     const config = buildDefaultConfig({ autoAdvance: true });
     writeFileSync(configFile, JSON.stringify(config, null, 2));
     console.log('  - wrote .planning/config.json (auto defaults)\n');
-    if (!config.commitDocs) ensureGitignoreEntry(cwd);
+    if (!config.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
     return;
   }
 
@@ -289,7 +290,7 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
     const config = buildDefaultConfig({ autoAdvance: false });
     writeFileSync(configFile, JSON.stringify(config, null, 2));
     console.log('  - wrote .planning/config.json (non-interactive defaults)\n');
-    if (!config.commitDocs) ensureGitignoreEntry(cwd);
+    if (!config.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
     return;
   }
 
@@ -303,18 +304,17 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
 
   writeFileSync(configFile, JSON.stringify(selected, null, 2));
   console.log('  - saved .planning/config.json (guided wizard)\n');
-  if (!selected.commitDocs) ensureGitignoreEntry(cwd);
+  if (!selected.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
 }
 
-function ensureGitignoreEntry(cwd) {
+function ensureGitignoreEntry(cwd, entry, message) {
   const gitignorePath = join(cwd, '.gitignore');
-  const entry = '.planning/';
   const hasGitignore = existsSync(gitignorePath);
   const current = hasGitignore ? readFileSync(gitignorePath, 'utf-8') : '';
   if (!current.split(/\r?\n/).includes(entry)) {
     const next = current.trimEnd() ? `${current.trimEnd()}\n${entry}\n` : `${entry}\n`;
     writeFileSync(gitignorePath, next);
-    console.log('  - ensured .planning/ is gitignored');
+    console.log(message);
   }
 }
 

package/bin/lib/init-runtime.mjs

@@ -192,6 +192,8 @@ Commands:
                               Validate UI proof metadata; use --claim for stronger proof uses
   ui-proof compare <planned-slots-json> [observed-bundle-json ...]
                               Compare planned UI proof slots against observed bundles
+  control-map [--json] [--with-ignored] [--annotations <path>]
+                              Report computed repo/worktree/planning state and local annotations
   help                        Show this summary
 
 Platforms (for --tools):
@@ -263,6 +265,7 @@ 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
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/rendering.mjs

@@ -7,6 +7,7 @@ const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', '..', 'distilled');
 const HELPER_LIB_FILES = Object.freeze([
   'cli-utils.mjs',
+  'control-map.mjs',
   'evidence-contract.mjs',
   'file-ops.mjs',
   'lifecycle-preflight.mjs',
@@ -49,6 +50,7 @@ import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdPhaseStatus } from './lib/phase.mjs';
 import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { cmdUiProof } from './lib/ui-proof.mjs';
+import { cmdControlMap } from './lib/control-map.mjs';
 import { bootstrapHelperWorkspace, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const COMMANDS = {
@@ -57,6 +59,7 @@ const COMMANDS = {
   'phase-status': cmdPhaseStatus,
   'session-fingerprint': cmdSessionFingerprint,
   'ui-proof': cmdUiProof,
+  'control-map': cmdControlMap,
 };
 
 function printHelp() {
@@ -78,6 +81,8 @@ function printHelp() {
     '                               Validate UI proof metadata; use --claim for stronger proof uses',
     '  ui-proof compare <planned-slots-json> [observed-bundle-json ...]',
     '                               Compare planned UI proof slots against observed bundles',
+    '  control-map [--json] [--with-ignored] [--annotations <path>]',
+    '                               Report computed repo/worktree/planning state and local annotations',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',

package/distilled/DESIGN.md

@@ -73,6 +73,7 @@
 60. [Release Closeout Contract](#d60---release-closeout-contract)
 61. [Deliberate Subagent Contract](#d61---deliberate-subagent-contract)
 62. [Repo-Native UI Proof Contract](#d62---repo-native-ui-proof-contract)
+63. [Computed-First Control Map](#d63---computed-first-control-map)
 
 ---
 
@@ -2872,6 +2873,44 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 - Generated runtime surfaces and local templates must stay freshness-checkable through `gsdd update --templates` and health diagnostics.
 - Future provider/tooling work must not make `agent-browser` a required validator field without a separate product decision; the current contract makes it the default workflow path, not a schema lock.
 
+## D63 - Computed-First Control Map
+
+**Decision (2026-05-08):** Long-running multi-agent and multi-worktree control uses a computed-first `gsdd control-map` helper rather than a new lifecycle workflow or a vendor session parser. The helper computes repo/worktree/planning truth live and overlays optional local annotations only for intent that git cannot know.
+
+**Context:**
+- Gap I52 showed that ordinary `git status` can be clean while sibling worktrees, detached runtime worktrees, ignored/generated surfaces, snapshots, dirty local WIP, and cleanup obligations remain unexplained.
+- Gap I54 showed that repeated subagent swarms can become a substitute for shared state when there is no one-screen control map for active branches, ownership, proof state, and cleanup debt.
+- Current runtime research shows the only portable cross-vendor coordination layer is repo artifacts plus generated workflow entrypoints. Claude, OpenCode, Codex, Cursor, Copilot, and Gemini do not expose one uniform authoritative session/worktree store.
+- Current harness guidance favors structured handoff artifacts, worktree isolation, evaluator loops, approval gates around side effects, and browser/runtime evidence. Those ideas fit Workspine only if repo truth remains primary and vendor adapters stay thin.
+
+**Decision:**
+- Add `gsdd control-map [--json] [--with-ignored] [--annotations <path>]` to the main CLI and generated `.planning/bin/gsdd.mjs` helper runtime.
+- Compute authority from live git/worktree state first: canonical checkout, branch, HEAD, upstream divergence when comparable, tracked/untracked dirty buckets, optional ignored-path scans through `--with-ignored`, sibling git worktrees, detached/bare state, invalid git access, planning drift, checkpoint existence, lifecycle state, and repo-local runtime worktree directories.
+- Read optional annotations from `.planning/.local/control-map.annotations.json`. Annotations may record `runtime_owner`, intended scope, write set, cleanup state, proof state, next step, branch, and last known head.
+- Treat annotations as stale-checkable intent only. They never outrank repo truth, planning artifacts, or checkpoint reconciliation.
+- Keep transcript/session stores out of the helper. Vendor session evidence may support postmortems, but it is not live product truth.
+- Wire the control map into portable workflow behavior by having `progress`, `resume`, `pause`, `quick`, `plan`, and `execute` consult it when available. This is guidance plus deterministic helper output, not a new workflow lane.
+
+**Leverage:**
+- Lost: a pure zero-file model cannot preserve non-computable intent such as owner/runtime, intended scope, and cleanup obligation.
+- Kept: Workspine remains a lightweight repo-native spine; no new lifecycle workflow, no dashboard/control plane, no vendor session authority, and no change to the five evidence kinds.
+- Gained: agents can explain "clean" precisely across tracked, untracked, sibling, detached, stale, and annotated state by default, and across ignored/generated local surfaces when the caller requests the explicit `--with-ignored` scan before planning, execution, resume, cleanup, or milestone continuation.
+
+**Evidence:**
+- `bin/lib/control-map.mjs`, `bin/gsdd.mjs`, `bin/lib/rendering.mjs`
+- `distilled/workflows/progress.md`, `resume.md`, `pause.md`, `quick.md`, `plan.md`, `execute.md`
+- `tests/gsdd.control-map.test.cjs`
+- `.internal-research/gaps.md` Gap I52 and Gap I54
+- `.internal-research/lessons-learned.md` entries on multi-worktree registry, clean-vs-editor-visible noise, checkpoint/worktree truth split, and subagent stop conditions
+- GSD comparison: upstream GSD preserves lifecycle rigor but does not define a vendor-agnostic computed worktree/control-map helper.
+- OpenSpec comparison: OpenSpec optimizes change-level speed and archive flow, but does not own long-running multi-worktree local-state reconciliation as a portable harness surface.
+- Harness sources: `https://www.anthropic.com/engineering/harness-design-long-running-apps`, `https://code.claude.com/docs/en/worktrees`, `https://developers.openai.com/codex/cloud`, `https://developers.openai.com/api/docs/guides/agents/orchestration`, `https://developers.openai.com/api/docs/guides/agents/guardrails-approvals`, `https://developers.openai.com/api/docs/guides/agent-evals`, `https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent`, `https://agent-browser.dev/sessions`, and `https://developer.chrome.com/docs/devtools/agents`.
+
+**Consequences:**
+- Future cleanup, resume, and parallel-worktree work should start from `gsdd control-map --json` rather than repeated ad hoc repo audits; use `--with-ignored` before making a clean-workspace claim that includes ignored or generated surfaces.
+- A future mutation command may update annotations, but the current helper intentionally stays computed/read-first and safe to call from status surfaces.
+- Future health or preflight hardening can consume the same helper output for stricter blocking, but must avoid turning local annotations into product truth.
+
 ---
 
 ## Maintenance

package/distilled/EVIDENCE-INDEX.md

@@ -505,6 +505,16 @@
 - Long-term pitfalls carried forward: do not accept screenshot-free "looks good" claims, weak planned slots, unverified artifact paths, stale interactive refs after page mutation, partial/failed proof without failure classification, raw artifact publication without privacy metadata, browser contention in parallel checks, or semantic/selector-poor UI that forces fragile coordinate inspection.
 - Supporting spec/runtime docs: https://openspec.dev/, https://www.lean-spec.dev/docs/guide/first-principles, https://help.openai.com/en/articles/11369540-codex-in-chatgpt, https://docs.claude.com/en/docs/agents-and-tools/agent-skills, https://docs.github.com/en/copilot/concepts/prompting/response-customization
 
+## D63 — Computed-First Control Map
+- `bin/lib/control-map.mjs`, `bin/gsdd.mjs`, `bin/lib/rendering.mjs`
+- `distilled/workflows/progress.md`, `resume.md`, `pause.md`, `quick.md`, `plan.md`, `execute.md`
+- `tests/gsdd.control-map.test.cjs`
+- `.internal-research/gaps.md` Gap I52 and Gap I54
+- `.internal-research/lessons-learned.md` multi-worktree registry, clean-vs-editor-visible noise, checkpoint/worktree truth split, and subagent stop-condition lessons
+- GSD comparison: upstream GSD lifecycle rigor does not include a vendor-agnostic computed worktree/control-map helper
+- OpenSpec comparison: OpenSpec change archive flow does not own long-running multi-worktree local-state reconciliation as a portable harness surface
+- Harness sources: https://www.anthropic.com/engineering/harness-design-long-running-apps, https://code.claude.com/docs/en/worktrees, https://developers.openai.com/codex/cloud, https://developers.openai.com/api/docs/guides/agents/orchestration, https://developers.openai.com/api/docs/guides/agents/guardrails-approvals, https://developers.openai.com/api/docs/guides/agent-evals, https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent, https://agent-browser.dev/sessions, https://developer.chrome.com/docs/devtools/agents
+
 ---
 
 ## Maintenance

package/distilled/README.md

@@ -71,6 +71,14 @@ npx -y gsdd-cli init       -> bootstrap (create .planning/, copy templates, gene
 /gsdd-progress             -> show status, route to next action
 ```
 
+The main operator spine is four workflow moves after bootstrap: `new-project -> plan -> execute -> verify`. The other public workflow surfaces are support lanes for milestone closeout, quick work, progress, pause/resume, and brownfield orientation.
+
+Helper command for long-running sessions:
+
+```
+npx -y gsdd-cli control-map [--json] [--with-ignored] -> computed repo/worktree/planning state plus local annotations
+```
+
 ## Brownfield Entry Contract
 
 Use the same three-way routing everywhere:
@@ -101,6 +109,7 @@ Use the same three-way routing everywhere:
 Architecture notes:
 - `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
 - Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path, relies on `.planning/bin/gsdd.mjs` for deterministic helper calls, and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
+- `control-map` is a helper command, not a lifecycle workflow: it computes repo/worktree/planning truth first and treats `.planning/.local/` annotations as local intent only.
 - Codex VS Code/app are separate surfaces from Codex CLI; do not claim the CLI proof for them unless they expose compatible skill discovery. Fallback is opening or pasting the generated `SKILL.md`.
 - `npx -y gsdd-cli health` now compares any installed generated runtime surfaces against current render output and routes repairs back through `npx -y gsdd-cli update`.
 - Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.

package/distilled/workflows/execute.md

@@ -1,8 +1,7 @@
 <role>
 You are the EXECUTOR. Your job is to implement the tasks from a phase plan with precision and discipline.
 
-You follow the plan. You verify before reporting completion. You document deviations.
-You DO NOT freelance. You DO NOT add features outside the plan.
+You follow the plan, verify before reporting completion, document deviations, and DO NOT freelance or add features outside the plan.
 </role>
 
 <load_context>
@@ -36,7 +35,8 @@ Treat the preflight as an authorization seam over shared repo truth only:
 - it does not mutate `.planning/ROADMAP.md` by itself
 - owned writes remain execution artifacts, and ROADMAP mutation stays explicit in `<state_updates>` via `node .planning/bin/gsdd.mjs phase-status`
 </lifecycle_preflight>
-
+<control_map_check>Before code mutation, run `node .planning/bin/gsdd.mjs control-map --json` when available. Confirm the intended execution surface, dirty buckets, sibling/detached worktrees, and overlapping write-set risk. If it reports stale annotations, dubious git access, dirty out-of-plan canonical files, or unannotated dirty sibling worktrees, stop or ask for explicit acknowledgement before broad writes. Local annotations are intent hints only; computed repo/worktree truth stays primary.
+</control_map_check>
 <runtime_contract>
 Execution uses the same `Runtime` and `Assurance` types as planning and verification.
 Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.

package/distilled/workflows/pause.md

@@ -39,6 +39,8 @@ Store the detected work type as `$WORK_TYPE` (one of: `phase`, `quick`, `generic
 <gather_state>
 Build a draft checkpoint from artifact truth before asking the user to restate work. The user should correct the draft, not rewrite obvious repo state from scratch.
 
+When available, run `node .planning/bin/gsdd.mjs control-map --json` and use it as the draft's repo/worktree snapshot: canonical branch/HEAD, dirty tracked/untracked/ignored buckets, sibling/detached worktrees, stale annotations, planning drift, and recommended interventions. Include only a compact summary or pointer in `.planning/.continue-here.md`; the checkpoint records resumability context, not a replacement for future computed repo truth.
+
 Ask the user conversationally to fill in the gaps the artifacts cannot answer:
 
 1. **What was completed** this session

package/distilled/workflows/plan.md

@@ -32,12 +32,12 @@ If the preflight result is `blocked`, STOP and report the blocker instead of inf
 
 <integration_surface_check>
 Before planning roadmap work, inspect the live integration surface separately from checkpoint or planning artifacts:
-- current branch name
-- divergence from `main` when available
-- staged, unstaged, and untracked local truth
-- whether the current branch appears stale/spent or mixed-scope
+- Run `node .planning/bin/gsdd.mjs control-map --json` when available.
+- Use its computed branch/HEAD, divergence, tracked/untracked/ignored buckets, sibling/detached worktrees, local annotations, and interventions.
+- If the helper is unavailable, fall back to direct git/worktree inspection.
 
-If the planning truth says "next phase is X" but the git/worktree truth says the current branch is a stale or mixed execution surface, warn explicitly and treat the dirty branch as evidence only. Do not silently assume the checked-out branch is the right planning surface just because it exists.
+If the planning truth says "next phase is X" but the git/worktree truth says the current branch is a stale/spent or mixed-scope execution surface, warn explicitly and treat the dirty branch as evidence only. Do not silently assume the checked-out branch is the right planning surface just because it exists.
+Local annotations explain operator intent but do not outrank repo truth, planning artifacts, or checkpoint reconciliation.
 </integration_surface_check>
 
 <runtime_contract>

package/distilled/workflows/progress.md

@@ -6,6 +6,10 @@ Core mindset: derive state from primary artifacts. ROADMAP.md checkboxes, phase
 Scope boundary: you are NOT resume.md. You do not wait for user input, clean up checkpoints, present interactive menus, or trigger any action. You report and suggest only.
 </role>
 
+<control_map>
+At the start of status reporting, run `node .planning/bin/gsdd.mjs control-map --json` when the local helper exists. Summarize its computed repo/worktree/planning state in the status block: canonical branch/HEAD, tracked/untracked dirty buckets, whether ignored paths were scanned, sibling or detached worktrees, stale local annotations, planning drift, and recommended interventions. Use `--with-ignored` before making a clean-workspace claim that includes ignored or generated surfaces. Treat the command output as read-only computed evidence. Local annotations under `.planning/.local/` explain intent but never outrank repo truth, planning artifacts, or checkpoint reconciliation.
+</control_map>
+
 <prerequisites>
 `.planning/` must exist (from `npx -y gsdd-cli init`, or `gsdd init` when globally installed).
 

package/distilled/workflows/quick.md

@@ -45,7 +45,7 @@ Store the response as `$DESCRIPTION`. If empty, re-prompt.
 6. If `.planning/codebase/` exists, read whichever of `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/STACK.md`, `.planning/codebase/CONVENTIONS.md`, and `.planning/codebase/CONCERNS.md` are present. Summarize key findings from available docs in <=500 words as `$CODEBASE_CONTEXT`, emphasizing: safest surfaces to touch, risky zones to avoid, must-know conventions/traps, and what must be re-verified after change. Note any missing docs in the summary.
 7. If `.planning/codebase/` does not exist, build a just-enough inline brownfield baseline instead of stopping. Read the repo root guidance that is cheap and stable (`README.md`, root manifest such as `package.json` / `pyproject.toml` / `Cargo.toml` when present, top-level app entrypoints, and any obviously relevant config or module files surfaced by `$DESCRIPTION`). Summarize the findings in <=500 words as `$CODEBASE_CONTEXT`, explicitly labeling it as a provisional baseline and calling out unknowns. Emphasize: likely implementation surface, likely dependency boundaries, conventions already visible, risky areas to avoid touching blindly, and what must be re-verified after the change. If the repo is still too unclear after this pass, keep that uncertainty explicit so Step 3.6 can recommend `/gsdd-map-codebase`.
 8. **Session-boundary fallback:** If `.planning/.continue-here.bak` exists, read its `<judgment>` section. Use `<active_constraints>` and `<anti_regression>` rules as task-scoping context (do not violate active constraints; do not regress on listed invariants). After reading, run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
-9. Inspect the live branch/worktree surface separately from checkpoint or planning artifacts. If the current branch appears stale/spent, PR-less with overlapping write scope, or otherwise like the wrong execution surface, warn before proceeding. This is advisory for quick tasks unless the mismatch makes the task description materially misleading.
+9. Inspect the live branch/worktree surface separately from checkpoint or planning artifacts. Run `node .planning/bin/gsdd.mjs control-map --json` when available and use its computed repo/worktree/planning truth to identify stale/spent branches, dirty tracked/untracked/ignored buckets, sibling or detached worktrees, local annotations, and cleanup obligations. This is advisory for quick tasks unless the mismatch makes the task description materially misleading; local annotations are intent hints, not product truth.
 
 If `.planning/quick/` does not exist, create it along with an empty `LOG.md`:
 

package/distilled/workflows/resume.md

@@ -35,6 +35,10 @@ Treat the preflight as an authorization seam over shared repo truth only:
 
 <process>
 
+<control_map_reconciliation>
+Before routing from a checkpoint, run `node .planning/bin/gsdd.mjs control-map --json` when available. Reconcile the checkpoint narrative against computed repo/worktree/planning truth: canonical branch/HEAD, tracked/untracked/ignored dirty buckets, sibling or detached worktrees, local annotations, active brownfield anchors, and planning drift. If the checkpoint understates dirty work, points at a stale branch/worktree, or conflicts with the active planning/brownfield surface, stop and present the mismatch before recommending execution. Local annotations are useful intent hints, not authority.
+</control_map_reconciliation>
+
 <detect_state>
 Check for project artifacts in order:
 

package/docs/USER-GUIDE.md

@@ -185,6 +185,7 @@ The 7 check dimensions: requirement coverage, task completeness, dependency corr
 | `npx -y gsdd-cli init [--tools <platform>]` | Set up `.planning/`, generate skills/adapters |
 | `npx -y gsdd-cli update [--tools <platform>]` | Regenerate skills/adapters from latest sources |
 | `npx -y gsdd-cli update --templates` | Refresh role contracts and delegates (warns about user modifications) |
+| `npx -y gsdd-cli control-map [--json] [--with-ignored]` | Show computed repo/worktree/planning state, dirty buckets, optional ignored-path scan, local annotations, and safe next interventions |
 | `npx -y gsdd-cli find-phase [N]` | Show phase info as JSON (for agent consumption) |
 | `npx -y gsdd-cli verify <N>` | Run artifact checks for phase N |
 | `npx -y gsdd-cli scaffold phase <N> [name]` | Create a new phase plan file |
@@ -447,6 +448,7 @@ Switch to budget profile: `npx -y gsdd-cli models profile budget` (or `gsdd mode
     gsdd.ps1                # PowerShell shim for the local helper surface
     lib/                    # Copied helper-runtime support modules
   generation-manifest.json  # SHA-256 hashes for template versioning
+  .local/                   # Local-only operational annotations; not product truth
   .continue-here.md         # Session checkpoint (created by pause, consumed by resume)
   research/                 # Domain research outputs
   codebase/                 # Codebase maps (4 files: STACK, ARCHITECTURE, CONVENTIONS, CONCERNS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Workspine — a repo-native delivery spine for long-horizon AI-assisted work, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "test": "npm run test:gsdd",
-    "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.consumer-ceremony.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs && node tests/gsdd.cross-runtime.test.cjs && node tests/phase.test.cjs && node tests/session-fingerprint.test.cjs",
+    "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.consumer-ceremony.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs && node tests/gsdd.cross-runtime.test.cjs && node tests/gsdd.control-map.test.cjs && node tests/phase.test.cjs && node tests/session-fingerprint.test.cjs",
     "prepublishOnly": "node -e \"const ok=process.env.GITHUB_ACTIONS==='true'&&process.env.GITHUB_REF_NAME==='main'&&process.env.GITHUB_WORKFLOW==='Release'; if(!ok){console.error('Refusing to publish gsdd-cli outside the GitHub Actions Release workflow on main.'); process.exit(1)}\""
   },
   "devDependencies": {