gsd-pi 2.10.12 → 2.12.0

package/dist/resources/extensions/gsd/templates/slice-summary.md

@@ -0,0 +1,99 @@
+---
+id: {{sliceId}}
+parent: {{milestoneId}}
+milestone: {{milestoneId}}
+provides:
+  - {{whatThisSliceProvides}}
+requires:
+  - slice: {{depSliceId}}
+    provides: {{whatWasConsumed}}
+affects:
+  - {{downstreamSliceId}}
+key_files:
+  - {{filePath}}
+key_decisions:
+  - {{decision}}
+patterns_established:
+  - {{pattern}}
+observability_surfaces:
+  - {{status endpoint, structured log, persisted failure state, diagnostic command, or none}}
+drill_down_paths:
+  - {{pathToTaskSummary}}
+duration: {{duration}}
+verification_result: passed
+completed_at: {{date}}
+---
+
+# {{sliceId}}: {{sliceTitle}}
+
+<!-- One-liner must say what actually shipped, not just that work completed.
+     Good: "Structured job status endpoint with persisted failure diagnostics"
+     Bad: "Status feature implemented" -->
+
+**{{oneLiner}}**
+
+## What Happened
+
+{{narrative — compress task summaries into a coherent story}}
+
+## Verification
+
+{{whatWasVerifiedAcrossAllTasks — tests, builds, manual checks}}
+
+<!-- If the project has no REQUIREMENTS.md, omit all four requirement sections below entirely — do not fill them with "none". These sections only apply when requirements are being actively tracked. -->
+## Requirements Advanced
+
+- {{requirementId}} — {{howThisSliceAdvancedIt}}
+
+## Requirements Validated
+
+- {{requirementId}} — {{whatProofNowMakesItValidated}}
+
+## New Requirements Surfaced
+
+- {{newRequirementOr_none}}
+
+## Requirements Invalidated or Re-scoped
+
+- {{requirementIdOr_none}} — {{what changed}}
+
+## Deviations
+
+<!-- Deviations are unplanned changes to the written plan, not ordinary debugging inside the plan's intended scope. -->
+
+{{deviationsFromPlan_OR_none}}
+
+## Known Limitations
+
+<!-- Known limitations are real gaps, rough edges, or deferred constraints that still exist after this slice shipped. -->
+
+{{whatDoesntWorkYet_OR_whatWasDeferredToLaterSlices}}
+
+## Follow-ups
+
+<!-- Follow-ups are concrete next actions discovered during execution, not a restatement of known limitations. -->
+
+{{workDeferredOrDiscoveredDuringExecution_OR_none}}
+
+## Files Created/Modified
+
+- `{{filePath}}` — {{description}}
+- `{{filePath}}` — {{description}}
+
+## Forward Intelligence
+
+<!-- Write what you wish you'd known at the start of this slice.
+     This section is read by the next slice's planning and research steps.
+     Be specific and concrete — this is the most valuable context you can transfer. -->
+
+### What the next slice should know
+- {{insightThatWouldHelpDownstreamWork}}
+
+### What's fragile
+- {{fragileAreaOrThinImplementation}} — {{whyItMatters}}
+
+### Authoritative diagnostics
+- {{whereAFutureAgentShouldLookFirst}} — {{whyThisSignalIsTrustworthy}}
+
+### What assumptions changed
+- {{originalAssumption}} — {{whatActuallyHappened}}

package/dist/resources/extensions/gsd/templates/state.md

@@ -0,0 +1,19 @@
+# GSD State
+
+**Active Milestone:** {{milestoneId}}: {{milestoneTitle}}
+**Active Slice:** {{sliceId}}: {{sliceTitle}}
+**Active Task:** {{taskId}}: {{taskTitle}}
+**Phase:** {{phase}}
+**Slice Branch:** {{activeBranch}}
+**Active Workspace:** {{activeWorkspace}}
+**Next Action:** {{nextAction}}
+**Last Updated:** {{date}}
+**Requirements Status:** {{activeCount}} active · {{validatedCount}} validated · {{deferredCount}} deferred · {{outOfScopeCount}} out of scope
+
+## Recent Decisions
+
+- {{decision}}
+
+## Blockers
+
+- (none)

package/dist/resources/extensions/gsd/templates/task-plan.md

@@ -0,0 +1,52 @@
+---
+# Optional scope estimate — helps the plan quality validator detect over-scoped tasks.
+# Tasks with 10+ estimated steps or 12+ estimated files trigger a warning to consider splitting.
+estimated_steps: {{estimatedSteps}}
+estimated_files: {{estimatedFiles}}
+---
+
+# {{taskId}}: {{taskTitle}}
+
+**Slice:** {{sliceId}} — {{sliceTitle}}
+**Milestone:** {{milestoneId}}
+
+## Description
+
+{{description}}
+
+## Steps
+
+1. {{step}}
+2. {{step}}
+3. {{step}}
+
+## Must-Haves
+
+- [ ] {{mustHave}}
+- [ ] {{mustHave}}
+
+## Verification
+
+- {{howToVerifyThisTaskIsActuallyDone}}
+- {{commandToRun_OR_behaviorToCheck}}
+
+## Observability Impact
+
+<!-- OMIT THIS SECTION ENTIRELY for simple tasks that don't touch runtime boundaries,
+     async flows, APIs, background processes, or error paths.
+     Include it only when the task meaningfully changes how failures are detected or diagnosed. -->
+
+- Signals added/changed: {{structured logs, statuses, errors, metrics}}
+- How a future agent inspects this: {{command, endpoint, file, UI state}}
+- Failure state exposed: {{what becomes visible on failure}}
+
+## Inputs
+
+- `{{filePath}}` — {{whatThisTaskNeedsFromPriorWork}}
+- {{priorTaskSummaryInsight}}
+
+## Expected Output
+
+<!-- This task should produce a real increment toward making the slice goal/demo true. A full slice plan should not be able to mark every task complete while the claimed slice behavior still does not work at the stated proof level. -->
+
+- `{{filePath}}` — {{whatThisTaskShouldProduceOrModify}}

package/dist/resources/extensions/gsd/templates/task-summary.md

@@ -0,0 +1,57 @@
+---
+id: {{taskId}}
+parent: {{sliceId}}
+milestone: {{milestoneId}}
+provides:
+  - {{whatThisTaskProvides}}
+key_files:
+  - {{filePath}}
+key_decisions:
+  - {{decision}}
+patterns_established:
+  - {{pattern}}
+observability_surfaces:
+  - {{status endpoint, structured log, persisted failure state, diagnostic command, or none}}
+duration: {{duration}}
+verification_result: passed
+completed_at: {{date}}
+# Set blocker_discovered: true only if execution revealed the remaining slice plan
+# is fundamentally invalid (wrong API, missing capability, architectural mismatch).
+# Do NOT set true for ordinary bugs, minor deviations, or fixable issues.
+blocker_discovered: false
+---
+
+# {{taskId}}: {{taskTitle}}
+
+<!-- One-liner must say what actually shipped, not just that work completed.
+     Good: "Added retry-aware worker status logging"
+     Bad: "Implemented logging improvements" -->
+
+**{{oneLiner}}**
+
+## What Happened
+
+{{narrative}}
+
+## Verification
+
+{{whatWasVerifiedAndHow — commands run, tests passed, behavior confirmed}}
+
+## Diagnostics
+
+{{howToInspectWhatThisTaskBuiltLater — status surfaces, logs, error shapes, failure artifacts, or none}}
+
+## Deviations
+
+<!-- Deviations are unplanned changes to the written task plan, not ordinary debugging during implementation. -->
+
+{{deviationsFromPlan_OR_none}}
+
+## Known Issues
+
+{{issuesDiscoveredButNotFixed_OR_none}}
+
+## Files Created/Modified
+
+- `{{filePath}}` — {{description}}
+- `{{filePath}}` — {{description}}

package/dist/resources/extensions/gsd/templates/uat.md

