@pi-unipi/milestone 0.1.2

package/README.md

@@ -0,0 +1,123 @@
+# @pi-unipi/milestone
+
+Lifecycle layer for project-level goals. Track progress across multiple workflow cycles via a `MILESTONES.md` file with automatic context injection and sync.
+
+## Why
+
+Workflow operates at the task level — brainstorm, plan, work, review. But project goals are scattered across specs, plans, and quick-work docs. Milestone provides a unified view of "what's left to do" and keeps the agent aligned with project goals across sessions.
+
+## How It Works
+
+1. **MILESTONES.md** — A markdown file with phases and checkbox items that tracks your project goals
+2. **Session start hook** — Reads milestones and injects progress summary into the system prompt
+3. **Session end hook** — Scans modified workflow docs, detects completed items, auto-updates milestones
+4. **Coexist triggers** — Hooks into brainstorm/plan/consolidate to suggest milestone updates
+
+## MILESTONES.md Format
+
+```markdown
+---
+title: "Project Milestones"
+created: 2026-04-28
+updated: 2026-04-28
+---
+
+# Project Milestones
+
+## Phase 1: Foundation
+> Set up the core infrastructure
+
+- [x] Project scaffold and build system
+- [x] Database schema design
+- [ ] Authentication system
+- [ ] API routing layer
+
+## Phase 2: Core Features
+> Build the primary user-facing features
+
+- [ ] User dashboard
+- [ ] File upload system
+- [ ] Notification service
+```
+
+## Skills
+
+### `/unipi:milestone-onboard`
+
+Create MILESTONES.md from existing workflow docs. Scans specs, plans, quick-work, debug, fix, and chore docs to group scattered tasks into coherent milestone phases.
+
+**Phases:** Explore → Propose → Refine → Write → Report
+
+### `/unipi:milestone-update`
+
+Sync MILESTONES.md with completed work. Detects checkbox changes in workflow docs and updates milestone items.
+
+**Phases:** Scan → Diff → Resolve → Write → Report
+
+## API Exports
+
+```typescript
+import {
+  parseMilestones,      // Parse MILESTONES.md → MilestoneDoc
+  writeMilestones,      // Write MilestoneDoc → MILESTONES.md
+  updateItemStatus,     // Toggle a checkbox item
+  getProgressSummary,   // Get progress stats
+} from "@pi-unipi/milestone";
+
+import type {
+  MilestoneDoc,
+  MilestonePhase,
+  MilestoneItem,
+  ProgressSummary,
+  PhaseProgress,
+} from "@pi-unipi/milestone";
+```
+
+## Lifecycle Hooks
+
+### Session Start
+
+On `before_agent_start`, reads `.unipi/docs/MILESTONES.md` and appends a progress summary to the system prompt:
+
+```
+## Project Milestones
+Overall progress: 5/10 items (50%)
+  Phase 1: Foundation: 3/5 done
+  Phase 2: Features: 2/5 done
+Current focus: Phase 1: Foundation
+```
+
+If MILESTONES.md doesn't exist, no context is injected.
+
+### Session End
+
+On `session_shutdown`, scans workflow docs modified during the session. Detects items that changed from `- [ ]` to `- [x]` and auto-updates MILESTONES.md using exact text matching.
+
+Unmatched items are logged as warnings — resolve manually with `/unipi:milestone-update`.
+
+## Coexist Triggers
+
+| Trigger | Behavior |
+|---------|----------|
+| After brainstorm | Checks if new spec items map to milestones, logs suggestions |
+| After plan | Maps plan tasks to milestone items, logs coverage |
+| After consolidate | References auto-sync from session shutdown |
+
+All triggers are non-blocking and skip gracefully if MILESTONES.md doesn't exist.
+
+## Info Screen
+
+Registers a "Milestones" group in the info-screen dashboard showing:
+- **Progress** — completed/total items with percentage
+- **Current Phase** — phase name with per-phase breakdown
+- **Remaining** — items left to complete
+
+## Configuration
+
+No configuration needed. Place MILESTONES.md at `.unipi/docs/MILESTONES.md` and the extension handles the rest.
+
+## Dependencies
+
+- `@pi-unipi/core` — shared constants and utilities
+- `@mariozechner/pi-coding-agent` — extension API
+- `@mariozechner/pi-tui` — TUI types

package/coexist.ts

