gsdd-cli 0.27.0 → 0.28.0

package/bin/lib/lifecycle-state.mjs

@@ -293,7 +293,8 @@ export function readBrownfieldChangeState(planningDir) {
 }
 
 export function deriveNonPhaseState({ planningDir, hasSpec, hasRoadmap, brownfieldChange } = {}) {
-  if (brownfieldChange?.exists) return 'active_brownfield_change';
+  const brownfieldStatus = String(brownfieldChange?.currentStatus || '').trim().toLowerCase();
+  if (brownfieldChange?.exists && brownfieldStatus !== 'closed') return 'active_brownfield_change';
   if (hasRoadmap) return null;
   if (hasSpec) return 'between_milestones';
   if (hasSubstantiveCodebaseMaps(planningDir)) return 'codebase_only';

package/bin/lib/next.mjs

@@ -2,6 +2,7 @@ import { join } from 'path';
 import { existsSync } from 'fs';
 import { output, parseFlagValue } from './cli-utils.mjs';
 import { buildControlMap } from './control-map.mjs';
+import { resolveStateDir } from './state-dir.mjs';
 import {
   NEXT_STATES,
   addOpenQuestion,
@@ -68,6 +69,9 @@ function packet(overrides) {
     confidence: overrides.confidence || 'medium',
     next_command: overrides.next_command || null,
     next_action: overrides.next_action || null,
+    authority: overrides.authority || null,
+    route_kind: overrides.route_kind || null,
+    blocked_by: overrides.blocked_by || [],
     requires_user: Boolean(overrides.requires_user),
     questions: overrides.questions || [],
     constraints: overrides.constraints || [],
@@ -110,6 +114,15 @@ function manualReviewAction(targets, description) {
   };
 }
 
+function stateDirName(context) {
+  return context?.planning?.state_dir_name || '.work';
+}
+
+function statePath(context, relativePath = '') {
+  const dirName = stateDirName(context);
+  return relativePath ? `${dirName}/${relativePath}` : dirName;
+}
+
 function userQuestionAction(questionIds, description) {
   return {
     type: 'user_question',
@@ -120,9 +133,10 @@ function userQuestionAction(questionIds, description) {
 
 function summarizeControlMap(cwd) {
   try {
+    const stateDir = resolveStateDir(cwd).dir;
     return buildControlMap({
       workspaceRoot: cwd,
-      planningDir: join(cwd, '.planning'),
+      planningDir: stateDir,
     });
   } catch (error) {
     return {
@@ -145,10 +159,29 @@ function readManifestStatus(context) {
 
 function repoWarningsFromControlMap(controlMap) {
   return (controlMap.risks || [])
-    .filter((risk) => risk.code === 'canonical_dirty')
+    .filter((risk) => risk.code === 'canonical_dirty' || risk.severity === 'block')
     .map((risk) => risk.message);
 }
 
+function controlMapBlockers(controlMap) {
+  return (controlMap.risks || [])
+    .filter((risk) => risk.severity === 'block')
+    .map((risk) => risk.code);
+}
+
+function hasActiveBrownfieldChange(context) {
+  return brownfieldPosture(context) === 'active';
+}
+
+function brownfieldPosture(context) {
+  if (!context.planning.has_brownfield_change) return null;
+  const status = String(context.planning.brownfield_change?.currentStatus || '').trim().toLowerCase();
+  if (status === 'closed') return 'closed';
+  if (status === 'ready_for_verification') return 'ready_for_verification';
+  if (status === 'blocked') return 'blocked';
+  return 'active';
+}
+
 function routeFromStateObject(stateValue) {
   const state = stateValue || {};
   const workflow = state.workflow || state.milestone || state;
@@ -277,6 +310,7 @@ function routeNext(ctx) {
   if (context.milestone?.has_audit) inputsConsidered.push('.work/milestone/AUDIT.md');
   else inputsSkipped.push('.work/milestone/AUDIT.md: missing');
   if (context.milestone?.phase_packet_count > 0) inputsConsidered.push('.work/milestone/phases/*');
+  if (context.planning.has_brownfield_change) inputsConsidered.push(statePath(context, 'brownfield-change/CHANGE.md'));
 
   if (context.graph.invalid.length > 0) {
     return packet({
@@ -423,8 +457,114 @@ function routeNext(ctx) {
     }, { context, controlMap, constraints, privacyNotes, inputsConsidered, inputsSkipped, traceRefs });
   }
 
+  const brownfieldStatus = brownfieldPosture(context);
+  if (['active', 'blocked', 'ready_for_verification'].includes(brownfieldStatus) && context.milestone?.exists) {
+    return packet({
+      state: 'blocked',
+      reason: 'Active brownfield-change authority and .work/milestone authority both exist; continuing would silently choose between two continuity roots.',
+      confidence: 'high',
+      next_command: null,
+      next_action: manualReviewAction([statePath(context, 'brownfield-change/CHANGE.md'), '.work/milestone/MILESTONE.md', '.work/milestone/ROADMAP.md'], 'Resolve the authority conflict before routing to plan, execute, or verify.'),
+      authority: 'blocked',
+      route_kind: 'authority_conflict',
+      blocked_by: ['brownfield_change', 'work_milestone'],
+      requires_user: false,
+      constraints,
+      evidence_required: ['One continuity authority must be selected or archived before continuing.'],
+      artifacts_to_read: [statePath(context, 'brownfield-change/CHANGE.md'), '.work/milestone/MILESTONE.md', '.work/milestone/ROADMAP.md'],
+      repo_warnings: repoWarningsFromControlMap(controlMap),
+      privacy_notes: privacyNotes,
+      inputs_considered: inputsConsidered,
+      inputs_skipped: inputsSkipped,
+      trace_refs: traceRefs,
+    });
+  }
+
+  if (brownfieldStatus === 'blocked') {
+    return packet({
+      state: 'blocked',
+      reason: 'Active bounded brownfield change is marked blocked; resolve the blocker recorded in CHANGE.md before planning or execution.',
+      confidence: 'high',
+      next_command: null,
+      next_action: manualReviewAction([statePath(context, 'brownfield-change/CHANGE.md'), statePath(context, 'brownfield-change/HANDOFF.md')], 'Resolve the blocker and update the brownfield change status before continuing.'),
+      authority: 'brownfield_change',
+      route_kind: 'brownfield_change_blocked',
+      blocked_by: ['brownfield_change'],
+      requires_user: false,
+      constraints,
+      artifacts_to_read: [statePath(context, 'brownfield-change/CHANGE.md'), statePath(context, 'brownfield-change/HANDOFF.md')],
+      artifacts_to_write: [statePath(context, 'brownfield-change/CHANGE.md'), statePath(context, 'brownfield-change/HANDOFF.md')],
+      repo_warnings: repoWarningsFromControlMap(controlMap),
+      privacy_notes: privacyNotes,
+      inputs_considered: inputsConsidered,
+      inputs_skipped: inputsSkipped,
+      trace_refs: traceRefs,
+    });
+  }
+
+  if (brownfieldStatus === 'ready_for_verification') {
+    return packet({
+      state: 'verify',
+      reason: 'Active bounded brownfield change is ready for verification; verify the bounded closeout proof before more planning.',
+      confidence: 'high',
+      next_command: null,
+      next_action: manualReviewAction([statePath(context, 'brownfield-change/CHANGE.md'), statePath(context, 'brownfield-change/VERIFICATION.md')], 'Verify the bounded brownfield change and update VERIFICATION.md.'),
+      authority: 'brownfield_change',
+      route_kind: 'brownfield_change_verification',
+      requires_user: false,
+      constraints,
+      evidence_required: ['VERIFICATION.md must prove the CHANGE.md done-when and closeout path or record concrete gaps.'],
+      artifacts_to_read: [
+        statePath(context, 'brownfield-change/CHANGE.md'),
+        statePath(context, 'brownfield-change/HANDOFF.md'),
+        statePath(context, 'brownfield-change/VERIFICATION.md'),
+      ],
+      artifacts_to_write: [statePath(context, 'brownfield-change/VERIFICATION.md')],
+      repo_warnings: repoWarningsFromControlMap(controlMap),
+      privacy_notes: privacyNotes,
+      inputs_considered: inputsConsidered,
+      inputs_skipped: inputsSkipped,
+      trace_refs: traceRefs,
+    });
+  }
+
+  if (brownfieldStatus === 'active') {
+    return packet({
+      state: 'plan',
+      reason: 'Active bounded brownfield change exists; route planning through the brownfield change lane before phase roadmap preflight.',
+      confidence: 'high',
+      next_command: 'gsdd-plan',
+      next_action: workflowAction('gsdd-plan', 'Plan the active bounded brownfield change from CHANGE.md and HANDOFF.md without requiring unrelated ROADMAP phase membership.'),
+      authority: 'brownfield_change',
+      route_kind: 'brownfield_change',
+      requires_user: false,
+      constraints: [
+        ...constraints,
+        `Bounded brownfield changes use \`${statePath(context, 'brownfield-change/')}\`, not \`${statePath(context, 'phases/')}\` or ROADMAP checkboxes.`,
+        'Promote to `gsdd-new-project` or `gsdd-new-milestone` only when the change no longer fits one active stream.',
+      ],
+      evidence_required: ['Plan must preserve the bounded CHANGE.md goal, scope, done-when, next action, and closeout path.'],
+      artifacts_to_read: [
+        statePath(context, 'brownfield-change/CHANGE.md'),
+        statePath(context, 'brownfield-change/HANDOFF.md'),
+        statePath(context, 'brownfield-change/VERIFICATION.md'),
+        statePath(context, 'SPEC.md'),
+        statePath(context, 'ROADMAP.md'),
+      ],
+      artifacts_to_write: [
+        statePath(context, 'brownfield-change/CHANGE.md'),
+        statePath(context, 'brownfield-change/HANDOFF.md'),
+      ],
+      repo_warnings: repoWarningsFromControlMap(controlMap),
+      privacy_notes: privacyNotes,
+      inputs_considered: inputsConsidered,
+      inputs_skipped: inputsSkipped,
+      trace_refs: traceRefs,
+    });
+  }
+
   if (hasUnverifiedSummaries(context.planning.phases)) {
-    return enrichRoute({ state: 'verify', reason: 'Legacy `.planning` phase summaries exist without matching verification reports.' }, { context, controlMap, constraints, privacyNotes, inputsConsidered, inputsSkipped, traceRefs });
+    return enrichRoute({ state: 'verify', reason: `${statePath(context)} phase summaries exist without matching verification reports.` }, { context, controlMap, constraints, privacyNotes, inputsConsidered, inputsSkipped, traceRefs });
   }
 
   const workMilestoneRoute = routeFromWorkMilestone(context, manifest);
@@ -436,14 +576,18 @@ function routeNext(ctx) {
   if (!legacyComplete) {
     return packet({
       state: 'plan',
-      reason: '`.work/goal.md` exists, but canonical `.planning` lifecycle truth is incomplete; create or refresh the Workspine-native plan from `.work`.',
+      reason: `\`.work/goal.md\` exists, but canonical ${statePath(context)} lifecycle truth is incomplete; create or refresh the Workspine-native plan from \`.work\`.`,
       confidence: context.planning.exists ? 'medium' : 'high',
       next_command: 'gsdd-plan',
       next_action: workflowAction('gsdd-plan', 'Plan the Workspine-native milestone from `.work` truth.'),
+      authority: 'work',
+      route_kind: 'work_native_plan',
+      blocked_by: controlMapBlockers(controlMap),
+      repo_warnings: repoWarningsFromControlMap(controlMap),
       requires_user: false,
       constraints: [
         ...constraints,
-        'Do not infer normal `.planning` milestone progress when SPEC.md, ROADMAP.md, or MILESTONES.md are missing.',
+        `Do not infer normal ${statePath(context)} milestone progress when SPEC.md, ROADMAP.md, or MILESTONES.md are missing.`,
       ],
       evidence_required: ['Plan must map `.work/goal.md` requirements to implementation and verification artifacts.'],
       artifacts_to_read: ['.work/goal.md', '.work/research/2026-06-20-long-term-agent-harness-consistency.md'],
@@ -452,9 +596,9 @@ function routeNext(ctx) {
       inputs_considered: inputsConsidered,
       inputs_skipped: [
         ...inputsSkipped,
-        !context.planning.has_spec ? '.planning/SPEC.md: missing' : null,
-        !context.planning.has_roadmap ? '.planning/ROADMAP.md: missing' : null,
-        !context.planning.has_milestones ? '.planning/MILESTONES.md: missing' : null,
+        !context.planning.has_spec ? `${statePath(context, 'SPEC.md')}: missing` : null,
+        !context.planning.has_roadmap ? `${statePath(context, 'ROADMAP.md')}: missing` : null,
+        !context.planning.has_milestones ? `${statePath(context, 'MILESTONES.md')}: missing` : null,
       ].filter(Boolean),
       trace_refs: traceRefs,
     });
@@ -466,9 +610,13 @@ function routeNext(ctx) {
     confidence: 'medium',
     next_command: 'gsdd-plan',
     next_action: workflowAction('gsdd-plan', 'Plan the next approved work slice.'),
+    authority: 'planning',
+    route_kind: 'phase_plan',
+    blocked_by: controlMapBlockers(controlMap),
+    repo_warnings: repoWarningsFromControlMap(controlMap),
     requires_user: false,
     constraints,
-    artifacts_to_read: ['.work/goal.md', '.planning/SPEC.md', '.planning/ROADMAP.md', '.planning/MILESTONES.md'],
+    artifacts_to_read: ['.work/goal.md', statePath(context, 'SPEC.md'), statePath(context, 'ROADMAP.md'), statePath(context, 'MILESTONES.md')],
     artifacts_to_write: ['.work/focus/current.md'],
     privacy_notes: privacyNotes,
     inputs_considered: inputsConsidered,
@@ -523,7 +671,7 @@ function enrichRoute(route, { context, controlMap, constraints, privacyNotes, in
     execute: workflowAction('gsdd-execute', 'Execute the approved Workspine plan.'),
     verify: workflowAction('gsdd-verify', 'Verify executed artifacts against the plan.'),
     audit: workflowAction('gsdd-audit-milestone', 'Audit milestone-level integration and closure evidence.'),
-    fix_gaps: workflowAction('gsdd-plan-milestone-gaps', 'Plan gap-fix work from audit or verification findings.'),
+    fix_gaps: workflowAction('gsdd-plan', 'Plan amend/extend work from audit or verification findings.'),
     dogfood: cliAction(['next', 'dogfood', 'capture', '--id', '<id>', '--title', '<text>', '--body', '<text>'], 'Capture one bounded local dogfood finding.'),
     pause: manualReviewAction(['.work/handoff/current.md'], 'Update handoff before pausing.'),
     blocked: null,
@@ -537,6 +685,9 @@ function enrichRoute(route, { context, controlMap, constraints, privacyNotes, in
     confidence: route.state === 'blocked' || route.state === 'ask_user' ? 'high' : 'medium',
     next_command: route.next_command || actionToLegacyCommand(nextAction),
     next_action: nextAction,
+    authority: route.authority || inferAuthorityForState(route.state, context),
+    route_kind: route.route_kind || route.state,
+    blocked_by: [...(route.blocked_by || []), ...controlMapBlockers(controlMap)],
     requires_user: route.state === 'ask_user',
     questions: route.questions || [],
     constraints,
@@ -551,6 +702,13 @@ function enrichRoute(route, { context, controlMap, constraints, privacyNotes, in
   });
 }
 
+function inferAuthorityForState(state, context) {
+  if (context.milestone?.exists) return 'work_milestone';
+  if (hasActiveBrownfieldChange(context)) return 'brownfield_change';
+  if (state === 'blocked') return 'blocked';
+  return 'planning';
+}
+
 function actionToLegacyCommand(action) {
   if (!action) return null;
   if (action.type === 'cli_command') return action.command;
@@ -562,11 +720,11 @@ function defaultReadArtifacts(state, context) {
   if (state === 'execute') return ['.work/goal.md', '.work/focus/current.md'];
   if (state === 'verify') return context.milestone?.has_roadmap
     ? ['.work/goal.md', '.work/milestone/ROADMAP.md', '.work/milestone/phases/*/*-VERIFY.md']
-    : ['.work/goal.md', '.work/evidence/manifest.json', '.planning/phases/*/*-SUMMARY.md'];
+    : ['.work/goal.md', '.work/evidence/manifest.json', statePath(context, 'phases/*/*-SUMMARY.md')];
   if (state === 'audit') return context.milestone?.has_roadmap
     ? ['.work/goal.md', '.work/milestone/ROADMAP.md', '.work/milestone/phases/*/*-VERIFY.md']
-    : ['.work/goal.md', '.work/evidence/manifest.json', '.planning/phases/**/*-VERIFICATION.md'];
-  if (state === 'fix_gaps') return ['.work/evidence/manifest.json'];
+    : ['.work/goal.md', '.work/evidence/manifest.json', statePath(context, 'phases/**/*-VERIFICATION.md')];
+  if (state === 'fix_gaps') return ['.work/evidence/manifest.json', '.work/*-MILESTONE-AUDIT.md', '.work/milestone/AUDIT.md'];
   if (state === 'dogfood') return ['.work/goal.md', '.work/evidence/manifest.json'];
   if (state === 'pause') return ['.work/handoff/current.md'];
   if (state === 'complete') return ['.work/goal.md', '.work/evidence/manifest.json', '.work/dogfood/'];
@@ -577,7 +735,7 @@ function defaultReadArtifacts(state, context) {
 function defaultWriteArtifacts(state) {
   if (state === 'verify') return ['.work/evidence/manifest.json'];
   if (state === 'audit') return ['.work/evidence/manifest.json'];
-  if (state === 'fix_gaps') return ['.work/focus/current.md', '.work/graph/events.jsonl'];
+  if (state === 'fix_gaps') return ['.work/ROADMAP.md', '.work/phases/', '.work/focus/current.md', '.work/graph/events.jsonl'];
   if (state === 'dogfood') return ['.work/dogfood/*.md', '.work/graph/events.jsonl'];
   if (state === 'pause') return ['.work/handoff/current.md'];
   return [];
@@ -601,13 +759,78 @@ function findTrustGate(manifest) {
   };
 }
 
+const CARD_WIDTH = 62;
+
+const STATE_LABELS = {
+  research: 'Look into the problem before planning',
+  plan: 'Plan the next piece of work',
+  execute: 'Build the planned work',
+  verify: 'Prove the last piece of work is done',
+  audit: 'Check the whole milestone holds together',
+  fix_gaps: 'Plan the gaps that checking found',
+  dogfood: 'Use the result and record one honest finding',
+  complete: 'Finish and archive the milestone',
+  ask_user: 'Answer a question before work can continue',
+  pause: 'Work is paused; pick it back up when ready',
+  blocked: 'Work is stuck; clear the blocker below',
+};
+
+function cardFrame(text) {
+  return `│${text.padEnd(CARD_WIDTH)}│`;
+}
+
+function pushCardLine(rows, indent, hang, text) {
+  const words = String(text).split(/\s+/).filter(Boolean);
+  if (words.length === 0) {
+    rows.push(cardFrame(' '.repeat(indent)));
+    return;
+  }
+  let prefix = ' '.repeat(indent);
+  let line = prefix;
+  for (const word of words) {
+    const candidate = line === prefix ? line + word : `${line} ${word}`;
+    if (candidate.length <= CARD_WIDTH) {
+      line = candidate;
+    } else {
+      rows.push(cardFrame(line));
+      prefix = ' '.repeat(hang);
+      line = prefix + word;
+    }
+  }
+  rows.push(cardFrame(line));
+}
+
+export function renderNextCard(packetValue) {
+  const top = `┌${'─'.repeat(CARD_WIDTH)}┐`;
+  const rule = `├${'─'.repeat(CARD_WIDTH)}┤`;
+  const bottom = `└${'─'.repeat(CARD_WIDTH)}┘`;
+  const label = STATE_LABELS[packetValue.state] || packetValue.state;
+  const action = (packetValue.next_action ? renderAction(packetValue.next_action) : null)
+    || packetValue.next_command
+    || '(nothing queued)';
+  const waiting = packetValue.requires_user ? 'yes' : 'no';
+
+  const rows = [top];
+  rows.push(cardFrame('  Where things stand'));
+  rows.push(rule);
+  pushCardLine(rows, 2, 7, `Now: ${label}`);
+  pushCardLine(rows, 2, 7, `Why: ${packetValue.reason || ''}`);
+  rows.push(cardFrame(''));
+  rows.push(cardFrame('  Do this next:'));
+  pushCardLine(rows, 4, 4, action);
+  rows.push(cardFrame(''));
+  rows.push(cardFrame(`  Waiting on you:  ${waiting}`));
+  rows.push(cardFrame(''));
+  rows.push(cardFrame('  Stuck?  Run: gsdd next --format human'));
+  rows.push(cardFrame(''));
+  rows.push(cardFrame('  Safety checks — this computer: not set up yet ·'));
+  rows.push(cardFrame('                 server: not set up yet'));
+  rows.push(bottom);
+  return rows.join('\n');
+}
+
 function printHuman(packetValue) {
-  console.log(`gsdd next: ${packetValue.state}`);
-  console.log(`Why: ${packetValue.reason}`);
-  if (packetValue.next_action) console.log(`Next: ${renderAction(packetValue.next_action)}`);
-  else if (packetValue.next_command) console.log(`Next: ${packetValue.next_command}`);
-  if (packetValue.requires_user) console.log('Approval: required');
-  else console.log('Approval: not required');
+  console.log(renderNextCard(packetValue));
   if (packetValue.questions.length > 0) {
     console.log('\nQuestions:');
     for (const question of packetValue.questions) {