@@ -0,0 +1,54 @@
+# {{sliceId}}: {{sliceTitle}} — UAT
+
+**Milestone:** {{milestoneId}}
+**Written:** {{date}}
+
+## UAT Type
+
+- UAT mode: {{artifact-driven | live-runtime | human-experience | mixed}}
+- Why this mode is sufficient: {{reason}}
+
+## Preconditions
+
+{{whatMustBeTrueBeforeTesting — server running, data seeded, etc.}}
+
+## Smoke Test
+
+{{oneQuickCheckThatConfirmsTheSliceBasicallyWorks}}
+
+## Test Cases
+
+### 1. {{testName}}
+
+1. {{step}}
+2. {{step}}
+3. **Expected:** {{expected}}
+
+### 2. {{testName}}
+
+1. {{step}}
+2. **Expected:** {{expected}}
+
+## Edge Cases
+
+### {{edgeCaseName}}
+
+1. {{step}}
+2. **Expected:** {{expected}}
+
+## Failure Signals
+
+- {{whatWouldIndicateSomethingIsBroken — errors, missing UI, wrong data}}
+
+## Requirements Proved By This UAT
+
+- {{requirementIdOr_none}} — {{what this UAT proves}}
+
+## Not Proven By This UAT
+
+- {{what this UAT intentionally does not prove}}
+- {{remaining live/runtime/operational gaps, if any}}
+
+## Notes for Tester
+
+{{anythingTheHumanShouldKnow — known rough edges, things to ignore, areas needing gut check}}

package/dist/resources/extensions/gsd/tests/activity-log-prune.test.ts

