gsdd-cli 0.22.0 → 0.24.0

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/phase.mjs

@@ -4,10 +4,16 @@
 // evaluate once, so CWD must be computed inside function bodies.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
-import { join, basename } from 'path';
+import { dirname, join, relative } from 'path';
 import { output } from './cli-utils.mjs';
 import { writeFingerprint } from './session-fingerprint.mjs';
 import { resolveWorkspaceContext } from './workspace-root.mjs';
+import {
+  compareUiProofSlots,
+  findUiProofBundleFiles,
+  parseUiProofSlotsContent,
+  readUiProofBundleFile,
+} from './ui-proof.mjs';
 
 const PHASE_STATUS_MARKERS = {
   not_started: '[ ]',
@@ -169,6 +175,200 @@ function extractPlanFileArtifacts(planContent, workspaceRoot) {
   return artifacts;
 }
 
+function isPlanArtifactSatisfied(artifact) {
+  if (artifact.operation === 'delete') return !artifact.exists;
+  return artifact.exists;
+}
+
+function planArtifactFixHint(artifact) {
+  if (artifact.operation === 'delete') {
+    return `Complete the planned DELETE for ${artifact.file}, or revise the plan if the file should remain.`;
+  }
+  return `Create or update ${artifact.file} so the planned ${artifact.operation.toUpperCase()} artifact exists, or revise the plan if it is no longer in scope.`;
+}
+
+function evaluatePlanArtifacts(artifacts) {
+  const unsatisfied = artifacts
+    .filter((artifact) => !isPlanArtifactSatisfied(artifact))
+    .map((artifact) => ({
+      ...artifact,
+      severity: 'blocker',
+      expected: artifact.operation === 'delete' ? 'absent' : 'present',
+      fix_hint: planArtifactFixHint(artifact),
+    }));
+  return {
+    satisfied: unsatisfied.length === 0,
+    unsatisfied,
+  };
+}
+
+function normalizeUiProofIssue(issue) {
+  return {
+    ...issue,
+    severity: issue.severity || 'blocker',
+    fix_hint: issue.fix_hint || issue.fix || 'Fix the UI proof issue before claiming verification is complete.',
+  };
+}
+
+function planDeclaresUiProofSlots(planContent) {
+  const match = String(planContent || '').match(/(^|\n)ui_proof_slots:[ \t]*([^\n]*)/);
+  if (!match) return false;
+  const inlineValue = match[2].replace(/\s+#.*$/, '').trim();
+  if (inlineValue) return !['[]', 'null', '~'].includes(inlineValue);
+  const after = String(planContent || '').slice(match.index + match[0].length).split(/\r?\n/);
+  for (const line of after) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    if (trimmed === '---' || trimmed === '...') break;
+    if (/^\s+-\s+/.test(line)) return true;
+    if (/^\S[^:\n]*:\s*/.test(line) || /^\S/.test(line)) break;
+  }
+  return false;
+}
+
+function extractDeclaredUiProofSlotIds(planContent) {
+  const match = String(planContent || '').match(/(^|\n)ui_proof_slots:[ \t]*([^\n]*)/);
+  if (!match) return [];
+  const after = String(planContent || '').slice(match.index + match[0].length).split(/\r?\n/);
+  const slotIds = [];
+  for (const line of after) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    if (trimmed === '---' || trimmed === '...') break;
+    if (/^\S[^:\n]*:\s*/.test(line) || /^\S/.test(line)) break;
+    const slotMatch = trimmed.match(/(?:^-\s*)?slot_id:\s*([^#\s]+)/);
+    if (slotMatch) slotIds.push(slotMatch[1].replace(/^['"]|['"]$/g, ''));
+  }
+  return slotIds;
+}
+
+function findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths) {
+  const candidates = new Set();
+  const declaredPlans = [];
+  const declaredSlotIds = [];
+  const names = new Set([
+    'ui-proof-slots.json',
+    'ui-proof-slots.md',
+    'UI-PROOF-SLOTS.json',
+    'UI-PROOF-SLOTS.md',
+    'planned-ui-proof.json',
+    'planned-ui-proof.md',
+  ]);
+
+  for (const planDisplayPath of planDisplayPaths) {
+    const fullPlanPath = join(planningDir, 'phases', planDisplayPath);
+    if (!existsSync(fullPlanPath)) continue;
+    const planContent = readFileSync(fullPlanPath, 'utf-8');
+    if (!planDeclaresUiProofSlots(planContent)) continue;
+    const relPlanPath = relative(planningDir, fullPlanPath).replace(/\\/g, '/');
+    declaredPlans.push(relPlanPath);
+    for (const slotId of extractDeclaredUiProofSlotIds(planContent)) {
+      declaredSlotIds.push({ plan: relPlanPath, slot_id: slotId });
+    }
+    const planDir = dirname(fullPlanPath);
+    if (!existsSync(planDir)) continue;
+    for (const entry of readdirSync(planDir, { withFileTypes: true })) {
+      if (entry.isFile() && names.has(entry.name)) {
+        candidates.add(join(planDir, entry.name));
+      }
+    }
+  }
+  return { declaredPlans, declaredSlotIds, files: [...candidates].sort() };
+}
+
+function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
+  const plannedDiscovery = findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths);
+  const plannedFiles = plannedDiscovery.files;
+  const phaseDirs = new Set(planDisplayPaths.map((planDisplayPath) => dirname(join(planningDir, 'phases', planDisplayPath))));
+  const observedFiles = findUiProofBundleFiles(planningDir)
+    .filter((filePath) => phaseDirs.has(dirname(filePath)));
+
+  const plannedSlots = [];
+  const errors = [];
+  const planned = [];
+  const observed = [];
+
+  for (const filePath of plannedFiles) {
+    const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
+    const parsed = parseUiProofSlotsContent(readFileSync(filePath, 'utf-8'), rel);
+    planned.push(rel);
+    plannedSlots.push(...parsed.slots);
+    errors.push(...parsed.errors.map(normalizeUiProofIssue));
+  }
+
+  if (plannedSlots.length > 0 && plannedDiscovery.declaredSlotIds.length > 0) {
+    const plannedSlotIds = new Set(plannedSlots.map((slot) => String(slot?.slot_id || '')));
+    for (const declaredSlot of plannedDiscovery.declaredSlotIds) {
+      if (plannedSlotIds.has(String(declaredSlot.slot_id))) continue;
+      errors.push(normalizeUiProofIssue({
+        code: 'planned_ui_proof_slots_drift',
+        path: `${declaredSlot.plan}.ui_proof_slots`,
+        message: `Plan declares UI proof slot ${declaredSlot.slot_id}, but no matching slot exists in the planned UI proof artifact.`,
+        fix: 'Update ui-proof-slots.json or ui-proof-slots.md beside the plan so it matches the plan-declared slot IDs, or update the plan declaration.',
+      }));
+    }
+  }
+
+  const observedBundles = [];
+  for (const filePath of observedFiles) {
+    const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
+    const parsed = readUiProofBundleFile(filePath);
+    observed.push(rel);
+    if (parsed.errors.length > 0) {
+      errors.push(...parsed.errors.map((error) => normalizeUiProofIssue({ ...error, path: error.path || rel })));
+      continue;
+    }
+    observedBundles.push({
+      source: rel,
+      bundle: parsed.bundle,
+      options: {
+        requireLocalArtifactExists: true,
+        workspaceRoot,
+        bundleDir: dirname(filePath),
+      },
+    });
+  }
+
+  if (plannedFiles.length === 0 && plannedDiscovery.declaredPlans.length > 0) {
+    const missingError = {
+      code: 'missing_planned_ui_proof_slots_file',
+      severity: 'blocker',
+      path: plannedDiscovery.declaredPlans[0],
+      message: 'Plan declares ui_proof_slots but no ui-proof-slots artifact was found beside the plan.',
+      fix_hint: 'Create ui-proof-slots.json or ui-proof-slots.md beside the plan, or set ui_proof_slots: [] with a no_ui_proof_rationale if the phase is not UI-sensitive.',
+    };
+    return {
+      planned,
+      observed,
+      status: 'missing',
+      comparison: { status: 'missing', slots: [], errors: [missingError] },
+      errors: [missingError],
+    };
+  }
+
+  if (plannedFiles.length === 0) {
+    return {
+      planned,
+      observed,
+      status: 'not_applicable',
+      comparison: null,
+      errors,
+    };
+  }
+
+  const comparison = errors.length > 0
+    ? { status: 'partial', slots: [], errors: errors.map(normalizeUiProofIssue) }
+    : compareUiProofSlots(plannedSlots, observedBundles);
+
+  return {
+    planned,
+    observed,
+    status: comparison.status,
+    comparison,
+    errors: comparison.errors || errors,
+  };
+}
+
 export function updateRoadmapPhaseStatus(roadmap, phaseNumber, status) {
   const marker = PHASE_STATUS_MARKERS[status];
   if (!marker) {
@@ -360,6 +560,26 @@ export function cmdVerify(...args) {
       ? extractPlanFileArtifacts(readFileSync(fullPath, 'utf-8'), workspaceRoot)
       : [];
   });
+  const artifactStatus = evaluatePlanArtifacts(artifacts);
+  const uiProof = comparePhaseUiProof({
+    planningDir,
+    workspaceRoot,
+    planDisplayPaths: matchingPlans,
+  });
+  const uiProofSatisfied = ['satisfied', 'not_applicable'].includes(uiProof.status);
+  const legacyVerified = matchingPlans.length > 0 && matchingSummaries.length > 0;
+  const uiProofGate = {
+    status: uiProof.status,
+    required: uiProof.status !== 'not_applicable',
+    satisfied: uiProofSatisfied,
+    blocks_verification: uiProof.status !== 'not_applicable' && !uiProofSatisfied,
+    required_block: uiProof.status !== 'not_applicable' && !uiProofSatisfied ? 'ui-proof-failed' : null,
+  };
+  const blockedOn = [
+    ...(artifactStatus.satisfied ? [] : ['artifacts']),
+    ...(uiProofGate.blocks_verification ? ['ui_proof'] : []),
+  ];
+  const closureVerified = legacyVerified && artifactStatus.satisfied && uiProofSatisfied;
 
   const result = {
     phase: normalizePhaseToken(phaseNum),
@@ -368,9 +588,17 @@ export function cmdVerify(...args) {
     summaries: matchingSummaries,
     artifacts,
     allExist: artifacts.every((artifact) => artifact.exists),
-    verified: matchingPlans.length > 0 && matchingSummaries.length > 0,
+    artifact_status: artifactStatus,
+    uiProof,
+    verified: closureVerified,
+    legacy_verified: legacyVerified,
+    phase_artifacts_present: legacyVerified,
+    ui_proof: uiProofGate,
+    blocked_on: blockedOn,
+    blocks_verification: blockedOn.length > 0,
   };
   output(result);
+  if (!closureVerified && legacyVerified) process.exitCode = 1;
 }
 
 export function cmdScaffold(...args) {

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/bin/lib/ui-proof.mjs

@@ -446,6 +446,41 @@ function normalizeObservedBundle(entry) {
   };
 }
 
+function comparisonFixHint(code) {
+  const hints = {
+    invalid_observed_bundle: 'Fix the observed proof bundle metadata, then rerun ui-proof compare.',
+    unsatisfied_observed_claim_status: 'Record a passed observed claim only after the changed UI state has been exercised and evidenced.',
+    unsatisfied_observed_comparison_status: 'Set comparison_status_by_slot to satisfied only for slots backed by matching observations and artifacts.',
+    missing_required_evidence_kind: 'Add observed evidence for every evidence kind required by the planned slot, or narrow the planned slot before verification.',
+    human_evidence_cannot_bypass_required_non_human_evidence: 'Add the missing non-human evidence; human approval may narrow or waive but cannot replace it.',
+    route_state_mismatch: 'Capture proof for the exact planned route/state, or update the plan before execution.',
+    environment_mismatch: 'Capture proof in the planned environment, or record a narrowed claim limit and rerun comparison.',
+    viewport_mismatch: 'Capture proof for the planned viewport, or narrow the viewport claim explicitly.',
+    requirement_mismatch: 'Declare the planned requirement id in the observed proof bundle scope.',
+    claim_mismatch: 'Keep the planned and observed claims identical so proof maps to the exact UI assertion.',
+    observation_claim_mismatch: 'Add a passed observation that supports the exact planned claim.',
+    observation_route_state_mismatch: 'Attach observations to the exact planned route/state.',
+    missing_supporting_observation_evidence_kind: 'Add passed supporting observations for each required evidence kind.',
+    unsatisfied_proof_step: 'Rerun or replace failing proof steps before claiming the slot is satisfied.',
+    missing_manual_acceptance_evidence: 'Record human evidence when the planned slot requires manual acceptance.',
+    missing_manual_acceptance_observation: 'Add a passed human observation for manual acceptance.',
+    unsatisfied_observation_result: 'Resolve failed observations or classify the slot as partial, waived, or deferred.',
+    missing_minimum_observation: 'Add observations covering every planned minimum observation.',
+    missing_claim_limit: 'Preserve the planned claim limit in the observed proof bundle.',
+    missing_expected_artifact_type: 'Attach the planned artifact type, such as screenshot, report, trace, or DOM snapshot.',
+    missing_observed_bundle: 'Create an observed UI proof bundle for the planned slot, or explicitly waive/defer the slot with claim narrowing.',
+  };
+  return hints[code] || 'Fix the proof issue, rerun the comparison, and keep the slot partial until evidence matches the plan.';
+}
+
+function decorateComparisonIssue(issue) {
+  return {
+    severity: issue.severity || 'blocker',
+    fix_hint: issue.fix_hint || issue.fix || comparisonFixHint(issue.code),
+    ...issue,
+  };
+}
+
 function compareSlotToBundle(slot, slotIdValue, observed) {
   const issues = [];
   const bundle = observed.bundle;
@@ -648,7 +683,7 @@ function compareSlotToBundle(slot, slotIdValue, observed) {
   }
 
   const status = issues.length === 0 ? 'satisfied' : (bundleStatus === 'missing' ? 'missing' : 'partial');
-  return { status, issues, source: observed.source };
+  return { status, issues: issues.map(decorateComparisonIssue), source: observed.source };
 }
 
 export function compareUiProofSlots(plannedSlots, observedBundles) {
@@ -656,7 +691,7 @@ export function compareUiProofSlots(plannedSlots, observedBundles) {
   const slotValidation = validateUiProofSlots(slots);
   const bundles = normalizeArray(observedBundles).map(normalizeObservedBundle);
   const results = [];
-  const errors = [...slotValidation.errors];
+  const errors = slotValidation.errors.map(decorateComparisonIssue);
 
   for (const observed of bundles) {
     if (!observed.validation.valid) {
@@ -680,7 +715,7 @@ export function compareUiProofSlots(plannedSlots, observedBundles) {
           code: 'missing_observed_bundle',
           path: 'scope.slot_ids',
           message: `No observed UI proof bundle declares planned slot ${slotIdValue}.`,
-        }],
+        }].map(decorateComparisonIssue),
       });
       continue;
     }
@@ -706,7 +741,7 @@ export function compareUiProofSlots(plannedSlots, observedBundles) {
         ? 'missing'
         : 'partial';
 
-  return { status, slots: results, errors };
+  return { status, slots: results, errors: errors.map(decorateComparisonIssue) };
 }
 
 export function validateUiProofBundle(bundle, options = {}) {

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: