gsdd-cli 0.19.0 → 0.19.1

package/bin/lib/session-fingerprint.mjs

@@ -11,9 +11,13 @@
 import { createHash } from 'crypto';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { output } from './cli-utils.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 const FINGERPRINT_FILE = '.state-fingerprint.json';
 const FINGERPRINT_SOURCES = ['ROADMAP.md', 'SPEC.md', 'config.json'];
+const FINGERPRINT_SCHEMA_VERSION = 2;
+const FINGERPRINT_ALGORITHM = 'sha256:v2:exists-content';
 
 /**
  * Compute a SHA-256 fingerprint from the planning truth files.
@@ -23,15 +27,52 @@ const FINGERPRINT_SOURCES = ['ROADMAP.md', 'SPEC.md', 'config.json'];
 export function computeFingerprint(planningDir) {
   const hash = createHash('sha256');
   const sources = {};
+  const files = {};
   for (const file of FINGERPRINT_SOURCES) {
     const filePath = join(planningDir, file);
-    const content = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+    const exists = existsSync(filePath);
+    const content = exists ? readFileSync(filePath, 'utf-8') : '';
+    hash.update(`${file}:${exists ? 'exists' : 'missing'}:${content}\n`);
+    sources[file] = exists;
+    files[file] = {
+      exists,
+      hash: createHash('sha256').update(content).digest('hex'),
+    };
+  }
+  return { hash: hash.digest('hex'), sources, files };
+}
+
+function computeLegacyFingerprint(planningDir) {
+  const hash = createHash('sha256');
+  const sources = {};
+  for (const file of FINGERPRINT_SOURCES) {
+    const filePath = join(planningDir, file);
+    const exists = existsSync(filePath);
+    const content = exists ? readFileSync(filePath, 'utf-8') : '';
     hash.update(`${file}:${content}\n`);
-    sources[file] = existsSync(filePath);
+    sources[file] = exists;
   }
   return { hash: hash.digest('hex'), sources };
 }
 
+export function cmdSessionFingerprint(...args) {
+  const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [action] = normalizedArgs;
+  if (action !== 'write') {
+    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write');
+    process.exitCode = 1;
+    return;
+  }
+
+  output({ operation: 'session-fingerprint write', fingerprint: writeFingerprint(planningDir) });
+}
+
 /**
  * Read the stored fingerprint from .planning/.state-fingerprint.json.
  * Returns null if the file does not exist or is unparseable.
@@ -50,10 +91,13 @@ export function readStoredFingerprint(planningDir) {
  * Write the current fingerprint to .planning/.state-fingerprint.json.
  */
 export function writeFingerprint(planningDir) {
-  const { hash, sources } = computeFingerprint(planningDir);
+  const { hash, sources, files } = computeFingerprint(planningDir);
   const data = {
+    schemaVersion: FINGERPRINT_SCHEMA_VERSION,
+    algorithm: FINGERPRINT_ALGORITHM,
     hash,
     sources,
+    files,
     timestamp: new Date().toISOString(),
   };
   writeFileSync(join(planningDir, FINGERPRINT_FILE), JSON.stringify(data, null, 2) + '\n');
@@ -69,27 +113,33 @@ export function writeFingerprint(planningDir) {
  */
 export function checkDrift(planningDir) {
   const stored = readStoredFingerprint(planningDir);
-  const { hash: currentHash, sources: currentSources } = computeFingerprint(planningDir);
+  const { hash: currentHash, sources: currentSources, files: currentFiles } = computeFingerprint(planningDir);
 
   if (!stored) {
     return {
       drifted: false,
       noBaseline: true,
+      classification: 'no_baseline',
       details: ['No stored fingerprint found — first session or fingerprint was cleared.'],
       stored: null,
-      current: { hash: currentHash, sources: currentSources },
+      current: { hash: currentHash, sources: currentSources, files: currentFiles },
+      files: [],
     };
   }
 
-  const drifted = stored.hash !== currentHash;
+  const isLegacy = !stored.schemaVersion && !stored.files;
+  const comparison = isLegacy ? computeLegacyFingerprint(planningDir) : { hash: currentHash };
+  const drifted = stored.hash !== comparison.hash;
   const details = [];
+  const files = drifted
+    ? FINGERPRINT_SOURCES.map((file) => classifyFileDrift(file, stored, currentSources, currentFiles, { legacy: isLegacy }))
+    : FINGERPRINT_SOURCES.map((file) => ({ file, status: 'unchanged' }));
   if (drifted) {
-    for (const file of FINGERPRINT_SOURCES) {
-      const was = stored.sources?.[file] ?? false;
-      const now = currentSources[file];
-      if (was && !now) details.push(`${file} was removed`);
-      else if (!was && now) details.push(`${file} was created`);
-      else if (was && now) details.push(`${file} may have changed`);
+    for (const file of files) {
+      if (file.status === 'created') details.push(`${file.file} created`);
+      else if (file.status === 'removed') details.push(`${file.file} removed`);
+      else if (file.status === 'changed') details.push(`${file.file} changed`);
+      else if (file.status === 'unknown') details.push(`${file.file} may have changed`);
     }
     if (details.length === 0) {
       details.push('Planning state hash changed since last recorded session.');
@@ -99,8 +149,35 @@ export function checkDrift(planningDir) {
   return {
     drifted,
     noBaseline: false,
+    classification: drifted ? 'planning_state_drift' : 'clean',
+    compatibility: isLegacy ? 'legacy_v1' : null,
+    needsBaselineRefresh: isLegacy && !drifted,
     details,
-    stored: { hash: stored.hash, timestamp: stored.timestamp },
-    current: { hash: currentHash, sources: currentSources },
+    files,
+    stored: {
+      hash: stored.hash,
+      timestamp: stored.timestamp,
+      schemaVersion: stored.schemaVersion ?? null,
+      algorithm: stored.algorithm ?? null,
+      files: stored.files ?? null,
+    },
+    current: { hash: currentHash, sources: currentSources, files: currentFiles },
+  };
+}
+
+function classifyFileDrift(file, stored, currentSources, currentFiles, { legacy = false } = {}) {
+  const was = stored.sources?.[file] ?? false;
+  const now = currentSources[file];
+
+  if (was && !now) return { file, status: 'removed' };
+  if (!was && now) return { file, status: 'created' };
+  if (!was && !now) return { file, status: 'unchanged' };
+  if (legacy) return { file, status: 'unknown' };
+
+  const storedFile = stored.files?.[file];
+  if (!storedFile?.hash) return { file, status: 'unknown' };
+  return {
+    file,
+    status: storedFile.hash === currentFiles[file].hash ? 'unchanged' : 'changed',
   };
 }

package/distilled/DESIGN.md

@@ -69,6 +69,8 @@
 56. [Executable Brownfield Routing And Widen-Only Escalation](#d56---executable-brownfield-routing-and-widen-only-escalation)
 57. [Bounded Brownfield Growth And Context-Preserving Milestone Handoff](#d57---bounded-brownfield-growth-and-context-preserving-milestone-handoff)
 58. [Local Workflow Helper Launcher](#d58---local-workflow-helper-launcher)
+59. [Continuity Authority And Planning-State Drift](#d59---continuity-authority-and-planning-state-drift)
+60. [Release Closeout Contract](#d60---release-closeout-contract)
 
 ---
 
@@ -151,13 +153,13 @@ The same over-distillation pattern had also flattened `roadmapper.md`, `synthesi
 
 **Executor leverage audit (2026-03-13):**
 
-The executor was the last un-audited core lifecycle role. At 89 lines it was the most under-structured role contract in the system — no XML section boundaries, no mandatory initial read, no scope boundary, no typed output example, no auth-gate protocol, no completion checklist. The audit applied the same S12 hardening pattern.
+The executor was the last un-audited core lifecycle role. At 89 lines it was the most under-structured role contract in the system — no XML section boundaries, no explicit context-intake tiers, no scope boundary, no typed output example, no auth-gate protocol, no completion checklist. The audit applied the same S12 hardening pattern.
 
-- **Executor kept from GSD:** mandatory initial-read discipline, explicit deviation-rule examples (null pointers, missing auth, missing dependency, new DB tables), auth-gate protocol (401/403 recognition, checkpoint return with exact auth steps), substantive summary quality gate, TDD RED/GREEN/REFACTOR steps with infrastructure detection, self-check discipline, and completion checklist.
+- **Executor kept from GSD:** mandatory context-intake discipline, explicit deviation-rule examples (null pointers, missing auth, missing dependency, new DB tables), auth-gate protocol (401/403 recognition, checkpoint return with exact auth steps), substantive summary quality gate, TDD RED/GREEN/REFACTOR steps with infrastructure detection, self-check discipline, and completion checklist.
 - **Executor intentionally stripped:** wave-based parallelization, agent tracking journal, segment execution patterns A/B/C, auto-mode checkpoint routing (`auto_advance` config), per-task commit format `{type}({phase}-{plan}):`, `gsd-tools.cjs` CLI commands, template path references (`~/.claude/`), `user_setup` generation, `executor_model` selection, and codebase-map sync with dropped files (`STRUCTURE.md`, `INTEGRATIONS.md`).
 - **Executor gained in GSDD:** XML-bounded section structure, explicit scope boundary (plan-scoped, does not own planning/verification/milestone audit), typed SUMMARY.md output example with YAML frontmatter, portable auth-gate protocol (checkpoint:user with exact steps, not vendor-specific checkpoint return format), and execution-loop alignment with the current GSDD plan schema (`checkpoint:user`, `checkpoint:review`, change-impact discipline).
 
-The accompanying workflow alignment pass on `distilled/workflows/execute.md` added four targeted changes: mandatory read enforcement upgrade, auth-gate routing in the checkpoint protocol, concrete deviation-rule examples matching the role contract, and a substantive summary quality gate.
+The accompanying workflow alignment pass on `distilled/workflows/execute.md` added four targeted changes: tiered context-intake enforcement, auth-gate routing in the checkpoint protocol, concrete deviation-rule examples matching the role contract, and a substantive summary quality gate.
 
 This hardening pass also clarified a reusable architectural rule: strict portable workflows are not enough if the canonical role contracts underneath them are flattened into prose. Role strictness and workflow strictness both matter.
 
@@ -581,7 +583,7 @@ Design principle unchanged: derive state from primary artifacts (ROADMAP.md, SPE
 
 **GSD:** No structural invariant tests. Framework correctness relies on manual review and ad-hoc checking.
 
-**GSDD:** 6 invariant suites (G1-G7, G2 reserved) with ~106 assertions enforce structural properties across all 29 framework markdown files. Every assertion message includes a `FIX:` instruction so CI agents can self-remediate.
+**GSDD:** The guard and invariant suites enforce structural properties across framework markdown files. Every assertion message includes a `FIX:` instruction so CI agents can self-remediate.
 
 **Suite inventory:**
 
@@ -600,7 +602,7 @@ Design principle unchanged: derive state from primary artifacts (ROADMAP.md, SPE
 
 **Evidence:**
 
-- `tests/gsdd.invariants.test.cjs` lines 1015+ (6 suites, ~106 assertions)
+- `tests/gsdd.invariants.test.cjs` and `tests/gsdd.guards.test.cjs` enforce structural drift checks with actionable `FIX:` messages
 - OpenAI Harness Engineering blog (Feb 2026): "error messages as enforcement mechanism"
 - External audit (2026-03-13): recommendation #4 "Mechanize the framework's invariants"
 - GSD source: no equivalent test infrastructure
@@ -954,6 +956,7 @@ Implementation lives under `bin/lib/`:
 | E6 | ERROR | `.planning/templates/research/` missing or empty |
 | E7 | ERROR | `.planning/templates/codebase/` missing or empty |
 | E8 | ERROR | `.planning/templates/` missing critical root files (`spec.md`, `roadmap.md`, `auth-matrix.md`) |
+| E9 | ERROR | `.planning/templates/brownfield-change/` missing or missing critical files (`CHANGE.md`, `HANDOFF.md`, `VERIFICATION.md`) |
 | W1 | WARN | `generation-manifest.json` missing |
 | W2 | WARN | Template files modified locally (hash mismatch vs manifest) |
 | W3 | WARN | Template/role files missing from disk but listed in manifest |
@@ -963,8 +966,8 @@ Implementation lives under `bin/lib/`:
 | W7 | WARN | `distilled/DESIGN.md` health check table differs from implemented check IDs |
 | W8 | WARN | `distilled/README.md` workflow inventory differs from `distilled/workflows/` |
 | W9 | WARN | `.internal-research/gaps.md` references missing repo-local paths |
-| W10 | WARN | ROADMAP/SPEC requirement status drift |
-| W11 | WARN | Installed generated runtime surfaces drift from current render output |
+| W10 | WARN | ROADMAP lifecycle status drift, including requirement checkbox and overview/detail phase status mismatches |
+| W11 | WARN | Installed generated runtime/helper surfaces drift from current render output |
 | W12 | WARN | Planning state drifted since last recorded session (fingerprint mismatch) |
 | I1 | INFO | Generation manifest `frameworkVersion` differs from current `FRAMEWORK_VERSION` |
 | I2 | INFO | Phase completion count from ROADMAP |
@@ -987,15 +990,15 @@ Implementation lives under `bin/lib/`:
 
 3. **Pre-init guard.** If `.planning/config.json` doesn't exist, output a one-line message and exit 1. No partial checks — the workspace is simply not initialized.
 
-4. **Split structural vs truth checks.** `bin/lib/health.mjs` keeps the structural workspace checks. `bin/lib/health-truth.mjs` holds the always-on cross-file truth checks (W7-W10) so the health surface can grow without turning the main command into one monolith.
+4. **Split structural vs truth checks.** `bin/lib/health.mjs` keeps the structural workspace checks. `bin/lib/health-truth.mjs` holds the always-on cross-file truth checks (W7-W12) so the health surface can grow without turning the main command into one monolith.
 
 5. **Reuses existing modules.** `readManifest()` and `detectModifications()` from `manifest.mjs` handle W1-W3. `isProjectInitialized()` pattern from `models.mjs` handles the pre-init guard. Truth checks stay read-only and operate on repo-local artifacts only when those framework files exist.
 
-6. **Framework-source mode skips installed-project template checks.** Inside the GSDD framework repo itself, `distilled/templates/` is the source of truth and `.planning/templates/` is intentionally absent. `npx -y gsdd-cli health` therefore skips the installed-project template/manifest checks (E3-E8, W1-W3) in framework-source mode instead of producing false positives during self-health runs.
+6. **Framework-source mode skips installed-project template checks.** Inside the GSDD framework repo itself, `distilled/templates/` is the source of truth and `.planning/templates/` is intentionally absent. `npx -y gsdd-cli health` therefore skips the installed-project template/manifest checks (E3-E9, W1-W3) in framework-source mode instead of producing false positives during self-health runs.
 
 **What was removed vs GSD:**
 - `--repair` flag and associated repair actions
-- Error codes E001-E005/W001-W007 (replaced with simpler E1-E8/W1-W12/I1-I3)
+- Error codes E001-E005/W001-W007 (replaced with simpler E1-E9/W1-W12/I1-I3)
 - STATE.md checks (GSDD has no STATE.md per D7)
 - PROJECT.md checks (GSDD uses SPEC.md, not checked by health — it's workflow-authored)
 - Phase directory naming format checks (GSDD uses flat numbered files, not NN-name directories)
@@ -1365,6 +1368,7 @@ Both paths produce identical output: `{padded_phase}-APPROACH.md` in the phase d
 | Questioning style | Rigid 4-question batched loop | Adaptive convergence (2-6 questions depending on complexity) | Fixed batch sizes don't match decision complexity. Some areas resolve in 2 questions, others need 6 |
 | Pre-question research | No research before asking | Research subagent per technical area returns structured summary before asking | Users make better decisions when presented with researched options and trade-offs |
 | Quality gate | None | Self-check before writing APPROACH.md (concrete decisions, no vague language, source backing, scope compliance) | Prevents weak outputs that force re-asking during planning |
+| Alignment proof gate | None | `APPROACH.md` records `alignment_status: user_confirmed` or explicit `approved_skip`, and planning validates this before goal-backward planning when `workflow.discuss: true` | Prevents native or existing-artifact paths from turning mandatory discussion into artifact theater |
 | Intermediate persistence | No persistence until final output | Confirmed decisions written to disk incrementally | Protects against context limits in long conversations |
 | Context loading | "Read everything" | JIT extraction guidance (e.g., "From SPEC.md read ONLY locked decisions") | Prevents context pollution with irrelevant content |
 | Plan-checker integration | None | New `approach_alignment` dimension in plan-checker | Verifies plans honor approach decisions, not just requirements |
@@ -1398,11 +1402,11 @@ Isolating research in subagents and returning compressed summaries follows the C
 
 **Trade-offs:**
 
-- Benefit: planner receives locked user decisions instead of guessing approaches; plan-checker can verify approach alignment; context stays lean via research isolation
+- Benefit: planner receives locked user decisions instead of guessing approaches; plan-checker can verify approach alignment; existing APPROACH artifacts are not trusted unless their alignment proof is valid; context stays lean via research isolation
 - Cost: adds one interactive step before planning (~5-15 minutes of user time per phase); hybrid architecture is more complex than a single monolithic workflow
 - Mitigation: `workflow.discuss: true|false` toggle in `.planning/config.json` allows skipping with explicit `reduced_alignment` reporting; taste areas skip research entirely. Default is `false` (opt-in) to stay consistent with GSDD's stripped-down identity; users enable it explicitly
 
-**GSDD implementation:** `agents/approach-explorer.md` (role contract), `distilled/templates/delegates/approach-explorer.md` (thin delegate), `distilled/templates/approach.md` (output template), `distilled/workflows/plan.md` (`<approach_exploration>` section), `agents/planner.md` (`<approach_decisions>` section), `distilled/templates/delegates/plan-checker.md` (`approach_alignment` dimension), `bin/adapters/claude.mjs` + `bin/adapters/opencode.mjs` + `bin/adapters/codex.mjs` (native agent rendering)
+**GSDD implementation:** `agents/approach-explorer.md` (role contract), `distilled/templates/delegates/approach-explorer.md` (thin delegate), `distilled/templates/approach.md` (output template), `distilled/workflows/plan.md` (`<approach_exploration>` section), `agents/planner.md` (`<approach_decisions>` section), `distilled/templates/delegates/plan-checker.md` (`approach_alignment` dimension), `bin/adapters/claude.mjs` + `bin/adapters/opencode.mjs` + `bin/adapters/codex.mjs` (native agent rendering), `tests/gsdd.guards.test.cjs`, `tests/gsdd.plan.adapters.test.cjs`, and `tests/gsdd.scenarios.test.cjs` (alignment-proof propagation coverage)
 
 ---
 
@@ -2157,7 +2161,8 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
   - it reports blockers, owned writes, mutation expectations, and lifecycle posture
   - it does not mutate ROADMAP or milestone state itself
 - Keep `gsdd phase-status` as the only explicit ROADMAP mutator for phase-state transitions.
-- Require transition-sensitive workflow contracts to call the shared preflight seam instead of narrating their own lifecycle inference.
+- Require transition-sensitive workflow contracts, including plan creation, to call the shared preflight seam instead of narrating their own lifecycle inference.
+- Treat planning-state drift as warning-only for read-only surfaces and blocking for owned-write surfaces, with file-level drift details from the session fingerprint helper.
 - Preserve `progress` as read-only and make it explicitly defer any recommended transition back to the downstream workflow's own preflight gate.
 
 **Why this fits the codebase:**
@@ -2170,7 +2175,9 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - `.planning/ROADMAP.md` (Phase 30 success criteria)
 - `bin/lib/lifecycle-preflight.mjs`
 - `bin/lib/lifecycle-state.mjs`
+- `bin/lib/session-fingerprint.mjs`
 - `bin/gsdd.mjs`
+- `distilled/workflows/plan.md`
 - `distilled/workflows/execute.md`
 - `distilled/workflows/verify.md`
 - `distilled/workflows/audit-milestone.md`
@@ -2179,6 +2186,7 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - `distilled/workflows/resume.md`
 - `distilled/workflows/progress.md`
 - `tests/phase.test.cjs`
+- `tests/session-fingerprint.test.cjs`
 - `tests/gsdd.guards.test.cjs`
 - `tests/gsdd.scenarios.test.cjs`
 - GSD comparison source: `get-shit-done/workflows/progress.md` still keeps lifecycle routing inside the workflow surface rather than through a shared helper seam, so this is an intentional GSDD tightening.
@@ -2188,7 +2196,7 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - `progress` can continue reporting lifecycle posture without inheriting write authority or becoming a hidden transition surface.
 - Phase 31 can build evidence-gated closure on top of a stable deterministic preflight contract instead of competing lifecycle entry logic.
 
-**GSDD implementation:** `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`, `bin/gsdd.mjs`, `bin/lib/init.mjs`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`, `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+**GSDD implementation:** `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`, `bin/lib/session-fingerprint.mjs`, `bin/gsdd.mjs`, `bin/lib/init.mjs`, `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`, `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`, `tests/phase.test.cjs`, `tests/session-fingerprint.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 
 ---
 
@@ -2646,6 +2654,126 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - Generated governance remains compact and routing-focused because helper-surface instructions stay out of `AGENTS.md`.
 - Cross-platform proof is stronger for the local-helper seam itself, but direct live validation still needs to stay conservative by environment: the repo now has focused tests plus Windows fixture proof; Linux/WSL live consumer validation remains a separate evidence question.
 
+## D59 - Continuity Authority And Planning-State Drift
+
+**Decision (2026-04-27):** Workspine continuity authority is split by surface. Git/worktree truth owns integration visibility and overwrite risk, `.planning/` owns local workflow contracts, phase artifacts own phase-local scope and proof, generated runtime surfaces own consumed helper/adapter freshness, and compressed judgment remains advisory context. Planning-state drift must stay warning-only for read-only/reporting surfaces, but mutating lifecycle surfaces must not silently proceed through material drift.
+
+**Context:**
+- `.planning/` remains local-only by default in this framework repo. That preserves privacy and avoids noisy framework-internal planning commits, but it also means planning state can drift across sessions without git history protecting it.
+- Gap `I46` showed the concrete failure: one session wrote milestone state under ignored `.planning/`, another session read stale planning state and nearly routed execution as if the milestone did not exist.
+- Gap `S6` showed the related judgment failure: fresh sessions can recover artifact structure while losing the active constraints, unresolved uncertainty, decision posture, and anti-regression rules that explain how to continue safely.
+- Existing helper seams already detect part of the risk: `session-fingerprint.mjs` fingerprints `.planning/ROADMAP.md`, `.planning/SPEC.md`, and `.planning/config.json`; `lifecycle-preflight.mjs` exposes drift as `planning_state_drift`; `health` reports the same condition as `W12`.
+
+**Authority matrix:**
+
+| Surface | Owns | Does not own | Provenance check | Drift signal | Stop condition | Proof needed |
+| --- | --- | --- | --- | --- | --- | --- |
+| Git branch/HEAD | Integration surface identity, commit baseline, branch-local work context | Planning truth, phase status, judgment | `git rev-parse --abbrev-ref HEAD`; `git rev-parse --short HEAD` | Unexpected branch or HEAD relative to the active plan/change | Mutating workflow targets a different branch or HEAD than the active plan/change declares | Captured branch/HEAD before mutation; explicit acknowledgement if mismatched |
+| Staged changes | Pending commit contents and delivery visibility risk | Final repo truth until committed; planning authority | `git diff --name-only --cached` | Staged paths outside declared write set | Staged work overlaps unrelated scope or would be accidentally included | Staged path list reviewed against plan write set |
+| Unstaged changes | Local uncommitted edits and overwrite/conflict risk | Approved implementation state; phase closure | `git diff --name-only` | Dirty tracked files outside declared write set | Mutating workflow would overwrite or reinterpret unrelated edits | Dirty path list reviewed; user decision if conflict or overlap exists |
+| Untracked files | Local-only artifacts and possible proof gaps | Durable repo truth; public/delivery evidence | `git status --porcelain=v1` | Untracked required artifacts, generated dirs, or scope-expanding files | Required proof/output exists only untracked when closure claims tracked truth | Required artifacts are tracked intentionally or explicitly classified local-only |
+| `.planning/SPEC.md` | Local product/workflow requirements and active milestone requirement truth | Git-tracked public truth in the framework repo; branch delivery state | Read active requirements/current state; compare to roadmap and trackers | `W12`; mismatch with ROADMAP/TODO/gaps; stale active milestone | Mutating lifecycle action depends on stale or contradictory requirements | Fresh read plus drift acknowledgement/blocking behavior before mutation |
+| `.planning/ROADMAP.md` | Active milestone/phase ordering, status, success criteria, stop/replan contract | Artifact existence proof; implementation completion by itself | Read active phase section; lifecycle evaluator/preflight | `W12`; overview/detail mismatch; phase artifact mismatch | Execute/verify/audit/complete would act on stale or contradictory roadmap state | Preflight passes or blocks; phase status agrees with artifacts |
+| Phase PLAN/SUMMARY/VERIFICATION | Phase-local scope, execution result, verification result, compressed judgment handoff | Milestone-wide truth alone; git integration truth; generated runtime freshness | Check phase directory and required artifact sequence | PLAN without SUMMARY; SUMMARY missing for verify; VERIFICATION missing for completed phase | Execute without valid pending plan; verify without summary; close phase without verification | Required artifact exists, is substantive, and matches roadmap status |
+| Checkpoint files | Session-local resume context and mid-session compressed judgment | Durable status; routing authority over fresh roadmap/git truth | `.planning/.continue-here.md` and `.planning/.continue-here.bak` presence/classification | Checkpoint narrative conflicts with branch/worktree/planning truth; stale generic checkpoint | Resume would route from materially misleading checkpoint without acknowledgement | Resume surfaces checkpoint/planning/git split; material mismatch requires acknowledgement |
+| Brownfield CHANGE/HANDOFF/VERIFICATION | Medium-scope brownfield operational anchor, judgment handoff, closeout proof | Milestone phase state; roadmap-owned lifecycle; generic scratchpad | `.planning/brownfield-change/*` presence and lifecycle-state classification | Artifact branch/write-scope mismatch; missing sibling file; stale next action | Resume/progress would treat stale brownfield artifact as current without warning/acknowledgement | CHANGE primary, HANDOFF judgment-only, VERIFICATION proof; mismatch handled by progress/resume split |
+| Milestone audit | Milestone closure evidence and pass/fail posture | Phase execution; public release/delivery unless evidence says so | `.planning/<version>-MILESTONE-AUDIT.md`, `status: passed`, evidence contract | Missing audit for completion; audit not passed; evidence gaps | `complete-milestone` without passed audit or required evidence | Audit artifact exists, passed, and required evidence kinds are present |
+| Generated runtime surfaces | Consumed local runtime/helper surfaces generated from authored source | Authored workflow truth; planning status; branch truth | `gsdd health --json` runtime freshness and manifest comparison | `W11` drift from current render output | Phase behavior depends on generated-surface parity, or closure claims runtime freshness | Run the normal update path only when needed; health/checks prove freshness |
+
+**Decision rules:**
+- Read-only/reporting surfaces may warn on planning-state drift and continue. They must not refresh or mutate the planning fingerprint as a side effect.
+- Owned-write lifecycle surfaces must treat material planning-state drift as a stop or explicit acknowledgement boundary before writing summary, verification, milestone, roadmap, or checkpoint-cleanup artifacts.
+- No-baseline fingerprint state is not itself proof of drift. It should be classified explicitly, but it must not strand first-session users unless another contradiction exists.
+- Compressed judgment remains the four-section `<judgment>` shape (`active_constraints`, `unresolved_uncertainty`, `decision_posture`, `anti_regression`) and remains subordinate to operational state.
+- A tracked coordination artifact is not justified by Phase 44 evidence alone. It becomes necessary only if deterministic local checks cannot prevent stale-read/overwrite behavior or if a future release claim requires fresh-clone/public evidence.
+
+**Evidence:**
+- `.planning/phases/44-continuity-authority-and-persistence/44-APPROACH.md`
+- `.planning/phases/44-continuity-authority-and-persistence/44-PLAN.md`
+- `.planning/SPEC.md` (`REL-01`)
+- `.planning/ROADMAP.md` (Phase 44)
+- `.internal-research/gaps.md` (`I46`, `S6`)
+- `bin/lib/session-fingerprint.mjs`
+- `bin/lib/lifecycle-preflight.mjs`
+- `bin/lib/runtime-freshness.mjs`
+- `distilled/workflows/progress.md`
+- `distilled/workflows/resume.md`
+- `distilled/workflows/execute.md`
+- `distilled/workflows/verify.md`
+- `distilled/workflows/audit-milestone.md`
+- `distilled/workflows/complete-milestone.md`
+- `distilled/workflows/new-milestone.md`
+- `distilled/templates/brownfield-change/CHANGE.md`
+- `distilled/templates/brownfield-change/HANDOFF.md`
+- `distilled/templates/brownfield-change/VERIFICATION.md`
+- `tests/session-fingerprint.test.cjs`
+- `tests/phase.test.cjs`
+
+**Consequences:**
+- Phase execution can remain local-first without pretending ignored `.planning/` files are unconditional authority.
+- Planning drift becomes a concrete lifecycle safety signal rather than a generic health warning that agents can ignore.
+- The design avoids adding a scratchpad or second state system while preserving enough compressed judgment to guide cold-start continuation.
+- The remaining implementation question is narrow: make helper output and targeted tests reflect this authority split without widening Phase 44 into generated-surface or release-closeout work.
+
+---
+
+## D60 - Release Closeout Contract
+
+**Decision (2026-04-27, enforced 2026-04-27):** Release-quality milestone closeout uses a release claim posture layered over the existing evidence posture matrix. The allowed postures are `repo_closeout`, `runtime_validated_closeout`, and `delivery_supported_closeout`; each posture must stay within the fixed evidence kinds `code`, `test`, `runtime`, `delivery`, and `human`.
+
+**Context:**
+- D50 already defined the closure evidence matrix for `verify`, `audit-milestone`, and `complete-milestone`, but `repo_only` and `delivery_sensitive` are evidence bars rather than wording boundaries.
+- D59 clarified that `.planning/` remains local-only by default, generated runtime surfaces own their own freshness, and public/delivery claims need git/worktree or tracked repo-visible proof.
+- Phase 45 needed a way to close repo-local milestone work honestly without implying GitHub Releases, package publishes, runtime parity, generated-surface freshness, or external availability.
+- GitHub Releases remain explicitly deferred under `LSC-05`, so release closeout cannot depend on public release objects unless a later milestone approves them.
+
+**Decision:**
+- Add release claim posture semantics to `bin/lib/evidence-contract.mjs` without adding evidence kinds or replacing delivery postures.
+- Define the three postures as claim boundaries:
+  - `repo_closeout`: default; permits repo-local closeout only and must not imply public support, runtime validation, delivery, publication, or generated-surface freshness.
+  - `runtime_validated_closeout`: permits claims about a named runtime behavior or runtime surface only when `runtime` evidence exists for that exact runtime or surface.
+  - `delivery_supported_closeout`: permits externally consumed release, install, support, or delivery claims only when the `delivery_sensitive` evidence bar is satisfied.
+- Thread the posture through `audit-milestone` as audit-owned release closeout metadata: unsupported claims, waivers, deferrals, and contradiction checks are recorded with the audit evidence contract.
+- Make `complete-milestone` inherit the audit posture and stop when unsupported claims, invalid waivers, missing evidence, incompatible posture metadata, or failed claim-scoped contradiction checks remain.
+- Keep `verify` out of the main release-claim decision path; phase verification still records evidence, while milestone audit and completion own release closeout.
+- Enforce the inherited contract in `lifecycle-preflight complete-milestone` so milestone completion cannot proceed from a passed audit that lacks release-claim metadata or still contains unsupported stronger claims, invalid waivers, missing required evidence, incompatible posture metadata, or failed claim-scoped contradiction checks.
+
+**Why this fits the codebase:**
+- It preserves the compact D50 evidence matrix and avoids a new `release` evidence kind.
+- It avoids a new workflow lane or `gsdd-release` command by using the existing closeout surfaces.
+- It lets repo-local milestones close without fabricated delivery proof while preventing stronger public/runtime/delivery language from outrunning evidence.
+- It respects D59: local-only planning artifacts can support internal closeout, but public release/support claims need tracked public or repo-visible evidence.
+
+**Waiver and deferral rule:**
+Waivers may narrow a claim posture or defer an unsupported claim, but they never satisfy missing required evidence for the stronger claim. Deferrals must name the unsupported claim, missing evidence kind(s), and later workflow or milestone candidate when known.
+
+**Contradiction checks:**
+Closeout must check evidence, public-surface, runtime, delivery, planning-drift, and generated-surface contradictions. Generated-surface drift blocks only claims that depend on generated runtime/helper freshness; it does not fail unrelated `repo_closeout` claims.
+
+Posture compatibility is part of that closeout contract: `repo_closeout` and `runtime_validated_closeout` are repo-local wording boundaries over `repo_only`, while `delivery_supported_closeout` requires the `delivery_sensitive` evidence bar.
+
+**Evidence:**
+- `.planning/phases/45-release-closeout-contract/45-APPROACH.md`
+- `.planning/phases/45-release-closeout-contract/45-PLAN.md`
+- `.planning/phases/48-generated-helper-and-closeout-contract-parity/48-PLAN.md`
+- `.planning/research/45-RESEARCH.md`
+- `.planning/SPEC.md` (`REL-02`, deferred `LSC-05`)
+- `.planning/ROADMAP.md` (Phase 45)
+- `bin/lib/evidence-contract.mjs`
+- `bin/lib/lifecycle-preflight.mjs`
+- `distilled/workflows/audit-milestone.md`
+- `distilled/workflows/complete-milestone.md`
+- `distilled/DESIGN.md` D50 and D59
+- `tests/phase.test.cjs`
+- `tests/gsdd.guards.test.cjs`
+- `tests/gsdd.scenarios.test.cjs`
+
+**Consequences:**
+- A milestone audit can now distinguish internal repo closeout, runtime-validated closeout, and delivery-supported closeout without changing evidence kinds.
+- Missing delivery or runtime evidence must produce a downgrade or deferral; it cannot be hidden behind human waiver prose.
+- `complete-milestone` now fails closed before archive writes when the passed audit omits or contradicts the release claim contract.
+- Public claims are scoped to tracked public or repo-visible proof, while GitHub Releases, tags, package publication, and release automation remain deferred until explicitly planned.
+
 ## Maintenance
 
 This document is updated when:

package/distilled/EVIDENCE-INDEX.md

@@ -101,7 +101,7 @@
 - `.internal-research/gsd-distilled-audit-13th-march-2026.md` — Highest-ROI recommendation #3
 
 ## D13 — Mechanical Invariant Enforcement
-- `tests/gsdd.invariants.test.cjs` lines 1015+ (6 suites, ~106 assertions)
+- `tests/gsdd.invariants.test.cjs` and `tests/gsdd.guards.test.cjs` enforce structural drift checks with actionable `FIX:` messages
 - OpenAI Harness Engineering blog (Feb 2026): "error messages as enforcement mechanism"
 - External audit (2026-03-13): recommendation #4 "Mechanize the framework's invariants"
 - PRs #20-23: orphan `</output>` tags survived 4 manual review cycles before G4 caught them
@@ -212,7 +212,8 @@
 - `get-shit-done/workflows/discuss-phase.md` (gray area identification, GSD source)
 - `get-shit-done/workflows/list-phase-assumptions.md` (5-dimension assumption surfacing)
 - `get-shit-done/workflows/discovery-phase.md` (3-level research workflow)
-- `agents/approach-explorer.md`, `distilled/templates/delegates/approach-explorer.md`
+- `agents/approach-explorer.md`, `distilled/templates/approach.md`, `distilled/templates/delegates/approach-explorer.md`, `distilled/templates/delegates/plan-checker.md`
+- `distilled/workflows/plan.md`, `bin/adapters/opencode.mjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.plan.adapters.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 
 ## D30 — Hardening Propagation
 - D28 consumer audit (2026-03-21): persistence failures at every workflow boundary
@@ -357,12 +358,12 @@
 ## D49 — Deterministic Lifecycle Preflight Gates
 - `.planning/SPEC.md` (`ENGINE-01`, `ENGINE-02`, `ENGINE-03`)
 - `.planning/ROADMAP.md` (Phase 30)
-- `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`
+- `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`, `bin/lib/session-fingerprint.mjs`
 - `bin/gsdd.mjs`, `bin/lib/init.mjs`
-- `distilled/workflows/execute.md`, `distilled/workflows/verify.md`
+- `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`
 - `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`
 - `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`
-- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+- `tests/phase.test.cjs`, `tests/session-fingerprint.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 - `get-shit-done/workflows/progress.md`
 
 ## D50 — Evidence-Gated Closure Matrix
@@ -454,6 +455,29 @@
 - `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`
 - `tests/gsdd.init.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.manifest.test.cjs`, `tests/phase.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 
+## D59 — Continuity Authority And Planning-State Drift
+- `.planning/phases/44-continuity-authority-and-persistence/44-APPROACH.md`
+- `.planning/phases/44-continuity-authority-and-persistence/44-PLAN.md`
+- `.planning/SPEC.md` (`REL-01`)
+- `.planning/ROADMAP.md` (Phase 44)
+- `.internal-research/gaps.md` (`I46`, `S6`)
+- `bin/lib/session-fingerprint.mjs`, `bin/lib/lifecycle-preflight.mjs`, `bin/lib/runtime-freshness.mjs`
+- `distilled/workflows/progress.md`, `distilled/workflows/resume.md`, `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`, `distilled/workflows/new-milestone.md`
+- `distilled/templates/brownfield-change/CHANGE.md`, `distilled/templates/brownfield-change/HANDOFF.md`, `distilled/templates/brownfield-change/VERIFICATION.md`
+- `tests/session-fingerprint.test.cjs`, `tests/phase.test.cjs`
+
+## D60 — Release Closeout Contract
+- `.planning/phases/45-release-closeout-contract/45-APPROACH.md`
+- `.planning/phases/45-release-closeout-contract/45-PLAN.md`
+- `.planning/phases/48-generated-helper-and-closeout-contract-parity/48-PLAN.md`
+- `.planning/research/45-RESEARCH.md`
+- `.planning/SPEC.md` (`REL-02`, deferred `LSC-05`)
+- `.planning/ROADMAP.md` (Phase 45)
+- `bin/lib/evidence-contract.mjs`, `bin/lib/lifecycle-preflight.mjs`
+- `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`
+- `distilled/DESIGN.md` D50 and D59
+- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+
 ---
 
 ## Maintenance

package/distilled/templates/approach.md

@@ -6,6 +6,8 @@ Template for `.planning/phases/XX-name/{phase_num}-APPROACH.md` — captures imp
 
 **Key principle:** The top-level structure (`<domain>`, `<decisions>`, `<assumptions>`, `<deferred>`) is fixed. Section names WITHIN `<decisions>` emerge from what was actually discussed for THIS phase — a CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
 
+**Alignment proof:** When `.planning/config.json` has `workflow.discuss: true`, every APPROACH artifact must include an `## Alignment Proof` section before `<domain>`. It must record the canonical fields `alignment_status`, `alignment_method`, `user_confirmed_at`, `explicit_skip_approved`, `skip_scope`, `skip_rationale`, and `confirmed_decisions`. `Agent's Discretion` and agent-only "No questions needed" are not valid proof.
+
 **Downstream consumers:**
 - `planner` — Reads decisions to constrain implementation choices. Locked decisions must be implemented. Agent's Discretion items allow planner flexibility.
 - `plan-checker` — Reads decisions to verify plans implement chosen approaches (approach_alignment dimension). Flags plans that contradict explicit user choices.
@@ -20,6 +22,18 @@ Template for `.planning/phases/XX-name/{phase_num}-APPROACH.md` — captures imp
 **Explored:** [date]
 **Status:** Ready for planning
 
+## Alignment Proof
+
+- `workflow.discuss`: [true | false]
+- `alignment_status`: [user_confirmed | approved_skip | not_required]
+- `alignment_method`: [conversation source, e.g. runtime command or user message]
+- `user_confirmed_at`: [date or N/A]
+- `explicit_skip_approved`: [true | false]
+- `skip_scope`: [phase-wide / named gray area / N/A]
+- `skip_rationale`: [why the user approved skipping discussion, or N/A]
+- `confirmed_decisions`:
+  - [User-confirmed decision, or "N/A - approved skip"]
+
 <domain>
 ## Phase Boundary
 
@@ -87,6 +101,19 @@ Template for `.planning/phases/XX-name/{phase_num}-APPROACH.md` — captures imp
 **Explored:** 2026-03-22
 **Status:** Ready for planning
 
+## Alignment Proof
+
+- `workflow.discuss`: true
+- `alignment_status`: user_confirmed
+- `alignment_method`: planning conversation
+- `user_confirmed_at`: 2026-03-22
+- `explicit_skip_approved`: false
+- `skip_scope`: N/A
+- `skip_rationale`: N/A
+- `confirmed_decisions`:
+  - Use Recharts for chart rendering
+  - Use react-grid-layout for dashboard widgets
+
 <domain>
 ## Phase Boundary
 
@@ -158,6 +185,19 @@ Build an interactive dashboard with configurable widgets. Users can view metrics
 **Explored:** 2026-03-22
 **Status:** Ready for planning
 
+## Alignment Proof
+
+- `workflow.discuss`: true
+- `alignment_status`: user_confirmed
+- `alignment_method`: planning conversation
+- `user_confirmed_at`: 2026-03-22
+- `explicit_skip_approved`: false
+- `skip_scope`: N/A
+- `skip_rationale`: N/A
+- `confirmed_decisions`:
+  - Use HTTP-only cookies with JWT
+  - Use structured JSON errors
+
 <domain>
 ## Phase Boundary
 

package/distilled/templates/delegates/approach-explorer.md

@@ -4,8 +4,11 @@ You are the approach explorer delegate for the plan workflow.
 
 **Your job:** Identify gray areas in the target phase, research viable approaches for technical decisions, conduct an adaptive conversation with the user to capture locked decisions, and write APPROACH.md to the phase directory.
 
+When `workflow.discuss: true`, APPROACH.md must prove user alignment before planning: use `alignment_status: user_confirmed` for real user-confirmed decisions or `alignment_status: approved_skip` only when the user explicitly approves skipping discussion. Record the canonical fields `alignment_method`, `user_confirmed_at`, `explicit_skip_approved`, `skip_scope`, `skip_rationale`, and `confirmed_decisions`. `Agent's Discretion` and agent-only "No questions needed" are not valid alignment proof.
+
 Read only the explicit inputs provided by the orchestrator:
 - target phase goal and requirement IDs from `.planning/ROADMAP.md`
+- project config from `.planning/config.json`, especially `workflow.discuss`
 - locked decisions and deferred items from `.planning/SPEC.md`
 - phase research file (if exists)
 - relevant codebase files (existing patterns and conventions)