@@ -0,0 +1,297 @@
+// Tests for pruneActivityLogs — age-based activity log pruning with
+// highest-seq preservation invariant — plus step-11 prompt text assertion.
+//
+// Sections:
+//   (a) Basic pruning: one old file deleted, two recent survive
+//   (b) Highest-seq preserved even when all files are old
+//   (c) retentionDays=0 boundary: all non-highest-seq deleted
+//   (d) No-op when all files are recent
+//   (e) Empty directory: no crash
+//   (f) All old files: only highest-seq survives
+//   (g) Single file: always preserved (it IS highest-seq)
+//   (h) Seq number is tie-breaker (010 beats 001 lexicographically and numerically)
+//   (i) Non-matching filenames ignored: notes.txt survives, no crash
+//   (j) Step-11 prompt text: "refresh current state if needed"
+
+import { mkdtempSync, mkdirSync, readdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { pruneActivityLogs } from '../activity-log.ts';
+import { createTestContext } from './test-helpers.ts';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+
+const { assertEq, assertTrue, report } = createTestContext();
+// ─── Fixture helpers ───────────────────────────────────────────────────────
+
+let tmpDirs: string[] = [];
+
+function createTmpActivityDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'gsd-prune-test-'));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+function writeActivityFile(activityDir: string, seq: string, name: string): string {
+  mkdirSync(activityDir, { recursive: true });
+  const filePath = join(activityDir, `${seq}-${name}.jsonl`);
+  writeFileSync(filePath, `{"seq":${parseInt(seq, 10)},"name":"${name}"}\n`, 'utf-8');
+  return filePath;
+}
+
+/** Set mtime to daysAgo days in the past. */
+function backdateFile(filePath: string, daysAgo: number): void {
+  const pastMs = Date.now() - daysAgo * 24 * 60 * 60 * 1000;
+  const pastDate = new Date(pastMs);
+  utimesSync(filePath, pastDate, pastDate);
+}
+
+function cleanup(): void {
+  for (const dir of tmpDirs) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  tmpDirs = [];
+}
+
+process.on('exit', cleanup);
+
+// ─── Helper: get sorted filenames (basenames only) in a directory ──────────
+
+function listFiles(dir: string): string[] {
+  return readdirSync(dir).sort();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main(): Promise<void> {
+
+  // ─── (a) Basic pruning ────────────────────────────────────────────────────
+  console.log('\n── (a) Basic pruning: one old file deleted, two recent survive');
+
+  {
+    const dir = createTmpActivityDir();
+    const f001 = writeActivityFile(dir, '001', 'execute-task-M001-S01-T01');
+    const _f002 = writeActivityFile(dir, '002', 'execute-task-M001-S01-T02');
+    const _f003 = writeActivityFile(dir, '003', 'execute-task-M001-S01-T03');
+
+    backdateFile(f001, 40); // older than 30-day retention
+
+    pruneActivityLogs(dir, 30);
+
+    const remaining = listFiles(dir);
+    assertTrue(
+      !remaining.includes('001-execute-task-M001-S01-T01.jsonl'),
+      '(a) file 001 deleted (40 days old, past 30-day threshold)',
+    );
+    assertTrue(
+      remaining.includes('002-execute-task-M001-S01-T02.jsonl'),
+      '(a) file 002 survives (recent)',
+    );
+    assertTrue(
+      remaining.includes('003-execute-task-M001-S01-T03.jsonl'),
+      '(a) file 003 survives (recent, also highest-seq)',
+    );
+  }
+
+  // ─── (b) Highest-seq preserved even when all files are old ───────────────
+  console.log('\n── (b) Highest-seq preserved even when all files are old');
+
+  {
+    const dir = createTmpActivityDir();
+    const f001 = writeActivityFile(dir, '001', 'execute-task-M001-S01-T01');
+    const f002 = writeActivityFile(dir, '002', 'execute-task-M001-S01-T02');
+    const f003 = writeActivityFile(dir, '003', 'execute-task-M001-S01-T03');
+
+    backdateFile(f001, 40);
+    backdateFile(f002, 40);
+    backdateFile(f003, 40); // all old, but 003 is highest-seq
+
+    pruneActivityLogs(dir, 30);
+
+    const remaining = listFiles(dir);
+    assertEq(remaining.length, 1, '(b) exactly 1 file survives when all are old');
+    assertTrue(
+      remaining.includes('003-execute-task-M001-S01-T03.jsonl'),
+      '(b) highest-seq file (003) is the survivor',
+    );
+  }
+
+  // ─── (c) retentionDays=0 boundary ────────────────────────────────────────
+  console.log('\n── (c) retentionDays=0: all non-highest-seq deleted even if brand-new');
+
+  {
+    const dir = createTmpActivityDir();
+    // All files have mtime=now (freshly written — no backdating)
+    writeActivityFile(dir, '001', 'execute-task-M002-S01-T01');
+    writeActivityFile(dir, '002', 'execute-task-M002-S01-T02');
+    writeActivityFile(dir, '003', 'execute-task-M002-S01-T03');
+
+    pruneActivityLogs(dir, 0); // cutoff = now → everything is "expired"
+
+    const remaining = listFiles(dir);
+    assertEq(remaining.length, 1, '(c) retentionDays=0: exactly 1 file survives');
+    assertTrue(
+      remaining.includes('003-execute-task-M002-S01-T03.jsonl'),
+      '(c) retentionDays=0: only highest-seq (003) survives',
+    );
+  }
+
+  // ─── (d) No-op when all files are recent ─────────────────────────────────
+  console.log('\n── (d) No-op when all files are recent');
+
+  {
+    const dir = createTmpActivityDir();
+    writeActivityFile(dir, '001', 'execute-task-M003-S01-T01');
+    writeActivityFile(dir, '002', 'execute-task-M003-S01-T02');
+    writeActivityFile(dir, '003', 'execute-task-M003-S01-T03');
+    // No backdating — all files are fresh
+
+    pruneActivityLogs(dir, 30);
+
+    const remaining = listFiles(dir);
+    assertEq(remaining.length, 3, '(d) all 3 files survive when all are recent');
+  }
+
+  // ─── (e) Empty directory: no crash ────────────────────────────────────────
+  console.log('\n── (e) Empty directory: no crash');
+
+  {
+    const dir = createTmpActivityDir();
+    // dir exists but is empty
+
+    let threw = false;
+    try {
+      pruneActivityLogs(dir, 30);
+    } catch {
+      threw = true;
+    }
+
+    assertTrue(!threw, '(e) pruneActivityLogs does not throw on empty directory');
+    assertTrue(
+      readdirSync(dir).length === 0,
+      '(e) directory still exists and is still empty after no-op',
+    );
+  }
+
+  // ─── (f) All old files: only highest-seq survives ─────────────────────────
+  console.log('\n── (f) All old files: only highest-seq survives');
+
+  {
+    const dir = createTmpActivityDir();
+    const f004 = writeActivityFile(dir, '004', 'execute-task-M004-S01-T01');
+    const f005 = writeActivityFile(dir, '005', 'execute-task-M004-S01-T02');
+    const f006 = writeActivityFile(dir, '006', 'execute-task-M004-S01-T03');
+
+    backdateFile(f004, 60);
+    backdateFile(f005, 60);
+    backdateFile(f006, 60);
+
+    pruneActivityLogs(dir, 30);
+
+    const remaining = listFiles(dir);
+    assertEq(remaining.length, 1, '(f) exactly 1 file survives when all are old');
+    assertTrue(
+      remaining[0].startsWith('006-'),
+      '(f) the surviving file starts with 006 (highest-seq)',
+    );
+  }
+
+  // ─── (g) Single file: always preserved ────────────────────────────────────
+  console.log('\n── (g) Single file: always preserved (it IS highest-seq)');
+
+  {
+    const dir = createTmpActivityDir();
+    const f001 = writeActivityFile(dir, '001', 'execute-task-M005-S01-T01');
+    backdateFile(f001, 100); // very old
+
+    pruneActivityLogs(dir, 30);
+
+    const remaining = listFiles(dir);
+    assertEq(remaining.length, 1, '(g) single file survives even when very old (it is the highest-seq)');
+    assertTrue(
+      remaining.includes('001-execute-task-M005-S01-T01.jsonl'),
+      '(g) the single file (001) is preserved',
+    );
+  }
+
+  // ─── (h) Seq tie-breaker: 010 is higher than 001 ─────────────────────────
+  console.log('\n── (h) Seq number tie-breaker: 010 beats 001 numerically');
+
+  {
+    const dir = createTmpActivityDir();
+    const f001 = writeActivityFile(dir, '001', 'execute-task-M006-S01-T01');
+    const f010 = writeActivityFile(dir, '010', 'execute-task-M006-S01-T10');
+
+    backdateFile(f001, 40);
+    backdateFile(f010, 40); // both old; 010 is numerically highest
+
+    pruneActivityLogs(dir, 30);
+
+    const remaining = listFiles(dir);
+    assertEq(remaining.length, 1, '(h) exactly 1 file survives');
+    assertTrue(
+      remaining.includes('010-execute-task-M006-S01-T10.jsonl'),
+      '(h) seq 010 (numeric 10) survives over seq 001 (numeric 1)',
+    );
+  }
+
+  // ─── (i) Non-matching filenames ignored ───────────────────────────────────
+  console.log('\n── (i) Non-matching filenames ignored: notes.txt survives, no crash');
+
+  {
+    const dir = createTmpActivityDir();
+    const f001 = writeActivityFile(dir, '001', 'execute-task-M007-S01-T01');
+    const notesPath = join(dir, 'notes.txt');
+    writeFileSync(notesPath, 'some notes\n', 'utf-8');
+
+    backdateFile(f001, 40); // eligible for pruning
+    // notes.txt never gets a seq prefix → should be ignored by pruner
+
+    let threw = false;
+    try {
+      pruneActivityLogs(dir, 30);
+    } catch {
+      threw = true;
+    }
+
+    assertTrue(!threw, '(i) no crash when non-matching file is present');
+
+    const remaining = listFiles(dir);
+    assertTrue(
+      remaining.includes('notes.txt'),
+      '(i) notes.txt (non-matching filename) survives pruning unchanged',
+    );
+    // 001 is deleted (old, and notes.txt is not counted as seq-bearing so 001 is not "highest")
+    // But wait — 001 IS the only seq file, making it highest-seq → it survives
+    assertTrue(
+      remaining.includes('001-execute-task-M007-S01-T01.jsonl'),
+      '(i) seq 001 survives (it is the highest-seq among seq files)',
+    );
+  }
+
+  // ─── (j) Step-11 prompt text assertion ────────────────────────────────────
+  console.log('\n── (j) Step-11 prompt text: "refresh current state if needed"');
+
+  {
+    const { readFileSync } = await import('node:fs');
+    const promptPath = join(__dirname, '..', 'prompts', 'complete-slice.md');
+    const content = readFileSync(promptPath, 'utf-8');
+
+    assertTrue(
+      content.includes('refresh current state if needed'),
+      '(j) complete-slice.md step 11 contains "refresh current state if needed"',
+    );
+  }
+
+  report();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});