@@ -0,0 +1,123 @@
+/**
+ * @pi-unipi/milestone — Coexist triggers
+ *
+ * Hooks into workflow skill completions to offer milestone integration.
+ * Non-blocking — if MILESTONES.md doesn't exist, triggers silently skip.
+ */
+
+import * as path from "node:path";
+import { MILESTONE_DIRS, tryRead } from "@pi-unipi/core";
+import { parseMilestones, updateItemStatus, writeMilestones } from "./milestone.js";
+import type { MilestoneDoc } from "./types.js";
+
+/**
+ * After brainstorm completes: check if new spec items map to milestones.
+ * Offers to mark matching items as planned.
+ */
+export function onBrainstormComplete(specPath: string): void {
+  const cwd = process.cwd();
+  const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+
+  // Silently skip if no MILESTONES.md
+  if (!tryRead(milestonesPath)) return;
+
+  const specContent = tryRead(specPath);
+  if (!specContent) return;
+
+  // Extract checklist items from the new spec
+  const specItems: string[] = [];
+  for (const line of specContent.split("\n")) {
+    const match = line.match(/^-\s+\[([ xX])\]\s+(.+)$/);
+    if (match) {
+      specItems.push(match[2].trim().toLowerCase());
+    }
+  }
+
+  if (specItems.length === 0) return;
+
+  // Check against milestones
+  const doc = parseMilestones(milestonesPath);
+  const matched: string[] = [];
+
+  for (const phase of doc.phases) {
+    for (const item of phase.items) {
+      const normalized = item.text.toLowerCase().trim();
+      if (specItems.includes(normalized) && !item.checked) {
+        matched.push(`"${item.text}" in ${phase.name}`);
+      }
+    }
+  }
+
+  if (matched.length > 0) {
+    console.log(
+      `[milestone] Brainstorm spec contains items that map to milestones: ${matched.join(", ")}`,
+    );
+    console.log(
+      `[milestone] Run /unipi:milestone-update to sync after completing work.`,
+    );
+  }
+}
+
+/**
+ * After plan completes: check if plan tasks map to milestone items.
+ * Logs matching items for awareness.
+ */
+export function onPlanComplete(planPath: string): void {
+  const cwd = process.cwd();
+  const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+
+  // Silently skip if no MILESTONES.md
+  if (!tryRead(milestonesPath)) return;
+
+  const planContent = tryRead(planPath);
+  if (!planContent) return;
+
+  // Extract task names from plan (### Task N — Name pattern)
+  const planTasks: string[] = [];
+  for (const line of planContent.split("\n")) {
+    const match = line.match(/^###\s+Task\s+\d+\s*[—–-]\s*(.+)$/);
+    if (match) {
+      planTasks.push(match[1].trim().toLowerCase());
+    }
+  }
+
+  if (planTasks.length === 0) return;
+
+  // Check against milestones
+  const doc = parseMilestones(milestonesPath);
+  const matched: string[] = [];
+
+  for (const phase of doc.phases) {
+    for (const item of phase.items) {
+      const normalized = item.text.toLowerCase().trim();
+      // Check if any plan task contains the milestone item text or vice versa
+      for (const task of planTasks) {
+        if (task.includes(normalized) || normalized.includes(task)) {
+          matched.push(`"${item.text}" → plan task`);
+          break;
+        }
+      }
+    }
+  }
+
+  if (matched.length > 0) {
+    console.log(
+      `[milestone] Plan covers milestone items: ${matched.join(", ")}`,
+    );
+  }
+}
+
+/**
+ * After consolidate: reference milestone sync that already happened.
+ */
+export function onConsolidate(): void {
+  const cwd = process.cwd();
+  const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+
+  if (!tryRead(milestonesPath)) return;
+
+  // Just log that milestone sync was handled by session_shutdown hook
+  console.log(
+    `[milestone] Milestone progress was auto-synced during session shutdown.`,
+  );
+}

package/commands.ts

@@ -0,0 +1,97 @@
+/**
+ * @pi-unipi/milestone — Command registration
+ *
+ * Registers milestone-onboard and milestone-update commands.
+ * Follows the same pattern as workflow/commands.ts:
+ * loads SKILL.md content and sends it as a user message.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { UNIPI_PREFIX, MILESTONE_COMMANDS, MILESTONE_DIRS } from "@pi-unipi/core";
+import { parseMilestones } from "./milestone.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Resolve the skills directory relative to this file */
+const SKILLS_DIR = join(new URL(".", import.meta.url).pathname, "skills");
+
+/**
+ * Load SKILL.md content for a given skill name.
+ */
+function loadSkill(skillName: string): string {
+  try {
+    return readFileSync(join(SKILLS_DIR, skillName, "SKILL.md"), "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Register milestone commands with the extension API.
+ */
+export function registerCommands(pi: ExtensionAPI): void {
+  // milestone-onboard — create milestones from existing work
+  pi.registerCommand(`${UNIPI_PREFIX}${MILESTONE_COMMANDS.ONBOARD}`, {
+    description: "Create MILESTONES.md from existing workflow docs — scan, propose, refine, write",
+    handler: async (args: string, ctx: any) => {
+      const skillContent = loadSkill("milestone-onboard");
+
+      let message = "Execute the milestone-onboard workflow.";
+      if (args?.trim()) {
+        message += `\n\nArguments: ${args.trim()}`;
+      }
+      if (skillContent) {
+        message += `\n\n<skill_content>\n${skillContent}\n</skill_content>`;
+      }
+
+      pi.sendUserMessage(message, { deliverAs: "followUp" });
+
+      if (ctx.hasUI) {
+        ctx.ui.notify("Running /unipi:milestone-onboard", "info");
+      }
+    },
+  });
+
+  // milestone-update — sync milestones with completed work
+  pi.registerCommand(`${UNIPI_PREFIX}${MILESTONE_COMMANDS.UPDATE}`, {
+    description: "Sync MILESTONES.md with completed work — scan docs, diff checkboxes, auto-update",
+    handler: async (args: string, ctx: any) => {
+      const skillContent = loadSkill("milestone-update");
+
+      let message = "Execute the milestone-update workflow.";
+      if (args?.trim()) {
+        message += `\n\nArguments: ${args.trim()}`;
+      }
+      if (skillContent) {
+        message += `\n\n<skill_content>\n${skillContent}\n</skill_content>`;
+      }
+
+      pi.sendUserMessage(message, { deliverAs: "followUp" });
+
+      if (ctx.hasUI) {
+        ctx.ui.notify("Running /unipi:milestone-update", "info");
+      }
+    },
+    getArgumentCompletions: () => {
+      // Suggest phase names from existing MILESTONES.md
+      const cwd = process.cwd();
+      const milestonesPath = join(cwd, MILESTONE_DIRS.MILESTONES);
+      const doc = parseMilestones(milestonesPath);
+
+      const suggestions = doc.phases.map((phase) => ({
+        value: phase.name,
+        label: phase.name,
+        description: `${phase.items.filter((i) => i.checked).length}/${phase.items.length} done`,
+      }));
+
+      // Add "all" option
+      suggestions.unshift({
+        value: "all",
+        label: "all",
+        description: "Update all phases",
+      });
+
+      return suggestions;
+    },
+  });
+}

package/hooks.ts

@@ -0,0 +1,212 @@
+/**
+ * @pi-unipi/milestone — Lifecycle hooks
+ *
+ * Session start: inject milestone progress as system context.
+ * Session end: auto-sync completed items from workflow docs.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MILESTONE_DIRS, safeMtimeMs, tryRead } from "@pi-unipi/core";
+import { parseMilestones, getProgressSummary, updateItemStatus } from "./milestone.js";
+
+/** Track when the session started for diffing modified files */
+let sessionStartMs = 0;
+
+/**
+ * Format a progress summary as a context string for the system prompt.
+ */
+function formatMilestoneContext(filePath: string): string | null {
+  const summary = getProgressSummary(filePath);
+  if (summary.totalItems === 0) return null;
+
+  const phaseLines = summary.phases
+    .filter((p) => p.total > 0)
+    .map((p) => `  ${p.name}: ${p.done}/${p.total} done`);
+
+  const focus = summary.currentPhase
+    ? `Current focus: ${summary.currentPhase}`
+    : "";
+
+  return [
+    "## Project Milestones",
+    `Overall progress: ${summary.completedItems}/${summary.totalItems} items (${summary.percentComplete}%)`,
+    ...phaseLines,
+    focus,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * Register session start hook — injects milestone progress into system context.
+ */
+export function registerSessionStartHook(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => {
+    sessionStartMs = Date.now();
+
+    const cwd = process.cwd();
+    const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+
+    const context = formatMilestoneContext(milestonesPath);
+    if (!context) return undefined;
+
+    // Append milestone context to the system prompt
+    const currentPrompt = (event as any).systemPrompt ?? "";
+    return {
+      systemPrompt: currentPrompt + "\n\n" + context,
+    };
+  });
+}
+
+/**
+ * Extract checkbox items that changed from [ ] to [x] in a file.
+ * Compares current state against a baseline snapshot.
+ */
+function extractNewCompletions(
+  filePath: string,
+  baselineContent: string,
+): Array<{ text: string; phase: string }> {
+  const currentContent = tryRead(filePath);
+  if (!currentContent) return [];
+
+  const baselineLines = baselineContent.split("\n");
+  const currentLines = currentContent.split("\n");
+  const results: Array<{ text: string; phase: string }> = [];
+  let currentPhase = "";
+
+  for (let i = 0; i < currentLines.length; i++) {
+    const line = currentLines[i];
+
+    // Track phase
+    const phaseMatch = line.match(/^##\s+(.+)$/);
+    if (phaseMatch) {
+      currentPhase = phaseMatch[1].trim();
+      continue;
+    }
+
+    // Check if this line is a newly checked item
+    const currentItemMatch = line.match(/^-\s+\[x\]\s+(.+)$/);
+    if (currentItemMatch && currentPhase) {
+      // Check if baseline had this as unchecked
+      const baselineLine = baselineLines[i] ?? "";
+      const baselineItemMatch = baselineLine.match(/^-\s+\[([ xX])\]\s+(.+)$/);
+      if (baselineItemMatch && baselineItemMatch[1] === " ") {
+        // Same position, was unchecked, now checked
+        results.push({ text: currentItemMatch[1].trim(), phase: currentPhase });
+      } else if (!baselineItemMatch) {
+        // Line didn't exist or wasn't a checkbox — check by text match in same phase
+        const text = currentItemMatch[1].trim().toLowerCase();
+        const foundUnchecked = baselineLines.some((bl) => {
+          const m = bl.match(/^-\s+\[\s\]\s+(.+)$/);
+          return m && m[1].trim().toLowerCase() === text;
+        });
+        if (foundUnchecked) {
+          results.push({ text: currentItemMatch[1].trim(), phase: currentPhase });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Scan workflow docs for files modified since session start.
+ */
+function scanModifiedDocs(dirs: string[], since: number): string[] {
+  const modified: string[] = [];
+
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const filePath = path.join(dir, entry.name);
+      const mtime = safeMtimeMs(filePath);
+      if (mtime > since) {
+        modified.push(filePath);
+      }
+    }
+  }
+
+  return modified;
+}
+
+/**
+ * Register session end hook — listens for WORKFLOW_END events,
+ * scans modified docs, and auto-updates MILESTONES.md.
+ */
+export function registerSessionEndHook(pi: ExtensionAPI): void {
+  // Store baseline snapshots at session start
+  const baselineSnapshots = new Map<string, string>();
+
+  // Capture baselines on session start
+  pi.on("session_start", () => {
+    sessionStartMs = Date.now();
+    baselineSnapshots.clear();
+
+    const cwd = process.cwd();
+    const scanDirs = [
+      path.join(cwd, ".unipi/docs/specs"),
+      path.join(cwd, ".unipi/docs/plans"),
+      path.join(cwd, ".unipi/docs/quick-work"),
+    ];
+
+    for (const dir of scanDirs) {
+      if (!fs.existsSync(dir)) continue;
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const filePath = path.join(dir, entry.name);
+        const content = tryRead(filePath);
+        if (content) baselineSnapshots.set(filePath, content);
+      }
+    }
+  });
+
+  // Listen for WORKFLOW_END events
+  pi.on("input", (event) => {
+    // Check if this is a unipi event emission for WORKFLOW_END
+    // The input event fires for tool calls; we need to detect when
+    // the workflow ends. We'll use the events system instead.
+    return undefined;
+  });
+
+  // Use tool_result to detect workflow end
+  // Actually, we should listen for the UNIPI_EVENTS.WORKFLOW_END via pi.events
+  // But the ExtensionAPI doesn't expose pi.events.on() directly.
+  // Instead, we'll hook into session_shutdown to do a final sync.
+  pi.on("session_shutdown", () => {
+    const cwd = process.cwd();
+    const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+
+    if (!fs.existsSync(milestonesPath)) return;
+
+    const scanDirs = [
+      path.join(cwd, ".unipi/docs/specs"),
+      path.join(cwd, ".unipi/docs/plans"),
+      path.join(cwd, ".unipi/docs/quick-work"),
+    ];
+
+    const modifiedFiles = scanModifiedDocs(scanDirs, sessionStartMs);
+
+    for (const filePath of modifiedFiles) {
+      const baseline = baselineSnapshots.get(filePath);
+      if (!baseline) continue;
+
+      const completions = extractNewCompletions(filePath, baseline);
+      for (const { text, phase } of completions) {
+        // Try exact match update
+        const updated = updateItemStatus(milestonesPath, phase, text, true);
+        if (!updated) {
+          console.warn(
+            `[milestone] Could not auto-update "${text}" in phase "${phase}" — no exact match found`,
+          );
+        }
+      }
+    }
+  });
+}

package/index.ts

@@ -0,0 +1,72 @@
+/**
+ * @pi-unipi/milestone — Extension entry point
+ *
+ * Lifecycle layer for project-level goals. Tracks progress via MILESTONES.md,
+ * injects context on session start, auto-syncs on session end.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MODULES, MILESTONE_COMMANDS, MILESTONE_DIRS, emitEvent, UNIPI_EVENTS } from "@pi-unipi/core";
+import { registerSessionStartHook, registerSessionEndHook } from "./hooks.js";
+import { registerCommands } from "./commands.js";
+import { getProgressSummary } from "./milestone.js";
+import * as path from "node:path";
+
+export default function milestoneExtension(pi: ExtensionAPI): void {
+  // Register lifecycle hooks
+  registerSessionStartHook(pi);
+  registerSessionEndHook(pi);
+
+  // Register commands
+  registerCommands(pi);
+
+  // Register info-screen group
+  const globalObj = globalThis as any;
+  const registry = globalObj.__unipi_info_registry;
+  if (registry) {
+    registry.registerGroup({
+      id: "milestone",
+      name: "Milestones",
+      icon: "🎯",
+      priority: 40,
+      config: {
+        showByDefault: true,
+        stats: [
+          { id: "progress", label: "Progress", show: true },
+          { id: "current_phase", label: "Current Phase", show: true },
+          { id: "remaining", label: "Remaining", show: true },
+        ],
+      },
+      dataProvider: async () => {
+        const cwd = process.cwd();
+        const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+        const summary = getProgressSummary(milestonesPath);
+
+        return {
+          progress: {
+            value: `${summary.completedItems}/${summary.totalItems}`,
+            detail: `${summary.percentComplete}% complete`,
+          },
+          current_phase: {
+            value: summary.currentPhase || "None",
+            detail: summary.phases.length > 0
+              ? summary.phases.map((p) => `${p.name}: ${p.done}/${p.total}`).join(", ")
+              : "No milestones defined",
+          },
+          remaining: {
+            value: String(summary.totalItems - summary.completedItems),
+            detail: "items remaining",
+          },
+        };
+      },
+    });
+  }
+
+  // Emit module ready event
+  emitEvent(pi as any, UNIPI_EVENTS.MODULE_READY, {
+    name: MODULES.MILESTONE,
+    version: "0.1.0",
+    commands: Object.values(MILESTONE_COMMANDS),
+    tools: [],
+  });
+}

package/milestone.ts

@@ -0,0 +1,238 @@
+/**
+ * @pi-unipi/milestone — MILESTONES.md parser, writer, and updater
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensureDir, tryRead } from "@pi-unipi/core";
+import type { MilestoneDoc, MilestonePhase, MilestoneItem, ProgressSummary } from "./types.js";
+
+/** Default empty milestone doc */
+function emptyDoc(filePath: string): MilestoneDoc {
+  return {
+    title: "Project Milestones",
+    created: new Date().toISOString().split("T")[0],
+    updated: new Date().toISOString().split("T")[0],
+    phases: [],
+    filePath,
+  };
+}
+
+/**
+ * Parse a MILESTONES.md file into a MilestoneDoc.
+ * Handles missing file (returns empty doc) and malformed input (skips unparseable lines).
+ */
+export function parseMilestones(filePath: string): MilestoneDoc {
+  const content = tryRead(filePath);
+  if (!content) return emptyDoc(filePath);
+
+  const lines = content.split("\n");
+  const doc = emptyDoc(filePath);
+  let currentPhase: MilestonePhase | null = null;
+  let inFrontmatter = false;
+  let frontmatterDone = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1; // 1-indexed
+
+    // Frontmatter parsing
+    if (lineNum === 1 && line.trim() === "---") {
+      inFrontmatter = true;
+      continue;
+    }
+    if (inFrontmatter) {
+      if (line.trim() === "---") {
+        inFrontmatter = false;
+        frontmatterDone = true;
+        continue;
+      }
+      const match = line.match(/^(\w+):\s*(.+)$/);
+      if (match) {
+        const [, key, value] = match;
+        if (key === "title") doc.title = value.replace(/^["']|["']$/g, "");
+        if (key === "created") doc.created = value.trim();
+        if (key === "updated") doc.updated = value.trim();
+      }
+      continue;
+    }
+
+    // Phase header: ## Phase N: Name or ## Name
+    const phaseMatch = line.match(/^##\s+(.+)$/);
+    if (phaseMatch) {
+      currentPhase = {
+        name: phaseMatch[1].trim(),
+        items: [],
+      };
+      doc.phases.push(currentPhase);
+      continue;
+    }
+
+    // Phase description: > text
+    if (currentPhase && line.match(/^>\s*(.*)$/)) {
+      const desc = line.replace(/^>\s*/, "").trim();
+      if (desc) {
+        currentPhase.description = currentPhase.description
+          ? `${currentPhase.description} ${desc}`
+          : desc;
+      }
+      continue;
+    }
+
+    // Checkbox item: - [ ] text or - [x] text
+    const itemMatch = line.match(/^-\s+\[([ xX])\]\s+(.+)$/);
+    if (itemMatch && currentPhase) {
+      const checked = itemMatch[1].toLowerCase() === "x";
+      const text = itemMatch[2].trim();
+      currentPhase.items.push({
+        text,
+        checked,
+        lineNumber: lineNum,
+      });
+      continue;
+    }
+  }
+
+  return doc;
+}
+
+/**
+ * Write a MilestoneDoc to a MILESTONES.md file.
+ * Generates frontmatter, phase headers, descriptions, and checkbox items.
+ */
+export function writeMilestones(filePath: string, doc: MilestoneDoc): void {
+  const lines: string[] = [];
+
+  // Frontmatter
+  lines.push("---");
+  lines.push(`title: "${doc.title}"`);
+  lines.push(`created: ${doc.created}`);
+  lines.push(`updated: ${doc.updated}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${doc.title}`);
+  lines.push("");
+
+  // Phases
+  for (const phase of doc.phases) {
+    lines.push(`## ${phase.name}`);
+    if (phase.description) {
+      lines.push(`> ${phase.description}`);
+    }
+    lines.push("");
+    for (const item of phase.items) {
+      const check = item.checked ? "[x]" : "[ ]";
+      lines.push(`- ${check} ${item.text}`);
+    }
+    lines.push("");
+  }
+
+  ensureDir(filePath);
+  // Atomic write: write to temp, rename
+  const tmpPath = filePath + ".tmp";
+  fs.writeFileSync(tmpPath, lines.join("\n"), "utf-8");
+  fs.renameSync(tmpPath, filePath);
+}
+
+/**
+ * Toggle a checkbox item's status in a MILESTONES.md file.
+ * Matches by normalized (lowercase, trimmed) phase name and item text.
+ * Returns true if item was found and updated.
+ */
+export function updateItemStatus(
+  filePath: string,
+  phaseName: string,
+  itemText: string,
+  checked: boolean,
+): boolean {
+  const content = tryRead(filePath);
+  if (!content) return false;
+
+  const lines = content.split("\n");
+  const normalizedPhase = phaseName.toLowerCase().trim();
+  const normalizedItem = itemText.toLowerCase().trim();
+  let currentPhase = "";
+  let found = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Track current phase
+    const phaseMatch = line.match(/^##\s+(.+)$/);
+    if (phaseMatch) {
+      currentPhase = phaseMatch[1].trim().toLowerCase();
+      continue;
+    }
+
+    // Match checkbox in the target phase
+    if (currentPhase === normalizedPhase) {
+      const itemMatch = line.match(/^-\s+\[([ xX])\]\s+(.+)$/);
+      if (itemMatch) {
+        const lineText = itemMatch[2].trim().toLowerCase();
+        if (lineText === normalizedItem) {
+          const mark = checked ? "x" : " ";
+          lines[i] = `- [${mark}] ${itemMatch[2].trim()}`;
+          found = true;
+          break;
+        }
+      }
+    }
+  }
+
+  if (found) {
+    // Update the 'updated' frontmatter date
+    const today = new Date().toISOString().split("T")[0];
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].match(/^updated:\s*/)) {
+        lines[i] = `updated: ${today}`;
+        break;
+      }
+    }
+
+    // Atomic write
+    const tmpPath = filePath + ".tmp";
+    fs.writeFileSync(tmpPath, lines.join("\n"), "utf-8");
+    fs.renameSync(tmpPath, filePath);
+  }
+
+  return found;
+}
+
+/**
+ * Get a progress summary from a MILESTONES.md file.
+ * Returns empty summary if file doesn't exist.
+ */
+export function getProgressSummary(filePath: string): ProgressSummary {
+  const doc = parseMilestones(filePath);
+
+  let totalItems = 0;
+  let completedItems = 0;
+  let currentPhase = "";
+  const phases: ProgressSummary["phases"] = [];
+
+  for (const phase of doc.phases) {
+    const done = phase.items.filter((i) => i.checked).length;
+    const total = phase.items.length;
+    totalItems += total;
+    completedItems += done;
+
+    phases.push({
+      name: phase.name,
+      done,
+      total,
+    });
+
+    // Current phase: first phase with incomplete items
+    if (!currentPhase && done < total) {
+      currentPhase = phase.name;
+    }
+  }
+
+  return {
+    totalItems,
+    completedItems,
+    percentComplete: totalItems > 0 ? Math.round((completedItems / totalItems) * 100) : 0,
+    currentPhase: currentPhase || (doc.phases.length > 0 ? doc.phases[0].name : "None"),
+    phases,
+  };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pi-unipi/milestone",
+  "version": "0.1.2",
+  "description": "Lifecycle layer for project-level goals — MILESTONES.md tracking, session hooks, auto-sync",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/milestone"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "milestone",
+    "goals",
+    "progress"
+  ],
+  "files": [
+    "*.ts",
+    "skills/**/*",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.0"
+  }
+}

package/skills/milestone-onboard/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: milestone-onboard
+description: "Create MILESTONES.md from existing workflow docs — scan, propose, refine, write."
+---
+
+# Onboard Milestones
+
+Create a MILESTONES.md file by scanning existing workflow documentation. Groups scattered tasks into coherent milestone phases.
+
+## Boundaries
+
+**This skill MAY:** read `.unipi/docs/`, read existing specs/plans/quick-work/debug/fix/chore docs, write `.unipi/docs/MILESTONES.md`.
+**This skill MAY NOT:** modify existing workflow docs, delete files, merge branches.
+
+---
+
+## Phase 1: Explore
+
+Scan `.unipi/docs/` for existing workflow documentation. Understand what's been done and what's planned.
+
+1. List all files in `.unipi/docs/{specs,plans,quick-work,debug,fix,chore}/`
+2. For each file, extract:
+   - Checkbox items (`- [ ]` and `- [x]`)
+   - Task statuses (`unstarted:`, `in-progress:`, `completed:`)
+   - File modification dates
+3. Categorize findings:
+   - **Completed work** — checked items, completed tasks
+   - **In progress** — in-progress tasks, partially checked lists
+   - **Planned** — unstarted tasks, unchecked items
+4. Present summary to user:
+   > "Found X completed items, Y in-progress, Z planned across N documents."
+
+---
+
+## Phase 2: Propose
+
+Group findings into logical milestone phases. Present with rationale.
+
+1. Analyze themes across documents — group related items together
+2. Suggest 2-5 phases with clear names and descriptions
+3. For each phase, list proposed items (both done and todo)
+4. Present proposal:
+   > "**Phase 1: Foundation** (3/5 done)
+   > - [x] Project scaffold
+   > - [x] Core parser
+   > - [ ] Type definitions
+   > - [ ] Error handling
+   > - [ ] Documentation
+   >
+   > **Phase 2: Features** (0/3 done)
+   > - [ ] User dashboard
+   > - [ ] File upload
+   > - [ ] Notifications
+   >
+   > Does this grouping look right?"
+
+5. **One question at a time** — ask if phases are correct before proceeding
+
+---
+
+## Phase 3: Refine
+
+User approves/adjusts phases. Iterate until satisfied.
+
+1. If user wants changes:
+   - **Add phase**: Ask for name and items
+   - **Remove phase**: Confirm removal
+   - **Move items**: Ask which item, which phase
+   - **Rename phase**: Ask for new name
+   - **Add items**: Ask for text and target phase
+2. After each change, show updated proposal
+3. Continue until user says "looks good" or "write it"
+
+---
+
+## Phase 4: Write
+
+Save MILESTONES.md using the milestone parser.
+
+1. Build `MilestoneDoc` from approved phases:
+   - `title`: "Project Milestones" (or ask user for custom title)
+   - `created`: today's date
+   - `updated`: today's date
+   - `phases`: approved phases with items
+2. Call `writeMilestones(".unipi/docs/MILESTONES.md", doc)`
+3. Verify file was written correctly
+
+---
+
+## Phase 5: Report
+
+Show summary and suggest next steps.
+
+1. Display what was written:
+   > "✅ MILESTONES.md created with N phases and M items.
+   > - Phase 1: Foundation (3/5 done)
+   > - Phase 2: Features (0/3 done)
+   >
+   > **Next steps:**
+   > - `/unipi:milestone-update` — sync milestones with completed work
+   > - Milestones will auto-inject context on session start
+   > - Completed items auto-sync on session end"
+
+---
+
+## Validation Checklist
+
+Before completing, verify:
+- [ ] MILESTONES.md exists at `.unipi/docs/MILESTONES.md`
+- [ ] File has valid frontmatter (title, created, updated)
+- [ ] All phases have names
+- [ ] All items have checkbox format (`- [ ]` or `- [x]`)
+- [ ] Previously completed items are marked `[x]`
+- [ ] File parses correctly via `parseMilestones()`

package/skills/milestone-update/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: milestone-update
+description: "Sync MILESTONES.md with completed work — scan docs, diff checkboxes, auto-update."
+---
+
+# Update Milestones
+
+Sync MILESTONES.md with work completed in workflow docs. Detects checkbox changes and updates milestone items.
+
+## Boundaries
+
+**This skill MAY:** read `.unipi/docs/`, update `.unipi/docs/MILESTONES.md`, ask user for conflict resolution.
+**This skill MAY NOT:** modify workflow docs, delete files, create new milestones (use `/unipi:milestone-onboard`).
+
+---
+
+## Phase 1: Scan
+
+Read all workflow docs modified since last milestone update.
+
+1. Read `.unipi/docs/MILESTONES.md` — if missing, suggest `/unipi:milestone-onboard`
+2. Record `updated` date from MILESTONES.md frontmatter
+3. Scan `.unipi/docs/{specs,plans,quick-work}/` for files modified after the `updated` date
+4. If no modified files found:
+   > "No workflow docs have been modified since the last milestone update."
+5. List modified files and present to user
+
+---
+
+## Phase 2: Diff
+
+Compare checkbox states between current docs and baseline.
+
+1. For each modified file:
+   - Extract all checkbox items (`- [ ]` and `- [x]`)
+   - Extract task statuses from plans (`completed:`)
+2. Compare against MILESTONES.md items:
+   - **Exact match** (normalized): item text matches a milestone item
+   - **No match**: item not found in milestones
+3. Categorize:
+   - **Newly completed**: item is `[x]` in doc but `[ ]` in milestones
+   - **Already synced**: item matches milestone state
+   - **Unmatched**: item not in milestones at all
+4. Present diff:
+   > "**Found 3 changes:**
+   > - ✅ `Authentication system` — completed in spec.md (exact match)
+   > - ✅ `API routing` — completed in plan.md (exact match)
+   > - ⚠️ `New feature idea` — not found in milestones (skipped)"
+
+---
+
+## Phase 3: Resolve
+
+Auto-update clear matches, ask user on conflicts.
+
+1. **Exact matches**: Update automatically via `updateItemStatus()`
+2. **Unmatched completions**: Present to user via `ask_user`:
+   > "Found completed items not in milestones:
+   > 1. `New feature idea` (from spec.md)
+   >
+   > What should I do?"
+   > - Skip (don't update milestones)
+   > - Add to a phase (specify which)
+3. If user wants to add: ask which phase, then add item and mark as completed
+4. Log all changes made
+
+---
+
+## Phase 4: Write
+
+Apply resolved changes to MILESTONES.md.
+
+1. For each resolved change:
+   - Call `updateItemStatus(milestonesPath, phase, text, true)` for completions
+   - Or modify doc directly for new items
+2. Update `updated` frontmatter date to today
+3. Verify file still parses correctly
+
+---
+
+## Phase 5: Report
+
+Show what changed, what was skipped, suggest next steps.
+
+1. Display summary:
+   > "✅ **Milestones updated:**
+   > - 2 items marked complete
+   > - 1 item skipped (not in milestones)
+   >
+   > **Progress:** 5/10 items (50%)
+   > **Current phase:** Phase 1: Foundation (3/5 done)
+   >
+   > **Next steps:**
+   > - Continue with remaining items
+   > - `/unipi:milestone-onboard` — restructure milestones"
+
+2. If no changes were made:
+   > "No milestone items needed updating. Everything is in sync."
+
+---
+
+## Validation Checklist
+
+Before completing, verify:
+- [ ] MILESTONES.md still exists and is valid
+- [ ] All auto-updated items match their source docs
+- [ ] `updated` date reflects today
+- [ ] No items were accidentally unchecked
+- [ ] File parses correctly via `parseMilestones()`

package/types.ts

@@ -0,0 +1,61 @@
+/**
+ * @pi-unipi/milestone — Type definitions
+ */
+
+/** A single item within a milestone phase */
+export interface MilestoneItem {
+  /** Item text (without checkbox) */
+  text: string;
+  /** Whether item is checked off */
+  checked: boolean;
+  /** Line number in the source file (1-indexed) */
+  lineNumber: number;
+}
+
+/** A phase grouping milestone items */
+export interface MilestonePhase {
+  /** Phase name (e.g., "Phase 1: Foundation") */
+  name: string;
+  /** Optional description (from `>` blockquote lines) */
+  description?: string;
+  /** Items in this phase */
+  items: MilestoneItem[];
+}
+
+/** Parsed representation of a MILESTONES.md file */
+export interface MilestoneDoc {
+  /** Document title from frontmatter */
+  title: string;
+  /** Creation date (ISO string) */
+  created: string;
+  /** Last update date (ISO string) */
+  updated: string;
+  /** Ordered list of phases */
+  phases: MilestonePhase[];
+  /** Source file path */
+  filePath: string;
+}
+
+/** Per-phase progress */
+export interface PhaseProgress {
+  /** Phase name */
+  name: string;
+  /** Completed items in this phase */
+  done: number;
+  /** Total items in this phase */
+  total: number;
+}
+
+/** Progress summary across all phases */
+export interface ProgressSummary {
+  /** Total items across all phases */
+  totalItems: number;
+  /** Completed items across all phases */
+  completedItems: number;
+  /** Overall completion percentage (0-100) */
+  percentComplete: number;
+  /** Name of the current phase (first with incomplete items) */
+  currentPhase: string;
+  /** Per-phase progress */
+  phases: PhaseProgress[];
+}