@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

package/src/resources/extensions/gsd/guidance.ts

@@ -0,0 +1,217 @@
+// Project/App: gsd-pi
+// File Purpose: Guidance module — the single catalog mapping typed findings
+// (Recovery kinds, milestone blocker kinds, doctor issue codes, crash unit
+// classes) to user-facing remediation: what happened and what to do next.
+//
+// Emit sites pass the typed finding; phrasing, command names, and step
+// ordering live here. A missing catalog row is a visible gap, not a silent
+// omission scattered across call sites.
+
+import type { RecoveryFailureKind } from "./recovery-classification.js";
+import type { DoctorIssueCode } from "./doctor-types.js";
+
+// ─── Shape ──────────────────────────────────────────────────────────────
+
+export interface Guidance {
+  summary: string;
+  steps: string[];
+}
+
+/** Flatten guidance into a notification / pause-banner string. */
+export function formatGuidance(guidance: Guidance): string {
+  if (guidance.steps.length === 0) return guidance.summary;
+  const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
+  return `${guidance.summary}\n\n${numbered}`;
+}
+
+// ─── Recovery Classification remediation ────────────────────────────────
+// Keyed by RecoveryFailureKind. The provider kind is split by transience,
+// which Recovery Classification resolves before looking up guidance.
+
+export type RecoveryGuidanceKey =
+  | Exclude<RecoveryFailureKind, "provider">
+  | "provider-transient"
+  | "provider-permanent";
+
+const RECOVERY_REMEDIATION: Record<RecoveryGuidanceKey, string> = {
+  "tool-schema": "Fix the Unit Tool Contract or tool schema before retrying.",
+  "tool-contract":
+    "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+  "tool-unavailable":
+    "The tool surface had not finished registering when the Unit called it (workflow MCP startup race). Retry after the surface is ready; escalate if the tool never appears.",
+  "deterministic-policy": "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+  "lifecycle-progression":
+    "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+  "stale-worker":
+    "Run `/gsd doctor` to detect and clear the stale worker or lock, then run `/gsd auto` to resume.",
+  "worktree-invalid":
+    "Run `/gsd doctor` to diagnose the milestone worktree (`gsd worktree list` shows its state). Repair it, or merge salvageable work with `gsd worktree merge <name>` before recreating — recreating discards uncommitted work.",
+  "verification-drift":
+    "Run `/gsd status` to see the verification finding, fix or re-run the verification, then run `/gsd auto` to resume. `/gsd doctor` can repair stale state files.",
+  "reconciliation-drift":
+    "Run `/gsd doctor` to surface the persistent or repair-failed drift kinds, apply its fixes, then run `/gsd auto` to resume.",
+  "illegal-transition":
+    "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+  "runtime-unknown": "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+  "provider-transient": "Retry after the provider/network condition clears.",
+  "provider-permanent": "Inspect provider credentials, model entitlement, or request shape.",
+};
+
+export function recoveryRemediation(key: RecoveryGuidanceKey): string {
+  return RECOVERY_REMEDIATION[key];
+}
+
+// ─── Milestone validation blockers ──────────────────────────────────────
+// NOTE: the first line of each blocker is load-bearing — validation-block-guard
+// matches /milestone validation returned needs-(?:attention|remediation)/i.
+// Keep that phrase intact when editing.
+
+export function needsAttentionBlockerGuidance(milestoneId: string): string {
+  return [
+    `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
+    `Fix options:`,
+    `1. Review the validation details: \`/gsd status\``,
+    `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
+    `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+    `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+    `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
+  ].join("\n");
+}
+
+export function needsRemediationBlockerGuidance(milestoneId: string): string {
+  return [
+    `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
+    `Fix options:`,
+    `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
+    `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+    `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+  ].join("\n");
+}
+
+// ─── Milestone closeout UAT sign-off blockers ───────────────────────────
+// The first sentence is the blocker finding; the numbered steps are the
+// resolution path. `verdict` is the recorded non-PASS verdict, or undefined
+// when no verdict has been recorded at all.
+
+export function uatSignoffBlockerGuidance(
+  milestoneId: string,
+  sliceId: string,
+  verdict?: string,
+): string {
+  const finding =
+    verdict === undefined
+      ? `missing UAT PASS verdict for ${sliceId}`
+      : `UAT verdict for ${sliceId} is "${verdict}"`;
+  const sliceSpecificRerunStep =
+    `If ${sliceId} is not the most recently completed slice, type a chat request to re-run UAT for ${sliceId}; run-uat will record the verdict through \`gsd_uat_result_save\`.`;
+  const steps =
+    verdict === undefined
+      ? [
+          `1. Run UAT for the most recently completed slice to record a verdict: \`/gsd dispatch uat\``,
+          `2. ${sliceSpecificRerunStep}`,
+          `3. Review the UAT criteria and progress: \`/gsd status\``,
+          `4. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ]
+      : [
+          `1. Review the failing UAT findings: \`/gsd status\` (the ${sliceId} ASSESSMENT records what failed)`,
+          `2. Fix the issue, then re-run UAT for the most recently completed slice to record a fresh verdict: \`/gsd dispatch uat\``,
+          `3. ${sliceSpecificRerunStep}`,
+          `4. If the fix needs new implementation work, add remediation slices: \`/gsd dispatch reassess\``,
+          `5. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ];
+  return [
+    `Cannot complete milestone ${milestoneId}: ${finding}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+    `Fix options:`,
+    ...steps,
+  ].join("\n");
+}
+
+// ─── Worktree isolation degradation ─────────────────────────────────────
+// The first sentence of each notice is load-bearing for log matching and
+// tests — keep it intact and append guidance after it.
+
+function restoreIsolationHint(milestoneId: string): string {
+  return `To restore isolation: close any processes using the old worktree, merge salvageable work with \`/gsd worktree merge ${milestoneId}\` or remove the stale worktree with \`/gsd worktree remove ${milestoneId}\`, then run \`/gsd doctor fix\`.`;
+}
+
+export function worktreeCreationFailedGuidance(milestoneId: string, error: string): string {
+  return [
+    `Auto-worktree creation for ${milestoneId} failed: ${error}. Continuing in project root.`,
+    `Worktree isolation is degraded for this session.`,
+    restoreIsolationHint(milestoneId),
+  ].join("\n");
+}
+
+export function isolationDegradedFallbackGuidance(milestoneId: string): string {
+  return [
+    `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
+    `Work continues safely on the milestone branch in the project root.`,
+    restoreIsolationHint(milestoneId),
+  ].join("\n");
+}
+
+/** Hard entry blockers from auto-start: bootstrap stopped, user must act. */
+export function milestoneEntryBlockedGuidance(
+  milestoneId: string,
+  reason: "creation-failed" | "isolation-degraded",
+): string {
+  const finding =
+    reason === "creation-failed"
+      ? `worktree/branch creation failed. Isolation is degraded.`
+      : `isolation is degraded from a prior worktree failure.`;
+  return [
+    `Cannot enter milestone ${milestoneId}: ${finding}`,
+    restoreIsolationHint(milestoneId),
+    `Then run \`/gsd auto\` to retry.`,
+  ].join("\n");
+}
+
+// ─── Crash recovery resume hints ────────────────────────────────────────
+
+/** Resume hint for an interrupted auto-mode unit, by unit class. */
+export function crashResumeHint(unitType: string, unitId: string): string | undefined {
+  if (unitType === "starting" && unitId === "bootstrap") {
+    return `No work was lost. Run /gsd auto to restart.`;
+  }
+  if (unitType.includes("research") || unitType.includes("plan")) {
+    return `The ${unitType} unit may be incomplete. Run /gsd auto to re-run it.`;
+  }
+  if (unitType.includes("execute")) {
+    return `Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`;
+  }
+  if (unitType.includes("complete")) {
+    return `Slice/milestone completion was interrupted. Run /gsd auto to finish.`;
+  }
+  return undefined;
+}
+
+// ─── Doctor issue fix hints ─────────────────────────────────────────────
+// Partial by design: codes without a row render no hint. Add rows here as
+// guidance is authored — the gap is visible in one place.
+
+const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
+  db_unavailable:
+    "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
+  stale_crash_lock: "Run `/gsd doctor fix` to clear the stale lock, then `/gsd auto` to resume.",
+  stale_parallel_session: "Run `/gsd doctor fix` to clear the stale session registration.",
+  unresolved_git_conflicts:
+    "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
+  conflict_markers_in_tracked_files:
+    "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
+  worktree_dirty:
+    "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
+  worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
+  orphaned_auto_worktree: "Run `/gsd doctor fix` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+  gitignore_missing_patterns: "Run `/gsd doctor fix` to append the missing .gitignore patterns.",
+  invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
+  provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
+  provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
+  state_file_stale: "Run `/gsd doctor fix` to rebuild the projection from the database.",
+  state_file_missing: "Run `/gsd doctor fix` to rebuild the projection from the database.",
+  projection_drift: "Run `/gsd doctor fix` to rebuild markdown projections from the database (DB is the source of truth).",
+  uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
+};
+
+export function doctorFixHint(code: DoctorIssueCode): string | undefined {
+  return DOCTOR_FIX_HINTS[code];
+}

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -20,6 +20,7 @@ import { invalidateAllCaches } from "./cache.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile,
   resolveGsdRootFile, relGsdRootFile, relSliceFile,
