@pi-unipi/milestone 2.4.0 → 2.5.0

package/README.md

@@ -15,9 +15,17 @@ Workflow operates at the task level — brainstorm, plan, work, review. Project
 
 ### Session Start
 
-On `before_agent_start`, milestone reads `.unipi/docs/MILESTONES.md` and appends a progress summary to the system prompt:
+On `before_agent_start`, milestone reads `.unipi/docs/MILESTONES.md` from `ctx.cwd` and appends a hidden `unipi-milestone-snapshot` custom message to the session:
 
 ```
+# UniPi Milestone Snapshot
+
+This snapshot supersedes all prior UniPi milestone snapshots; use only this snapshot for milestone status.
+
+Workspace: /path/to/project
+
+Status: active
+
 ## Project Milestones
 Overall progress: 5/10 items (50%)
   Phase 1: Foundation: 3/5 done
@@ -25,11 +33,11 @@ Overall progress: 5/10 items (50%)
 Current focus: Phase 1: Foundation
 ```
 
-If MILESTONES.md doesn't exist, no context is injected.
+Snapshots are append-only and hidden from the transcript. They keep the system-prompt prefix stable, persist milestone context in session history, and are deduplicated against the latest milestone custom message in the effective (compaction-aware) LLM context. If milestones disappear while an older active snapshot remains effective, an inactive snapshot is appended to supersede it. A clean workspace with no milestones and no effective snapshot receives no injected message.
 
 ### Session End
 
-On `session_shutdown`, milestone scans workflow docs modified during the session. Detects items that changed from `- [ ]` to `- [x]` and auto-updates MILESTONES.md using exact text matching.
+On `session_shutdown`, milestone scans workflow docs modified during the session. It uses the workspace captured from `session_start`'s `ctx.cwd`, detects items that changed from `- [ ]` to `- [x]`, and auto-updates MILESTONES.md using exact text matching.
 
 ### Coexist Triggers
 

package/hooks.ts

@@ -1,22 +1,33 @@
 /**
  * @pi-unipi/milestone — Lifecycle hooks
  *
- * Session start: inject milestone progress as system context.
+ * Agent start: append milestone progress as a hidden, persistent context snapshot.
  * 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 "@earendil-works/pi-coding-agent";
-import { MILESTONE_DIRS, safeMtimeMs, tryRead } from "@pi-unipi/core";
-import { parseMilestones, getProgressSummary, updateItemStatus } from "./milestone.js";
+import {
+  buildSessionContext,
+  type ExtensionAPI,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { MILESTONE_DIRS, UNIPI_EVENTS, safeMtimeMs, tryRead } from "@pi-unipi/core";
+import { getProgressSummary, updateItemStatus } from "./milestone.js";
 
-/** Track when the session started for diffing modified files */
-let sessionStartMs = 0;
+export const MILESTONE_SNAPSHOT_TYPE = "unipi-milestone-snapshot";
 
