gsd-pi 2.74.0-dev.b741afb → 2.74.0-dev.ffbcc03

package/src/resources/extensions/gsd/commands-extract-learnings.ts

@@ -0,0 +1,304 @@
+/**
+ * GSD Command — /gsd extract-learnings
+ *
+ * Analyses completed milestone artefacts and dispatches an LLM turn that
+ * extracts structured knowledge into 4 categories:
+ *   Decisions · Lessons · Patterns · Surprises
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+
+import { gsdRoot, resolveMilestonePath } from "./paths.js";
+import { projectRoot } from "./commands/context.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface PhaseArtifacts {
+  plan: string | null;
+  summary: string | null;
+  verification: string | null;
+  uat: string | null;
+  missingRequired: string[];
+}
+
+export interface ExtractLearningsPromptContext {
+  milestoneId: string;
+  milestoneName: string;
+  outputPath: string;
+  relativeOutputPath: string;
+  planContent: string;
+  summaryContent: string;
+  verificationContent: string | null;
+  uatContent: string | null;
+  missingArtifacts: string[];
+  projectName: string;
+}
+
+export interface FrontmatterContext {
+  milestoneId: string;
+  milestoneName: string;
+  projectName: string;
+  generatedAt: string;
+  counts: {
+    decisions: number;
+    lessons: number;
+    patterns: number;
+    surprises: number;
+  };
+  missingArtifacts: string[];
+}
+
+// ─── Pure functions ───────────────────────────────────────────────────────────
+
+export function parseExtractLearningsArgs(args: string): { milestoneId: string | null } {
+  const trimmed = args.trim();
+  return { milestoneId: trimmed || null };
+}
+
+export function buildLearningsOutputPath(milestoneDir: string, milestoneId: string): string {
+  return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
+}
+
+export function resolvePhaseArtifacts(milestoneDir: string, milestoneId: string): PhaseArtifacts {
+  const missingRequired: string[] = [];
+
+  const planFile = `${milestoneId}-PLAN.md`;
+  const summaryFile = `${milestoneId}-SUMMARY.md`;
+  const verificationFile = `${milestoneId}-VERIFICATION.md`;
+  const uatFile = `${milestoneId}-UAT.md`;
+
+  const planPath = join(milestoneDir, planFile);
+  const summaryPath = join(milestoneDir, summaryFile);
+  const verificationPath = join(milestoneDir, verificationFile);
+  const uatPath = join(milestoneDir, uatFile);
+
+  const plan = existsSync(planPath) ? planPath : null;
+  const summary = existsSync(summaryPath) ? summaryPath : null;
+  const verification = existsSync(verificationPath) ? verificationPath : null;
+  const uat = existsSync(uatPath) ? uatPath : null;
+
+  if (!plan) missingRequired.push(planFile);
+  if (!summary) missingRequired.push(summaryFile);
+
+  return { plan, summary, verification, uat, missingRequired };
+}
+
+export function buildExtractLearningsPrompt(ctx: ExtractLearningsPromptContext): string {
+  const optionalSections: string[] = [];
+
+  if (ctx.verificationContent) {
+    optionalSections.push(`## Verification Report\n\n${ctx.verificationContent}`);
+  }
+  if (ctx.uatContent) {
+    optionalSections.push(`## UAT Report\n\n${ctx.uatContent}`);
+  }
+
+  const missingNote = ctx.missingArtifacts.length > 0
+    ? `\nNote: The following optional artefacts were not available: ${ctx.missingArtifacts.join(", ")}\n`
+    : "";
+
+  return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+
+**Project:** ${ctx.projectName}
+**Output file:** ${ctx.outputPath}
+
+## Your Task
+
+Analyse the artefacts below and extract structured knowledge from milestone **${ctx.milestoneId}**.
+
+Write a LEARNINGS document to \`${ctx.outputPath}\` with the following 4 sections:
+
+### Decisions
+Key architectural and design decisions made during this milestone, including the rationale and alternatives considered.
+
+### Lessons
+What the team learned — technical discoveries, process insights, and knowledge gaps that were filled.
+
+### Patterns
+Reusable patterns, approaches, or solutions that emerged and should be applied in future work.
+
+### Surprises
+Unexpected challenges, discoveries, or outcomes — things that deviated from assumptions.
+
+### Source Attribution (REQUIRED)
+
+Every extracted item MUST include a \`Source:\` line immediately after the item text.
+Format: \`Source: {artifact-filename}/{section}\`
+Example: \`Source: M001-PLAN.md/Architecture Decisions\`
+
+Items without a Source attribution are invalid and must not be included in the output.
+
+---
+
+## Artefacts
+
+### Plan
+
+${ctx.planContent}
+
+---
+
+### Summary
+
+${ctx.summaryContent}
+
+${optionalSections.join("\n\n---\n\n")}
+${missingNote}
+---
+
+## Output Format
+
+Write the LEARNINGS file to \`${ctx.relativeOutputPath}\` with YAML frontmatter followed by the 4 sections above.
+Each section should contain concise, actionable bullet points.
+Every bullet point MUST be followed by a source line, for example:
+
+\`\`\`
+### Decisions
+- Chose PostgreSQL over SQLite for concurrent write support.
+  Source: M001-PLAN.md/Architecture Decisions
+\`\`\`
+
+Items without a \`Source:\` line are invalid.
+
+---
+
+## Optional: Capture Individual Learnings
+
+If the \`capture_thought\` tool is available, call it once for each extracted item with:
+- category: "decision" | "lesson" | "pattern" | "surprise"
+- phase: "${ctx.milestoneId}"
+- content: {the learning text}
+- source: {artifact filename}
+
+If \`capture_thought\` is not available, skip this step silently — do not report an error.
+
+---
+
+## Rebuild Knowledge Graph
+
+After writing LEARNINGS.md, call the \`gsd_graph\` tool with \`{ "mode": "build" }\` to rebuild the knowledge graph so the new learnings are immediately queryable by future milestone prompts.
+
+If the \`gsd_graph\` tool is not available, skip this step silently.
+`;
+}
+
+export function buildFrontmatter(ctx: FrontmatterContext): string {
+  const missingList = ctx.missingArtifacts.length > 0
+    ? ctx.missingArtifacts.map((a) => `  - ${a}`).join("\n")
+    : "  []";
+
+  const missingValue = ctx.missingArtifacts.length > 0
+    ? `\n${missingList}`
+    : " []";
+
+  return `---
+phase: ${ctx.milestoneId}
+phase_name: ${ctx.milestoneName}
+project: ${ctx.projectName}
+generated: ${ctx.generatedAt}
+counts:
+  decisions: ${ctx.counts.decisions}
+  lessons: ${ctx.counts.lessons}
+  patterns: ${ctx.counts.patterns}
+  surprises: ${ctx.counts.surprises}
+missing_artifacts:${missingValue}
+---`;
+}
+
+export function extractProjectName(basePath: string): string {
+  const projectMdPath = join(gsdRoot(basePath), "PROJECT.md");
+
+  if (existsSync(projectMdPath)) {
+    try {
+      const content = readFileSync(projectMdPath, "utf-8");
+      const match = content.match(/^name:\s*(.+)$/m);
+      if (match) return match[1].trim();
+    } catch {
+      // non-fatal
+    }
+  }
+
+  return basename(basePath);
+}
+
+// ─── Handler ──────────────────────────────────────────────────────────────────
+
+export async function handleExtractLearnings(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const { milestoneId } = parseExtractLearningsArgs(args);
+
+  if (!milestoneId) {
+    ctx.ui.notify("Usage: /gsd extract-learnings <milestoneId>  (e.g. M001)", "warning");
+    return;
+  }
+
+  // projectRoot() throws GSDNoProjectError if no project found — intentional, handled by dispatcher
+  const basePath = projectRoot();
+  const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+
+  if (!milestoneDir) {
+    ctx.ui.notify(`Milestone not found: ${milestoneId}`, "error");
+    return;
+  }
+
+  const artifacts = resolvePhaseArtifacts(milestoneDir, milestoneId);
+
+  if (artifacts.missingRequired.length > 0) {
+    ctx.ui.notify(
+      `Cannot extract learnings — required artefacts missing: ${artifacts.missingRequired.join(", ")}`,
+      "error",
+    );
+    return;
+  }
+
+  // Read required artefacts
+  const planContent = readFileSync(artifacts.plan!, "utf-8");
+  const summaryContent = readFileSync(artifacts.summary!, "utf-8");
+
+  // Read optional artefacts
+  const verificationContent = artifacts.verification
+    ? readFileSync(artifacts.verification, "utf-8")
+    : null;
+  const uatContent = artifacts.uat
+    ? readFileSync(artifacts.uat, "utf-8")
+    : null;
+
+  // Determine missing optional artefacts for context
+  const missingArtifacts: string[] = [];
+  if (!artifacts.verification) missingArtifacts.push(`${milestoneId}-VERIFICATION.md`);
+  if (!artifacts.uat) missingArtifacts.push(`${milestoneId}-UAT.md`);
+
+  // Extract milestone name from Plan H1 or fall back to milestoneId
+  const h1Match = planContent.match(/^#\s+(.+)$/m);
+  const milestoneName = h1Match?.[1]?.trim() ?? milestoneId;
+
+  const projectName = extractProjectName(basePath);
+  const outputPath = buildLearningsOutputPath(milestoneDir, milestoneId);
+  const relativeOutputPath = outputPath.replace(basePath + "/", "");
+
+  const prompt = buildExtractLearningsPrompt({
+    milestoneId,
+    milestoneName,
+    outputPath,
+    relativeOutputPath,
+    planContent,
+    summaryContent,
+    verificationContent,
+    uatContent,
+    missingArtifacts,
+    projectName,
+  });
+
+  ctx.ui.notify(`Extracting learnings for ${milestoneId}: "${milestoneName}"...`, "info");
+
+  pi.sendMessage(
+    { customType: "gsd-extract-learnings", content: prompt, display: false },
+    { triggerTurn: true },
+  );
+}

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -822,7 +822,7 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "budget_ceiling", "budget_enforcement", "context_pause_threshold",
     "notifications", "cmux", "remote_questions", "git",
     "post_unit_hooks", "pre_dispatch_hooks",
-    "dynamic_routing", "token_profile", "phases", "parallel",
+    "dynamic_routing", "uok", "token_profile", "phases", "parallel",
     "auto_visualize", "auto_report",
     "verification_commands", "verification_auto_fix", "verification_max_retries",
     "search_provider", "context_selection",

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -153,7 +153,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `context_pause_threshold`: number (0-100) — context window usage percentage at which auto-mode should pause to suggest checkpointing. Set to `0` to disable. Default: `0` (disabled).
 
-- `token_profile`: `"budget"`, `"balanced"`, or `"quality"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models. See token-optimization docs.
+- `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
@@ -191,6 +191,19 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `hooks`: boolean — enable routing hooks. Default: `true`.
   - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
 
+- `uok`: Unified Orchestration Kernel controls. Keys:
+  - `enabled`: boolean — enable kernel wrappers and contract observers. Default: `true`.
+  - `legacy_fallback.enabled`: boolean — emergency release fallback that forces legacy orchestration behavior even when `uok.enabled` is `true`. Default: `false`.
+    - Runtime override: set `GSD_UOK_FORCE_LEGACY=1` (or `GSD_UOK_LEGACY_FALLBACK=1`) to force legacy behavior for the current process.
+  - `gates.enabled`: boolean — route checks through the unified gate runner and persist `gate_runs`.
+  - `model_policy.enabled`: boolean — enforce policy filtering before model capability scoring.
+  - `execution_graph.enabled`: boolean — enable DAG scheduler facade/adapters for execution.
+  - `gitops.enabled`: boolean — persist turn-level git transaction records.
+  - `gitops.turn_action`: `"commit"` | `"snapshot"` | `"status-only"` — turn transaction mode.
+  - `gitops.turn_push`: boolean — whether turn transactions should include push intent metadata.
+  - `audit_unified.enabled`: boolean — dual-write unified audit envelope events.
+  - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow.
+
 - `context_management`: configures context hygiene for auto-mode sessions. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.

package/src/resources/extensions/gsd/ecosystem/gsd-extension-api.ts

@@ -0,0 +1,228 @@
+// GSD2 — Ecosystem Extension API wrapper
+// Wraps pi's ExtensionAPI to expose typed GSD context (phase + active unit)
+// to extensions loaded from `./.gsd/extensions/`. The wrapper intercepts only
+// `on("before_agent_start", ...)` so GSD can dispatch ecosystem handlers AFTER
+// refreshing state — fixing the load-order race where third-party
+// `.pi/extensions/` handlers see a stale module-level snapshot (#3338).
+//
+// SINGLE-SESSION INVARIANT: the module-level `_snapshot` is per-process.
+// Worktree or project switches do NOT reload extensions, matching pi's
+// `.pi/extensions/` behavior. Only re-launching the CLI rebinds the snapshot.
+
+import type {
+  BeforeAgentStartEvent,
+  ExtensionAPI,
+  ExtensionHandler,
+} from "@gsd/pi-coding-agent";
+
+// Structural mirror of pi's internal BeforeAgentStartEventResult. The internal
+// type is not re-exported from the package root, and constraint #3 forbids
+// changes to packages/pi-coding-agent/, so we mirror the public shape here.
+// `any` on inner fields keeps assignability bidirectional with pi's stricter
+// `Pick<CustomMessage, ...>` shape (CustomMessage is also not re-exported).
+// Source of truth: packages/pi-coding-agent/src/core/extensions/types.ts
+export interface BeforeAgentStartEventResult {
+  message?: {
+    customType: string;
+    content?: any;
+    display?: any;
+    details?: any;
+  };
+  systemPrompt?: string;
+}
+
+import type { GSDActiveUnit, GSDState, Phase } from "../types.js";
+import { isGSDActive, getCurrentPhase } from "../../shared/gsd-phase-state.js";
+import { logWarning } from "../workflow-logger.js";
+
+// ─── Public Interface ───────────────────────────────────────────────────
+
+export interface GSDExtensionAPI extends ExtensionAPI {
+  /** Current GSD workflow phase, or null if no project state. */
+  getPhase(): Phase | null;
+  /** Currently active milestone/slice/task triple, or null if none. */
+  getActiveUnit(): GSDActiveUnit | null;
+}
+
+export type GSDEcosystemBeforeAgentStartHandler = ExtensionHandler<
+  BeforeAgentStartEvent,
+  BeforeAgentStartEventResult
+>;
+
+// ─── Auto-loop phase mapping ────────────────────────────────────────────
+
+const AUTO_LOOP_PHASE_MAP: Record<string, Phase> = {
+  "plan-milestone": "planning",
+  "plan-slice": "planning",
+  "research": "researching",
+  "discuss": "discussing",
+  "execute-task": "executing",
+  "verify": "verifying",
+  "summarize-task": "summarizing",
+  "summarize-slice": "summarizing",
+  "advance": "advancing",
+  "validate-milestone": "validating-milestone",
+  "complete-milestone": "completing-milestone",
+  "replan-slice": "replanning-slice",
+};
+
+/** Exposed for unit tests. Returns null for unknown keys (does NOT default). */
+export function mapAutoLoopPhase(raw: string): Phase | null {
+  return AUTO_LOOP_PHASE_MAP[raw] ?? null;
+}
+
+function resolvePhase(state: GSDState | null): Phase | null {
+  if (!state) return null;
+  if (isGSDActive()) {
+    const raw = getCurrentPhase();
+    if (raw != null) {
+      const mapped = AUTO_LOOP_PHASE_MAP[raw];
+      if (mapped) return mapped;
+      logWarning("ecosystem", `unknown auto-loop phase: ${raw}`);
+      // FALL THROUGH to state.phase rather than defaulting to "executing".
+    }
+  }
+  return state.phase;
+}
+
+function resolveActiveUnit(state: GSDState | null): GSDActiveUnit | null {
+  if (!state) return null;
+  const m = state.activeMilestone;
+  const s = state.activeSlice;
+  const t = state.activeTask;
+  if (!m || !s || !t) return null;
+  return {
+    milestoneId: m.id,
+    milestoneTitle: m.title,
+    sliceId: s.id,
+    sliceTitle: s.title,
+    taskId: t.id,
+    taskTitle: t.title,
+  };
+}
+
+// ─── Module-level snapshot ──────────────────────────────────────────────
+
+interface Snapshot {
+  phase: Phase | null;
+  activeUnit: GSDActiveUnit | null;
+}
+
+let _snapshot: Snapshot = { phase: null, activeUnit: null };
+
+/** Refresh the snapshot from a freshly derived GSDState (or null on failure). */
+export function updateSnapshot(state: GSDState | null): void {
+  _snapshot = {
+    phase: resolvePhase(state),
+    activeUnit: resolveActiveUnit(state),
+  };
+}
+
+export function getSnapshotPhase(): Phase | null {
+  return _snapshot.phase;
+}
+
+export function getSnapshotActiveUnit(): GSDActiveUnit | null {
+  return _snapshot.activeUnit;
+}
+
+/** Test-only: reset the snapshot to its initial empty state. */
+export function _resetSnapshot(): void {
+  _snapshot = { phase: null, activeUnit: null };
+}
+
+// ─── Wrapper factory ────────────────────────────────────────────────────
+
+/**
+ * Build a GSDExtensionAPI by manually delegating every ExtensionAPI method
+ * to the underlying pi instance, except `on("before_agent_start", ...)`
+ * which is captured into `sharedHandlers` for GSD-owned dispatch.
+ *
+ * Uses `satisfies GSDExtensionAPI` (NOT `as`) so TypeScript catches drift
+ * when pi adds new ExtensionAPI methods.
+ */
+export function createGSDExtensionAPI(
+  pi: ExtensionAPI,
+  sharedHandlers: GSDEcosystemBeforeAgentStartHandler[],
+): GSDExtensionAPI {
+  const wrapper = {
+    // ── Event subscription (single intercept point) ────────────────────
+    on(event: any, handler: any): void {
+      if (event === "before_agent_start") {
+        sharedHandlers.push(handler as GSDEcosystemBeforeAgentStartHandler);
+        return;
+      }
+      (pi.on as (e: any, h: any) => void)(event, handler);
+    },
+
+    // ── Event emission ─────────────────────────────────────────────────
+    emitBeforeModelSelect: (...args: Parameters<ExtensionAPI["emitBeforeModelSelect"]>) =>
+      pi.emitBeforeModelSelect(...args),
+    emitAdjustToolSet: (...args: Parameters<ExtensionAPI["emitAdjustToolSet"]>) =>
+      pi.emitAdjustToolSet(...args),
+
+    // ── Tool / command / shortcut / flag registration ──────────────────
+    registerTool: ((tool: any) => pi.registerTool(tool)) as ExtensionAPI["registerTool"],
+    registerCommand: (...args: Parameters<ExtensionAPI["registerCommand"]>) =>
+      pi.registerCommand(...args),
+    registerBeforeInstall: (...args: Parameters<ExtensionAPI["registerBeforeInstall"]>) =>
+      pi.registerBeforeInstall(...args),
+    registerAfterInstall: (...args: Parameters<ExtensionAPI["registerAfterInstall"]>) =>
+      pi.registerAfterInstall(...args),
+    registerBeforeRemove: (...args: Parameters<ExtensionAPI["registerBeforeRemove"]>) =>
+      pi.registerBeforeRemove(...args),
+    registerAfterRemove: (...args: Parameters<ExtensionAPI["registerAfterRemove"]>) =>
+      pi.registerAfterRemove(...args),
+    registerShortcut: (...args: Parameters<ExtensionAPI["registerShortcut"]>) =>
+      pi.registerShortcut(...args),
+    registerFlag: (...args: Parameters<ExtensionAPI["registerFlag"]>) =>
+      pi.registerFlag(...args),
+    getFlag: (...args: Parameters<ExtensionAPI["getFlag"]>) => pi.getFlag(...args),
+
+    // ── Message rendering ──────────────────────────────────────────────
+    registerMessageRenderer: ((customType: string, renderer: any) =>
+      pi.registerMessageRenderer(customType, renderer)) as ExtensionAPI["registerMessageRenderer"],
+
+    // ── Actions ────────────────────────────────────────────────────────
+    sendMessage: ((message: any, options?: any) =>
+      pi.sendMessage(message, options)) as ExtensionAPI["sendMessage"],
+    sendUserMessage: (...args: Parameters<ExtensionAPI["sendUserMessage"]>) =>
+      pi.sendUserMessage(...args),
+    retryLastTurn: () => pi.retryLastTurn(),
+    appendEntry: ((customType: string, data?: any) =>
+      pi.appendEntry(customType, data)) as ExtensionAPI["appendEntry"],
+
+    // ── Session metadata ───────────────────────────────────────────────
+    setSessionName: (...args: Parameters<ExtensionAPI["setSessionName"]>) =>
+      pi.setSessionName(...args),
+    getSessionName: () => pi.getSessionName(),
+    setLabel: (...args: Parameters<ExtensionAPI["setLabel"]>) => pi.setLabel(...args),
+    exec: (...args: Parameters<ExtensionAPI["exec"]>) => pi.exec(...args),
+    getActiveTools: () => pi.getActiveTools(),
+    getAllTools: () => pi.getAllTools(),
+    setActiveTools: (...args: Parameters<ExtensionAPI["setActiveTools"]>) =>
+      pi.setActiveTools(...args),
+    getCommands: () => pi.getCommands(),
+
+    // ── Model & thinking ───────────────────────────────────────────────
+    setModel: (...args: Parameters<ExtensionAPI["setModel"]>) => pi.setModel(...args),
+    getThinkingLevel: () => pi.getThinkingLevel(),
+    setThinkingLevel: (...args: Parameters<ExtensionAPI["setThinkingLevel"]>) =>
+      pi.setThinkingLevel(...args),
+
+    // ── Provider registration ──────────────────────────────────────────
+    registerProvider: (...args: Parameters<ExtensionAPI["registerProvider"]>) =>
+      pi.registerProvider(...args),
+    unregisterProvider: (...args: Parameters<ExtensionAPI["unregisterProvider"]>) =>
+      pi.unregisterProvider(...args),
+
+    // ── Shared event bus (passthrough property) ────────────────────────
+    events: pi.events,
+
+    // ── GSD-specific additions ─────────────────────────────────────────
+    getPhase: (): Phase | null => _snapshot.phase,
+    getActiveUnit: (): GSDActiveUnit | null => _snapshot.activeUnit,
+  } satisfies GSDExtensionAPI;
+
+  return wrapper;
+}