+  relMilestoneFile,
 } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -29,6 +30,10 @@ import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 import { isFutureMilestoneStatus } from "./status-guards.js";
 
+const QUEUE_ARTIFACT_EXCERPT_MAX_CHARS = 20_000;
+const QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS = 120_000;
+const QUEUE_CONTEXT_SECTION_SEPARATOR = "\n\n---\n\n";
+
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 
 /**
@@ -280,7 +285,9 @@ export async function buildExistingMilestonesContext(
     if (contextFile) {
       const content = await loadFile(contextFile);
       if (content) {
-        parts.push(`\n**Context:**\n${content.trim()}`);
+        parts.push(
+          `\n**Context:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "CONTEXT"))}`,
+        );
       }
     } else {
       // No full CONTEXT.md — check for CONTEXT-DRAFT.md (draft seed from prior discussion)
@@ -288,7 +295,9 @@ export async function buildExistingMilestonesContext(
       if (draftFile) {
         const draftContent = await loadFile(draftFile);
         if (draftContent) {
-          parts.push(`\n**Draft context available:**\n${draftContent.trim()}`);
+          parts.push(
+            `\n**Draft context available:**\n${summarizeArtifactForQueue(draftContent, relMilestoneFile(basePath, mid, "CONTEXT-DRAFT"))}`,
+          );
         }
       }
     }
@@ -300,7 +309,9 @@ export async function buildExistingMilestonesContext(
       if (roadmapFile) {
         const content = await loadFile(roadmapFile);
         if (content) {
-          parts.push(`\n**Roadmap:**\n${content.trim()}`);
+          parts.push(
+            `\n**Roadmap:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "ROADMAP"))}`,
+          );
         }
       }
     }
@@ -317,7 +328,81 @@ export async function buildExistingMilestonesContext(
     }
   }
 
-  return sections.join("\n\n---\n\n");
+  return capExistingMilestonesContext(sections);
+}
+
+function summarizeArtifactForQueue(
+  content: string,
+  sourcePath: string,
+  cap = QUEUE_ARTIFACT_EXCERPT_MAX_CHARS,
+): string {
+  const trimmed = content.trim();
+  if (trimmed.length <= cap) {
+    return `Source: \`${sourcePath}\`\n\n${trimmed}`;
+  }
+
+  const excerpt = trimmed.slice(0, cap).trimEnd();
+  const omittedChars = trimmed.length - excerpt.length;
+  return [
+    `Source: \`${sourcePath}\``,
+    "",
+    excerpt,
+    "",
+    `[Truncated ${omittedChars} chars. Read \`${sourcePath}\` for full content.]`,
+  ].join("\n");
+}
+
+function capExistingMilestonesContext(
+  sections: string[],
+  cap = QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS,
+): string {
+  const fullContext = sections.join(QUEUE_CONTEXT_SECTION_SEPARATOR);
+  if (fullContext.length <= cap) return fullContext;
+
+  const notice = `[Existing milestones context truncated to ${cap} chars. Read source paths in this prompt or the corresponding .gsd artifacts for full details.]`;
+  const noticeSuffix = `${QUEUE_CONTEXT_SECTION_SEPARATOR}${notice}`;
+
+  const selected: string[] = [];
+  for (const section of sections) {
+    const candidate = [...selected, section].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (candidate.length <= cap) {
+      selected.push(section);
+      continue;
+    }
+    break;
+  }
+
+  if (selected.length === sections.length) {
+    return selected.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  }
+
+  const compactTail = sections.slice(selected.length).map(compactSectionForQueueBudget);
+  const hybrid = [...selected, ...compactTail].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  if (hybrid.length <= cap) return hybrid;
+
+  const compact = sections.map(compactSectionForQueueBudget);
+  const compactContext = compact.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  if (compactContext.length <= cap) return compactContext;
+
+  return `${compactContext.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
+}
+
+function compactSectionForQueueBudget(section: string): string {
+  const lines = section.split("\n");
+  const compact: string[] = [];
+
+  if (lines[0]) compact.push(lines[0]);
+
+  const statusLine = lines.find(line => line.startsWith("**Status:**"));
+  if (statusLine) compact.push(statusLine);
+
+  const sourceLines = lines.filter(line => line.startsWith("Source: `"));
+  if (sourceLines.length > 0) {
+    compact.push("", "**Sources:**", ...sourceLines);
+    compact.push("", "[Artifact excerpts omitted due to total queue/rethink context budget.]");
+  }
+
+  return compact.join("\n");
 }
 
 // ─── Internal Helpers ───────────────────────────────────────────────────────