@kata-sh/cli 0.1.0 → 0.1.1

package/src/resources/extensions/kata/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/src/resources/extensions/kata/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/src/resources/extensions/kata/tests/activity-log-prune.test.ts

@@ -0,0 +1,327 @@
+// 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';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── Assertion helpers ─────────────────────────────────────────────────────
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${message}`);
+  }
+}
+
+function assertEq<T>(actual: T, expected: T, message: string): void {
+  if (JSON.stringify(actual) === JSON.stringify(expected)) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${message} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+// ─── Fixture helpers ───────────────────────────────────────────────────────
+
+let tmpDirs: string[] = [];
+
+function createTmpActivityDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'kata-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);
+    assert(
+      !remaining.includes('001-execute-task-M001-S01-T01.jsonl'),
+      '(a) file 001 deleted (40 days old, past 30-day threshold)',
+    );
+    assert(
+      remaining.includes('002-execute-task-M001-S01-T02.jsonl'),
+      '(a) file 002 survives (recent)',
+    );
+    assert(
+      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');
+    assert(
+      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');
+    assert(
+      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;
+    }
+
+    assert(!threw, '(e) pruneActivityLogs does not throw on empty directory');
+    assert(
+      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');
+    assert(
+      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)');
+    assert(
+      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');
+    assert(
+      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;
+    }
+
+    assert(!threw, '(i) no crash when non-matching file is present');
+
+    const remaining = listFiles(dir);
+    assert(
+      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
+    assert(
+      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');
+
+    assert(
+      content.includes('refresh current state if needed'),
+      '(j) complete-slice.md step 11 contains "refresh current state if needed"',
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Results
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  console.log(`\n${'='.repeat(40)}`);
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  if (failed > 0) {
+    process.exit(1);
+  } else {
+    console.log('All tests passed ✓');
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/resources/extensions/kata/tests/auto-preflight.test.ts

@@ -0,0 +1,97 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  runKataDoctor,
+  selectDoctorScope,
+  filterDoctorIssues,
+} from "../doctor.js";
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${message}`);
+  }
+}
+
+const tmpBase = mkdtempSync(join(tmpdir(), "kata-auto-preflight-test-"));
+const kata = join(tmpBase, ".kata");
+
+mkdirSync(join(kata, "milestones", "M001", "slices", "S01", "tasks"), {
+  recursive: true,
+});
+mkdirSync(join(kata, "milestones", "M009", "slices", "S01", "tasks"), {
+  recursive: true,
+});
+
+writeFileSync(
+  join(kata, "milestones", "M001", "M001-ROADMAP.md"),
+  `# M001: Historical\n\n## Slices\n- [x] **S01: Old Slice** \`risk:low\` \`depends:[]\`\n  > After this: old done\n`,
+);
+writeFileSync(
+  join(kata, "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+  `# S01: Old Slice\n\n**Goal:** Old\n**Demo:** Old\n\n## Must-Haves\n- done\n\n## Tasks\n- [x] **T01: Old Task** \`est:5m\`\n  done\n`,
+);
+writeFileSync(
+  join(kata, "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md"),
+  `---\nid: T01\nparent: S01\nmilestone: M001\nprovides: []\nrequires: []\naffects: []\nkey_files: []\nkey_decisions: []\npatterns_established: []\nobservability_surfaces: []\ndrill_down_paths: []\nduration: 5m\nverification_result: passed\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# T01: Old Task\n\n**Done**\n\n## What Happened\nDone.\n\n## Diagnostics\n- log\n`,
+);
+writeFileSync(
+  join(kata, "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"),
+  `---\nid: S01\nparent: M001\nmilestone: M001\nprovides: []\nrequires: []\naffects: []\nkey_files: []\nkey_decisions: []\npatterns_established: []\nobservability_surfaces: []\ndrill_down_paths: []\nduration: 5m\nverification_result: passed\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# S01: Old Slice\n\n**Done**\n\n## What Happened\nDone.\n\n## Verification\nDone.\n\n## Deviations\nNone\n\n## Known Limitations\nNone\n\n## Follow-ups\nNone\n\n## Files Created/Modified\n- \`x\` — x\n\n## Forward Intelligence\n\n### What the next slice should know\n- x\n\n### What's fragile\n- x\n\n### Authoritative diagnostics\n- x\n\n### What assumptions changed\n- x\n`,
+);
+
+writeFileSync(
+  join(kata, "milestones", "M001", "M001-SUMMARY.md"),
+  `---\nid: M001\nstatus: complete\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# M001: Historical\n\nComplete.\n`,
+);
+
+writeFileSync(
+  join(kata, "milestones", "M009", "M009-ROADMAP.md"),
+  `# M009: Active\n\n## Slices\n- [ ] **S01: Active Slice** \`risk:low\` \`depends:[]\`\n  > After this: active works\n`,
+);
+writeFileSync(
+  join(kata, "milestones", "M009", "slices", "S01", "S01-PLAN.md"),
+  `# S01: Active Slice\n\n**Goal:** Active\n**Demo:** Active\n\n## Must-Haves\n- done\n\n## Tasks\n- [ ] **T01: Active Task** \`est:5m\`\n  todo\n`,
+);
+
+async function main(): Promise<void> {
+  const scope = await selectDoctorScope(tmpBase);
+  assert(
+    scope === "M009/S01",
+    "active scope selected instead of historical milestone",
+  );
+
+  const scopedReport = await runKataDoctor(tmpBase, { fix: false, scope });
+  const scopedBlocking = filterDoctorIssues(scopedReport.issues, {
+    scope,
+    includeWarnings: false,
+  });
+  assert(scopedBlocking.length === 0, "no blocking issues in active scope");
+
+  const historicalReport = await runKataDoctor(tmpBase, { fix: false });
+  const historicalWarnings = historicalReport.issues.filter(
+    (issue) =>
+      issue.unitId.startsWith("M001/S01") && issue.severity === "warning",
+  );
+  assert(
+    historicalWarnings.length > 0,
+    "full repo still contains historical warning drift",
+  );
+
+  rmSync(tmpBase, { recursive: true, force: true });
+
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/resources/extensions/kata/tests/auto-supervisor.test.mjs

@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeUnitRuntimeRecord, readUnitRuntimeRecord } from '../unit-runtime.ts';
+import { resolveAutoSupervisorConfig } from '../preferences.ts';
+
+test('resolveAutoSupervisorConfig provides safe timeout defaults', () => {
+  const supervisor = resolveAutoSupervisorConfig();
+  assert.equal(supervisor.soft_timeout_minutes, 20);
+  assert.equal(supervisor.idle_timeout_minutes, 10);
+  assert.equal(supervisor.hard_timeout_minutes, 30);
+});
+
+test('writeUnitRuntimeRecord persists progress and recovery metadata defaults', () => {
+  const base = mkdtempSync(join(tmpdir(), 'kata-auto-supervisor-'));
+  const startedAt = 1234567890;
+
+  writeUnitRuntimeRecord(base, 'plan-milestone', 'M010', startedAt, {
+    phase: 'dispatched',
+    lastProgressAt: startedAt,
+    progressCount: 1,
+    lastProgressKind: 'dispatch',
+  });
+
+  const runtime = readUnitRuntimeRecord(base, 'plan-milestone', 'M010');
+  assert.ok(runtime);
+  assert.equal(runtime.phase, 'dispatched');
+  assert.equal(runtime.lastProgressAt, startedAt);
+  assert.equal(runtime.progressCount, 1);
+  assert.equal(runtime.lastProgressKind, 'dispatch');
+  assert.equal(runtime.recoveryAttempts, 0);
+});
+
+test('writeUnitRuntimeRecord keeps explicit recovery attempt fields', () => {
+  const base = mkdtempSync(join(tmpdir(), 'kata-auto-supervisor-'));
+  const startedAt = 2234567890;
+
+  writeUnitRuntimeRecord(base, 'research-milestone', 'M011', startedAt, {
+    phase: 'timeout',
+    recoveryAttempts: 2,
+    lastRecoveryReason: 'idle',
+    lastProgressAt: startedAt + 50,
+    progressCount: 3,
+    lastProgressKind: 'recovery-retry',
+  });
+
+  const runtime = JSON.parse(readFileSync(join(base, '.kata/runtime/units/research-milestone-M011.json'), 'utf8'));
+  assert.equal(runtime.recoveryAttempts, 2);
+  assert.equal(runtime.lastRecoveryReason, 'idle');
+  assert.equal(runtime.lastProgressKind, 'recovery-retry');
+});