-/**
- * Format a progress summary as a context string for the system prompt.
- */
+interface MilestoneSnapshotDetails {
+  active: boolean;
+  workspace: string;
+}
+
+interface EffectiveSnapshot {
+  content: unknown;
+  details?: MilestoneSnapshotDetails;
+}
+
+/** Format the active milestone progress included in a snapshot. */
 function formatMilestoneContext(filePath: string): string | null {
   const summary = getProgressSummary(filePath);
   if (summary.totalItems === 0) return null;
@@ -39,23 +50,84 @@ function formatMilestoneContext(filePath: string): string | null {
     .join("\n");
 }
 
+/** Build an append-only snapshot that explicitly invalidates earlier snapshots. */
+function formatMilestoneSnapshot(workspace: string, context: string | null): string {
+  return [
+    "# UniPi Milestone Snapshot",
+    "This snapshot supersedes all prior UniPi milestone snapshots; use only this snapshot for milestone status.",
+    `Workspace: ${workspace}`,
+    `Status: ${context ? "active" : "inactive"}`,
+    context ?? "No milestones are active for this workspace.",
+  ].join("\n\n");
+}
+
+function latestEffectiveSnapshot(branch: SessionEntry[]): EffectiveSnapshot | undefined {
+  const messages = buildSessionContext(branch).messages;
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message.role === "custom" && message.customType === MILESTONE_SNAPSHOT_TYPE) {
+      return {
+        content: message.content,
+        details: message.details as MilestoneSnapshotDetails | undefined,
+      };
+    }
+  }
+  return undefined;
+}
+
+/** Find state that may have been folded into a compaction summary. */
+function latestHistoricalSnapshot(branch: SessionEntry[]): EffectiveSnapshot | undefined {
+  for (let index = branch.length - 1; index >= 0; index--) {
+    const entry = branch[index];
+    if (entry.type === "custom_message" && entry.customType === MILESTONE_SNAPSHOT_TYPE) {
+      return {
+        content: entry.content,
+        details: entry.details as MilestoneSnapshotDetails | undefined,
+      };
+    }
+  }
+  return undefined;
+}
+
+function isActiveSnapshot(snapshot: EffectiveSnapshot): boolean {
+  if (typeof snapshot.details?.active === "boolean") return snapshot.details.active;
+  return typeof snapshot.content === "string" && snapshot.content.includes("Status: active");
+}
+
 /**
- * Register session start hook — injects milestone progress into system context.
+ * Register the agent-start hook. Snapshots are hidden from the transcript but
+ * persist in the append-only session and therefore keep the system prefix stable.
  */
 export function registerSessionStartHook(pi: ExtensionAPI): void {
-  pi.on("before_agent_start", (event) => {
-    sessionStartMs = Date.now();
+  pi.on("before_agent_start", (_event, ctx) => {
+    const workspace = ctx.cwd;
+    const milestonesPath = path.join(workspace, MILESTONE_DIRS.MILESTONES);
+    const context = formatMilestoneContext(milestonesPath);
+    const branch = ctx.sessionManager.getBranch();
+    const latest = latestEffectiveSnapshot(branch);
+    const historical = latestHistoricalSnapshot(branch);
 
-    const cwd = process.cwd();
-    const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+    // A genuinely clean workspace/session needs no synthetic context. Raw
+    // history is checked because compaction may have folded an old active
+    // snapshot into summary prose while removing its custom-message identity.
+    if (!context && !latest && !historical) return undefined;
 
-    const context = formatMilestoneContext(milestonesPath);
-    if (!context) return undefined;
+    const prior = latest ?? historical;
+    if (!context && prior && !isActiveSnapshot(prior)) return undefined;
+
+    const content = formatMilestoneSnapshot(workspace, context);
+    if (latest?.content === content) return undefined;
 
-    // Append milestone context to the system prompt
-    const currentPrompt = (event as any).systemPrompt ?? "";
     return {
-      systemPrompt: currentPrompt + "\n\n" + context,
+      message: {
+        customType: MILESTONE_SNAPSHOT_TYPE,
+        content,
+        display: false,
+        details: {
+          active: context !== null,
+          workspace,
+        } satisfies MilestoneSnapshotDetails,
+      },
     };
   });
 }
@@ -140,19 +212,21 @@ function scanModifiedDocs(dirs: string[], since: number): string[] {
  * scans modified docs, and auto-updates MILESTONES.md.
  */
 export function registerSessionEndHook(pi: ExtensionAPI): void {
-  // Store baseline snapshots at session start
+  // Capture the session workspace because process.cwd() can change before shutdown.
   const baselineSnapshots = new Map<string, string>();
+  let sessionStartMs = 0;
+  let sessionWorkspace: string | null = null;
 
   // Capture baselines on session start
-  pi.on("session_start", () => {
+  pi.on("session_start", (_event, ctx) => {
     sessionStartMs = Date.now();
+    sessionWorkspace = ctx.cwd;
     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"),
+      path.join(sessionWorkspace, ".unipi/docs/specs"),
+      path.join(sessionWorkspace, ".unipi/docs/plans"),
+      path.join(sessionWorkspace, ".unipi/docs/quick-work"),
     ];
 
     for (const dir of scanDirs) {
@@ -167,28 +241,16 @@ export function registerSessionEndHook(pi: ExtensionAPI): void {
     }
   });
 
-  // 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);
+  const syncModifiedDocs = () => {
+    if (!sessionWorkspace) return;
 
+    const milestonesPath = path.join(sessionWorkspace, 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"),
+      path.join(sessionWorkspace, ".unipi/docs/specs"),
+      path.join(sessionWorkspace, ".unipi/docs/plans"),
+      path.join(sessionWorkspace, ".unipi/docs/quick-work"),
     ];
 
     const modifiedFiles = scanModifiedDocs(scanDirs, sessionStartMs);
@@ -204,5 +266,11 @@ export function registerSessionEndHook(pi: ExtensionAPI): void {
         updateItemStatus(milestonesPath, phase, text, true);
       }
     }
-  });
+  };
+
+  // Workflow emits this once its follow-up agent loop drains.
+  pi.events.on(UNIPI_EVENTS.WORKFLOW_END, syncModifiedDocs);
+
+  // Final fallback for changes made outside a workflow or before event wiring.
+  pi.on("session_shutdown", syncModifiedDocs);
 }

package/index.ts

@@ -2,7 +2,7 @@
  * @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.
+ * appends hidden context snapshots before agent turns, and auto-syncs on session end.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@pi-unipi/milestone",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Lifecycle layer for project-level goals — MILESTONES.md tracking, session hooks, auto-sync",
   "type": "module",
   "main": "index.ts",
+  "scripts": {
+    "test": "npx tsx --test tests/hooks.test.ts"
+  },
   "license": "MIT",
   "author": "Neuron Mr White",
   "repository": {
@@ -29,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.4.0"
+    "@pi-unipi/core": "2.5.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/coexist.ts

@@ -1,114 +0,0 @@
-/**
- * @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) {
-    // Removed console.log — milestone matches are informational.
-    // Use /unipi:milestone-update to sync manually.
-  }
-}
-
-/**
- * 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) {
-    // Removed console.log — plan-milestone matches are informational.
-  }
-}
-
-/**
- * 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;
-
-  // Removed console.log — milestone auto-sync is silent.
-}