@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/kata/state.ts

@@ -0,0 +1,509 @@
+// Kata Extension — State Derivation
+// Reads roadmap + plan files to determine current position.
+// Pure TypeScript, zero Pi dependencies.
+
+import type {
+  KataState,
+  ActiveRef,
+  Roadmap,
+  RoadmapSliceEntry,
+  SlicePlan,
+  MilestoneRegistryEntry,
+} from "./types.ts";
+
+import {
+  parseRoadmap,
+  parsePlan,
+  parseSummary,
+  loadFile,
+  parseRequirementCounts,
+  parseContextDependsOn,
+} from "./files.ts";
+
+import {
+  milestonesDir,
+  resolveMilestonePath,
+  resolveMilestoneFile,
+  resolveSlicePath,
+  resolveSliceFile,
+  resolveTaskFile,
+  resolveKataRootFile,
+} from "./paths.ts";
+import { getActiveSliceBranch } from "./worktree.ts";
+
+import { readdirSync } from "fs";
+import { join } from "path";
+
+// ─── Query Functions ───────────────────────────────────────────────────────
+
+/**
+ * Check if all tasks in a slice plan are done.
+ */
+export function isSliceComplete(plan: SlicePlan): boolean {
+  return plan.tasks.length > 0 && plan.tasks.every((t) => t.done);
+}
+
+/**
+ * Check if all slices in a roadmap are done.
+ */
+export function isMilestoneComplete(roadmap: Roadmap): boolean {
+  return roadmap.slices.length > 0 && roadmap.slices.every((s) => s.done);
+}
+
+// ─── State Derivation ──────────────────────────────────────────────────────
+
+/**
+ * Find all milestone directory IDs by scanning .kata/milestones/.
+ * Extracts the ID prefix (e.g. "M001") from directory names like "M001-PAYMENT-INTEGRATIONS".
+ */
+function findMilestoneIds(basePath: string): string[] {
+  const dir = milestonesDir(basePath);
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => {
+        const match = d.name.match(/^(M\d+)/);
+        return match ? match[1] : d.name;
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Returns the ID of the first incomplete milestone, or null if all are complete.
+ */
+export async function getActiveMilestoneId(
+  basePath: string,
+): Promise<string | null> {
+  const milestoneIds = findMilestoneIds(basePath);
+  for (const mid of milestoneIds) {
+    const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+    const content = roadmapFile ? await loadFile(roadmapFile) : null;
+    if (!content) {
+      // No roadmap — but if a summary exists, the milestone is already complete
+      const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (summaryFile) continue; // completed milestone, skip
+      return mid; // No roadmap and no summary — milestone is incomplete
+    }
+    const roadmap = parseRoadmap(content);
+    if (!isMilestoneComplete(roadmap)) return mid;
+  }
+  return null;
+}
+
+/**
+ * Reconstruct Kata state from files on disk.
+ * This is the source of truth — STATE.md is just a cache of this output.
+ */
+export async function deriveState(basePath: string): Promise<KataState> {
+  const milestoneIds = findMilestoneIds(basePath);
+  const requirements = parseRequirementCounts(
+    await loadFile(resolveKataRootFile(basePath, "REQUIREMENTS")),
+  );
+
+  if (milestoneIds.length === 0) {
+    return {
+      activeMilestone: null,
+      activeSlice: null,
+      activeTask: null,
+      phase: "pre-planning",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: "No milestones found. Run /kata to create one.",
+      registry: [],
+      requirements,
+      progress: {
+        milestones: { done: 0, total: 0 },
+      },
+    };
+  }
+
+  // Pre-compute the set of complete milestone IDs for dependency checking.
+  // This allows forward references (M002 depending on M003) to resolve correctly.
+  const completeMilestoneIds = new Set<string>();
+  for (const mid of milestoneIds) {
+    const rf = resolveMilestoneFile(basePath, mid, "ROADMAP");
+    const rc = rf ? await loadFile(rf) : null;
+    if (!rc) {
+      // No roadmap — milestone is complete if it has a summary
+      const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (sf) completeMilestoneIds.add(mid);
+      continue;
+    }
+    const rmap = parseRoadmap(rc);
+    if (!isMilestoneComplete(rmap)) continue;
+    const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
+    if (sf) completeMilestoneIds.add(mid);
+  }
+
+  // Build the registry and locate the active milestone in a single pass.
+  const registry: MilestoneRegistryEntry[] = [];
+  let activeMilestone: ActiveRef | null = null;
+  let activeRoadmap: Roadmap | null = null;
+  let activeMilestoneFound = false;
+
+  for (const mid of milestoneIds) {
+    const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+    const content = roadmapFile ? await loadFile(roadmapFile) : null;
+    if (!content) {
+      // No roadmap — check if a summary exists (completed milestone without roadmap)
+      const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (summaryFile) {
+        const summaryContent = await loadFile(summaryFile);
+        const summaryTitle = summaryContent
+          ? parseSummary(summaryContent).title || mid
+          : mid;
+        registry.push({ id: mid, title: summaryTitle, status: "complete" });
+        completeMilestoneIds.add(mid);
+        continue;
+      }
+      // No roadmap and no summary — treat as incomplete/active
+      if (!activeMilestoneFound) {
+        activeMilestone = { id: mid, title: mid };
+        activeMilestoneFound = true;
+        registry.push({ id: mid, title: mid, status: "active" });
+      } else {
+        registry.push({ id: mid, title: mid, status: "pending" });
+      }
+      continue;
+    }
+
+    const roadmap = parseRoadmap(content);
+    const title = roadmap.title.replace(/^M\d+[^:]*:\s*/, "");
+    const complete = isMilestoneComplete(roadmap);
+
+    if (complete) {
+      // All slices done — check if milestone summary exists
+      const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (!summaryFile && !activeMilestoneFound) {
+        // All slices complete but no summary written yet → completing-milestone
+        activeMilestone = { id: mid, title };
+        activeRoadmap = roadmap;
+        activeMilestoneFound = true;
+        registry.push({ id: mid, title, status: "active" });
+      } else {
+        registry.push({ id: mid, title, status: "complete" });
+      }
+    } else if (!activeMilestoneFound) {
+      // Check milestone-level dependencies before promoting to active
+      const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
+      const contextContent = contextFile ? await loadFile(contextFile) : null;
+      const deps = parseContextDependsOn(contextContent);
+      const depsUnmet = deps.some((dep) => !completeMilestoneIds.has(dep));
+      if (depsUnmet) {
+        registry.push({ id: mid, title, status: "pending", dependsOn: deps });
+        // Do NOT set activeMilestoneFound — let the loop continue to the next milestone
+      } else {
+        activeMilestone = { id: mid, title };
+        activeRoadmap = roadmap;
+        activeMilestoneFound = true;
+        registry.push({
+          id: mid,
+          title,
+          status: "active",
+          ...(deps.length > 0 ? { dependsOn: deps } : {}),
+        });
+      }
+    } else {
+      const contextFile2 = resolveMilestoneFile(basePath, mid, "CONTEXT");
+      const contextContent2 = contextFile2
+        ? await loadFile(contextFile2)
+        : null;
+      const deps2 = parseContextDependsOn(contextContent2);
+      registry.push({
+        id: mid,
+        title,
+        status: "pending",
+        ...(deps2.length > 0 ? { dependsOn: deps2 } : {}),
+      });
+    }
+  }
+
+  const milestoneProgress = {
+    done: registry.filter((entry) => entry.status === "complete").length,
+    total: registry.length,
+  };
+
+  if (!activeMilestone) {
+    // Check whether any milestones are pending (dep-blocked) vs all complete
+    const pendingEntries = registry.filter(
+      (entry) => entry.status === "pending",
+    );
+    if (pendingEntries.length > 0) {
+      // All incomplete milestones are dep-blocked — no progress possible
+      const blockerDetails = pendingEntries
+        .filter((entry) => entry.dependsOn && entry.dependsOn.length > 0)
+        .map(
+          (entry) =>
+            `${entry.id} is waiting on unmet deps: ${entry.dependsOn!.join(", ")}`,
+        );
+      return {
+        activeMilestone: null,
+        activeSlice: null,
+        activeTask: null,
+        phase: "blocked",
+        recentDecisions: [],
+        blockers:
+          blockerDetails.length > 0
+            ? blockerDetails
+            : [
+                "All remaining milestones are dep-blocked but no deps listed — check CONTEXT.md files",
+              ],
+        nextAction: "Resolve milestone dependencies before proceeding.",
+        registry,
+        requirements,
+        progress: {
+          milestones: milestoneProgress,
+        },
+      };
+    }
+    // All milestones complete
+    const lastEntry = registry[registry.length - 1];
+    return {
+      activeMilestone: lastEntry
+        ? { id: lastEntry.id, title: lastEntry.title }
+        : null,
+      activeSlice: null,
+      activeTask: null,
+      phase: "complete",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: "All milestones complete.",
+      registry,
+      requirements,
+      progress: {
+        milestones: milestoneProgress,
+      },
+    };
+  }
+
+  if (!activeRoadmap) {
+    // Active milestone exists but has no roadmap yet — needs planning
+    return {
+      activeMilestone,
+      activeSlice: null,
+      activeTask: null,
+      phase: "pre-planning",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: `Plan milestone ${activeMilestone.id}.`,
+      registry,
+      requirements,
+      progress: {
+        milestones: milestoneProgress,
+      },
+    };
+  }
+
+  // Check if active milestone needs completion (all slices done, no summary)
+  if (isMilestoneComplete(activeRoadmap)) {
+    const sliceProgress = {
+      done: activeRoadmap.slices.length,
+      total: activeRoadmap.slices.length,
+    };
+    return {
+      activeMilestone,
+      activeSlice: null,
+      activeTask: null,
+      phase: "completing-milestone",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: `All slices complete in ${activeMilestone.id}. Write milestone summary.`,
+      registry,
+      requirements,
+      progress: {
+        milestones: milestoneProgress,
+        slices: sliceProgress,
+      },
+    };
+  }
+
+  const sliceProgress = {
+    done: activeRoadmap.slices.filter((s) => s.done).length,
+    total: activeRoadmap.slices.length,
+  };
+
+  // Find the active slice (first incomplete with deps satisfied)
+  const doneSliceIds = new Set(
+    activeRoadmap.slices.filter((s) => s.done).map((s) => s.id),
+  );
+  let activeSlice: ActiveRef | null = null;
+
+  for (const s of activeRoadmap.slices) {
+    if (s.done) continue;
+    if (s.depends.every((dep) => doneSliceIds.has(dep))) {
+      activeSlice = { id: s.id, title: s.title };
+      break;
+    }
+  }
+
+  if (!activeSlice) {
+    return {
+      activeMilestone,
+      activeSlice: null,
+      activeTask: null,
+      phase: "blocked",
+      recentDecisions: [],
+      blockers: ["No slice eligible — check dependency ordering"],
+      nextAction: "Resolve dependency blockers or plan next slice.",
+      registry,
+      requirements,
+      progress: {
+        milestones: milestoneProgress,
+        slices: sliceProgress,
+      },
+    };
+  }
+
+  const activeBranch = getActiveSliceBranch(basePath);
+
+  // Check if the slice has a plan
+  const planFile = resolveSliceFile(
+    basePath,
+    activeMilestone.id,
+    activeSlice.id,
+    "PLAN",
+  );
+  const slicePlanContent = planFile ? await loadFile(planFile) : null;
+
+  if (!slicePlanContent) {
+    return {
+      activeMilestone,
+      activeSlice,
+      activeTask: null,
+      phase: "planning",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: `Plan slice ${activeSlice.id} (${activeSlice.title}).`,
+      activeBranch: activeBranch ?? undefined,
+      registry,
+      requirements,
+      progress: {
+        milestones: milestoneProgress,
+        slices: sliceProgress,
+      },
+    };
+  }
+
+  const slicePlan = parsePlan(slicePlanContent);
+  const taskProgress = {
+    done: slicePlan.tasks.filter((t) => t.done).length,
+    total: slicePlan.tasks.length,
+  };
+  const activeTaskEntry = slicePlan.tasks.find((t) => !t.done);
+
+  if (!activeTaskEntry) {
+    // All tasks done but slice not marked complete
+    return {
+      activeMilestone,
+      activeSlice,
+      activeTask: null,
+      phase: "summarizing",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`,
+      activeBranch: activeBranch ?? undefined,
+      registry,
+      requirements,
+      progress: {
+        milestones: milestoneProgress,
+        slices: sliceProgress,
+        tasks: taskProgress,
+      },
+    };
+  }
+
+  const activeTask: ActiveRef = {
+    id: activeTaskEntry.id,
+    title: activeTaskEntry.title,
+  };
+
+  // ── Blocker detection: scan completed task summaries ──────────────────
+  // If any completed task has blocker_discovered: true and no REPLAN.md
+  // exists yet, transition to replanning-slice instead of executing.
+  const completedTasks = slicePlan.tasks.filter((t) => t.done);
+  let blockerTaskId: string | null = null;
+  for (const ct of completedTasks) {
+    const summaryFile = resolveTaskFile(
+      basePath,
+      activeMilestone.id,
+      activeSlice.id,
+      ct.id,
+      "SUMMARY",
+    );
+    if (!summaryFile) continue;
+    const summaryContent = await loadFile(summaryFile);
+    if (!summaryContent) continue;
+    const summary = parseSummary(summaryContent);
+    if (summary.frontmatter.blocker_discovered) {
+      blockerTaskId = ct.id;
+      break;
+    }
+  }
+
+  if (blockerTaskId) {
+    // Loop protection: if REPLAN.md already exists, a replan was already
+    // performed for this slice — skip further replanning and continue executing.
+    const replanFile = resolveSliceFile(
+      basePath,
+      activeMilestone.id,
+      activeSlice.id,
+      "REPLAN",
+    );
+    if (!replanFile) {
+      return {
+        activeMilestone,
+        activeSlice,
+        activeTask,
+        phase: "replanning-slice",
+        recentDecisions: [],
+        blockers: [
+          `Task ${blockerTaskId} discovered a blocker requiring slice replan`,
+        ],
+        nextAction: `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`,
+        activeBranch: activeBranch ?? undefined,
+        activeWorkspace: undefined,
+        registry,
+        requirements,
+        progress: {
+          milestones: milestoneProgress,
+          slices: sliceProgress,
+          tasks: taskProgress,
+        },
+      };
+    }
+    // REPLAN.md exists — loop protection: fall through to normal executing
+  }
+
+  // Check for interrupted work
+  const sDir = resolveSlicePath(basePath, activeMilestone.id, activeSlice.id);
+  const continueFile = sDir
+    ? resolveSliceFile(basePath, activeMilestone.id, activeSlice.id, "CONTINUE")
+    : null;
+  // Also check legacy continue.md
+  const hasInterrupted =
+    !!(continueFile && (await loadFile(continueFile))) ||
+    !!(sDir && (await loadFile(join(sDir, "continue.md"))));
+
+  return {
+    activeMilestone,
+    activeSlice,
+    activeTask,
+    phase: "executing",
+    recentDecisions: [],
+    blockers: [],
+    nextAction: hasInterrupted
+      ? `Resume interrupted work on ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}. Read continue.md first.`
+      : `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
+    activeBranch: activeBranch ?? undefined,
+    registry,
+    requirements,
+    progress: {
+      milestones: milestoneProgress,
+      slices: sliceProgress,
+      tasks: taskProgress,
+    },
+  };
+}

package/src/resources/extensions/kata/templates/context.md

@@ -0,0 +1,76 @@
+# {{milestoneId}}: {{milestoneTitle}} — Context
+
+**Gathered:** {{date}}
+**Status:** Ready for planning
+
+## Project Description
+
+{{description}}
+
+## Why This Milestone
+
+{{whatProblemThisSolves_AND_whyNow}}
+
+## User-Visible Outcome
+
+### When this milestone is complete, the user can:
+
+- {{literalUserActionInRealEnvironment}}
+- {{literalUserActionInRealEnvironment}}
+
+### Entry point / environment
+
+- Entry point: {{CLI command / URL / bot / extension / service / workflow}}
+- Environment: {{local dev / browser / mobile / launchd / CI / production-like}}
+- Live dependencies involved: {{telegram / database / webhook / rpc subprocess / none}}
+
+## Completion Class
+
+- Contract complete means: {{what can be proven by tests / fixtures / artifacts}}
+- Integration complete means: {{what must work across real subsystems}}
+- Operational complete means: {{what must work under real lifecycle conditions, or none}}
+
+## Final Integrated Acceptance
+
+To call this milestone complete, we must prove:
+
+- {{one real end-to-end scenario}}
+- {{one real end-to-end scenario}}
+- {{what cannot be simulated if this milestone is to be considered truly done}}
+
+## Risks and Unknowns
+
+- {{riskOrUnknown}} — {{whyItMatters}}
+
+## Existing Codebase / Prior Art
+
+- `{{fileOrModule}}` — {{howItRelates}}
+- `{{fileOrModule}}` — {{howItRelates}}
+
+> See `.kata/DECISIONS.md` for all architectural and pattern decisions — it is an append-only register; read it during planning, append to it during execution.
+
+## Relevant Requirements
+
+- {{requirementId}} — {{howThisMilestoneAdvancesIt}}
+
+## Scope
+
+### In Scope
+
+- {{inScopeItem}}
+
+### Out of Scope / Non-Goals
+
+- {{outOfScopeItem}}
+
+## Technical Constraints
+
+- {{constraint}}
+
+## Integration Points
+
+- {{systemOrService}} — {{howThisMilestoneInteractsWithIt}}
+
+## Open Questions
+
+- {{question}} — {{currentThinking}}

package/src/resources/extensions/kata/templates/decisions.md

@@ -0,0 +1,8 @@
+# Decisions Register
+
+<!-- Append-only. Never edit or remove existing rows.
+     To reverse a decision, add a new row that supersedes it.
+     Read this file at the start of any planning or research phase. -->
+
+| # | When | Scope | Decision | Choice | Rationale | Revisable? |
+|---|------|-------|----------|--------|-----------|------------|

package/src/resources/extensions/kata/templates/milestone-summary.md

@@ -0,0 +1,73 @@
+---
+id: {{milestoneId}}
+provides:
+  - {{whatThisMilestoneProvides}}
+key_decisions:
+  - {{decision}}
+patterns_established:
+  - {{pattern}}
+observability_surfaces:
+  - {{status endpoint, structured log, persisted failure state, diagnostic command, or none}}
+requirement_outcomes:
+  - id: {{requirementId}}
+    from_status: {{active|blocked|deferred}}
+    to_status: {{validated|deferred|blocked|out_of_scope}}
+    proof: {{whatEvidenceSupportsThisTransition}}
+duration: {{duration}}
+verification_result: passed
+completed_at: {{date}}
+---
+
+# {{milestoneId}}: {{milestoneTitle}}
+
+<!-- One-liner must say what the milestone actually delivered, not just that it completed.
+     Good: "State machine integrity with completing-milestone gating, doctor audits, and observability validation"
+     Bad: "Milestone 2 completed" -->
+
+**{{oneLiner}}**
+
+## What Happened
+
+<!-- Cross-slice narrative: compress all slice summaries into a coherent story.
+     Focus on what was built, how the slices connected, and what the milestone
+     achieved as a whole — not a task-by-task replay. -->
+
+{{crossSliceNarrative}}
+
+## Cross-Slice Verification
+
+<!-- How were the milestone's success criteria verified?
+     Reference specific tests, commands, browser checks, or observable behaviors.
+     Each success criterion from the roadmap should have a corresponding verification entry. -->
+
+{{howSuccessCriteriaWereVerified}}
+
+## Requirement Changes
+
+<!-- Transitions with evidence. Each requirement that changed status during this milestone
+     should be listed with the proof that supports the transition. -->
+
+- {{requirementId}}: {{fromStatus}} → {{toStatus}} — {{evidence}}
+
+## Forward Intelligence
+
+<!-- Write what you wish you'd known at the start of this milestone.
+     This section is read by the next milestone's planning and research steps.
+     Be specific and concrete — this is the most valuable context you can transfer. -->
+
+### What the next milestone should know
+- {{insightThatWouldHelpDownstreamWork}}
+
+### What's fragile
+- {{fragileAreaOrThinImplementation}} — {{whyItMatters}}
+
+### Authoritative diagnostics
+- {{whereAFutureAgentShouldLookFirst}} — {{whyThisSignalIsTrustworthy}}
+
+### What assumptions changed
+- {{originalAssumption}} — {{whatActuallyHappened}}
+
+## Files Created/Modified
+
+- `{{filePath}}` — {{description}}
+- `{{filePath}}` — {{description}}