aiwcli 0.12.2 → 0.12.6

package/dist/templates/_shared/handoff-system/CLAUDE.md

@@ -0,0 +1,421 @@
+# Handoff System
+
+Comprehensive specification for the handoff workflow system.
+
+## Overview
+
+- **Purpose:** Capture session state for asynchronous handoff to next session
+- **Philosophy:** Structured sections (dead-ends, pending, decisions, etc.) + executable restoration
+- **When to use:** End of work session when context needs preservation
+- **Runtime location:** `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
+
+## Directory Structure
+
+```
+handoff-system/
+├── CLAUDE.md           # This file — comprehensive spec
+├── lib/                # Reusable modules
+│   ├── handoff-reader.ts       # Read and parse handoff sections
+│   └── document-generator.ts   # Generate handoff markdown (not currently imported)
+├── scripts/            # CLI entry points
+│   ├── save_handoff.ts         # Create handoff from stdin markdown
+│   └── resume_handoff.ts       # Load handoff and format for restoration
+└── workflows/          # Procedural documentation
+    ├── handoff.md              # Creation workflow
+    └── handoff-resume.md       # Restoration workflow
+```
+
+## Data Model & Schema
+
+### Handoff Folder Structure
+
+Runtime location: `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
+
+**Files created:**
+- `index.md` — Entry point with frontmatter
+- `completed-work.md` — What was accomplished
+- `dead-ends.md` — Failed approaches to avoid
+- `decisions.md` — Key decisions made
+- `pending.md` — Incomplete work items
+- `context.md` — Background context
+- `plan.md` — Optional, copied from context if plan exists
+
+### HandoffSections Interface
+
+```typescript
+// From _shared/lib-ts/types.ts
+interface HandoffSections {
+  index: string;           // Entry point with frontmatter
+  deadEnds: string | null; // Failed approaches to avoid
+  pending: string | null;  // Incomplete work items
+  plan: string | null;     // Copy of plan file if exists
+  decisions: string | null; // Key decisions made
+  completedWork: string | null; // What was accomplished
+  context: string | null;  // Background context
+}
+```
+
+**Why inline interfaces:** Makes CLAUDE.md self-contained — agents don't jump between files.
+
+### Section Markers
+
+Content parsed via HTML comments: `<!-- SECTION: name -->`
+
+**Valid section names:**
+- `CONTEXT`
+- `COMPLETED_WORK`
+- `DEAD_ENDS`
+- `DECISIONS`
+- `PENDING`
+- `PLAN`
+
+**Critical:** Markers must be HTML comments, not markdown headings. Parser searches for `<!-- SECTION: -->` format.
+
+### Frontmatter Schema
+
+YAML frontmatter in index.md:
+
+```yaml
+---
+title: Handoff - {project_name}
+date: {ISO timestamp}
+session_id: {Claude session ID}
+project: {context directory name}
+plan_document: {path to plan file if exists}
+---
+```
+
+## Lifecycle & Hook Integration
+
+### Creation Flow (save_handoff.ts script)
+
+**Trigger:** `/handoff` command invokes script with stdin markdown
+
+**Process:**
+1. Parse frontmatter and section markers from stdin
+2. Resolve context ID (5-tier resolution: `--context-id`, `--session-id`, frontmatter, `CLAUDE_SESSION_ID`, fallback to active)
+3. Create timestamped folder: `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
+4. Shard content into section files
+5. Update state.json with handoff metadata
+
+**State updates:**
+- `handoff_path`: Set to `handoffs/{timestamp}/index.md` (relative to context folder)
+- `work_consumed`: Set to `false` (enables staging)
+- `next_artifact_type`: Set to `"handoff"` (explicit artifact tracking)
+- **Latest-wins replacement:** If `plan_hash` exists, clear plan fields (`plan_path`, `plan_hash`, `plan_signature`)
+
+**Context resolution tiers** (first match wins):
+1. `--context-id` CLI arg
+2. `--session-id` CLI arg (lookup via CLAUDE_SESSION_ID → context)
+3. `session_id` in frontmatter (lookup via session → context)
+4. `CLAUDE_SESSION_ID` env var (lookup via session → context)
+5. Fallback: most recent active context
+
+### Staging (session_end.ts hook)
+
+**Trigger:** SessionEnd event
+
+**Condition for staging:**
+```typescript
+if (state.handoff_path && !state.work_consumed) {
+  state.mode = "has_staged_work";
+  state.next_artifact_type = "handoff";
+}
+```
+
+**Latest-wins detection:**
+If `plan_hash` differs from `plan_hash_consumed`, new plan detected:
+- Clear `handoff_path` (plan wins)
+- Set `work_consumed = false`
+- Set `next_artifact_type = "plan"`
+
+**Unified staging mode:** `has_staged_work` replaces old `has_plan` and `has_handoff` modes (v0.13.0+).
+
+### Restoration (session_start.ts hook)
+
+**Trigger:** SessionStart event with `source = "clear"`
+
+**Process:**
+1. Find context with `mode = "has_staged_work"`
+2. Dispatch by `next_artifact_type`:
+   - If `"handoff"`: call `formatHandoffContinuation(ctx)`
+   - If `"plan"`: inject plan content
+3. Bind session to context
+4. Transition `has_staged_work` → `active`
+5. Set `work_consumed = true` (one-shot latch prevents re-staging)
+
+**formatHandoffContinuation()** (from context-formatter.ts):
+- Reads handoff sections via `readHandoffSections()`
+- Assembles restoration context: dead-ends → pending → plan remaining → decisions → git delta → completed work
+- Injects as system-reminder for Claude
+
+### Fallback Matching (user_prompt_submit.ts hook)
+
+**Trigger:** UserPromptSubmit when no staged work mode detected
+
+**Process in determineContext():**
+1. Filter contexts by `has_staged_work` mode
+2. Separate by `determineArtifactType()`:
+   - Plan artifacts: check `plan_hash` and `plan_path`
+   - Handoff artifacts: check `handoff_path`
+3. Try plan match first (content-based via plan hash)
+4. Fall back to handoff match (first-match by recency)
+5. Set `work_consumed = true` if match found
+
+**determineArtifactType() utility:**
+- Checks `next_artifact_type` field first (authoritative)
+- Fallback: field detection (`plan_hash` + `plan_path` vs `handoff_path`)
+- Logs warning if both plan and handoff fields exist (bug - violates latest-wins)
+
+## Scripts
+
+### save_handoff.ts
+
+**Usage:**
+```bash
+bun .aiwcli/_shared/handoff-system/scripts/save_handoff.ts [--context-id ID] [--session-id SID] < handoff.md
+```
+
+**Stdin format:**
+```markdown
+---
+title: Handoff - Project Name
+session_id: abc123
+---
+
+# Handoff Document
+
+<!-- SECTION: CONTEXT -->
+Context details here...
+
+<!-- SECTION: PENDING -->
+Pending items...
+```
+
+**Output:**
+- Creates folder: `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
+- Shards to files: `index.md`, `pending.md`, `dead-ends.md`, etc.
+- Updates `state.json`: `handoff_path`, `work_consumed=false`, `next_artifact_type="handoff"`
+
+**Collision handling:**
+If timestamp folder exists, appends `-2`, `-3`, etc.
+
+**State updates (latest-wins):**
+- Sets handoff fields
+- **Clears plan fields if they exist** (`plan_path`, `plan_hash`, `plan_signature` → null)
+
+### resume_handoff.ts
+
+**Usage:**
+```bash
+# Auto-discover from current session
+bun .aiwcli/_shared/handoff-system/scripts/resume_handoff.ts
+
+# Explicit handoff path
+bun .aiwcli/_shared/handoff-system/scripts/resume_handoff.ts path/to/handoff/index.md
+
+# Explicit context
+bun .aiwcli/_shared/handoff-system/scripts/resume_handoff.ts --context context-id
+```
+
+**Output format (to stdout):**
+```markdown
+# Handoff Restoration
+
+## Dead Ends (Priority: Address First)
+...
+
+## Pending Items
+...
+
+## Plan Status
+42% complete (5/12 tasks)
+
+## Decisions Made
+...
+
+## Git Delta
+Changed files since handoff...
+
+## Completed Work
+...
+
+## Full Plan (Appendix)
+...
+```
+
+**Features:**
+- **Staleness warnings:** If handoff > 7 days old, warns in output
+- **Plan progress:** Calculates % complete from plan anchors
+- **Git delta:** Compares current git state to plan's git anchors
+- **Priority ordering:** Dead-ends first, then pending, then context
+
+**Auto-discovery:**
+Uses `CLAUDE_SESSION_ID` env var → lookup context → find latest handoff in `handoffs/` folder.
+
+## Library Modules
+
+### handoff-reader.ts
+
+**Location:** `_shared/handoff-system/lib/handoff-reader.ts`
+
+**Exports:**
+
+```typescript
+// Find most recent handoff in context
+function findLatestHandoff(contextPath: string): string | null
+
+// Read and parse handoff sections
+function readHandoffSections(handoffPath: string): HandoffSections
+
+// Extract timestamp from handoff path
+function getHandoffTimestamp(handoffPath: string): Date | null
+
+// Get plan reference from handoff frontmatter
+function getHandoffPlanReference(handoffPath: string): string | null
+```
+
+**Section mapping:**
+```typescript
+const SECTION_FILES = {
+  index: "index.md",
+  deadEnds: "dead-ends.md",
+  pending: "pending.md",
+  plan: "plan.md",
+  decisions: "decisions.md",
+  completedWork: "completed-work.md",
+  context: "context.md",
+};
+```
+
+**Returns null for missing optional sections** (dead-ends, pending, etc.).
+
+### document-generator.ts
+
+**Location:** `_shared/handoff-system/lib/document-generator.ts`
+
+**Exports:**
+
+```typescript
+// Generate complete handoff markdown with sections
+function generateHandoffDocument(options: HandoffOptions): string
+
+// Section builders
+function buildContextSection(ctx: ContextState): string
+function buildCompletedWorkSection(history: WorkHistory): string
+function buildDeadEndsSection(deadEnds: DeadEnd[]): string
+// ... (other section builders)
+```
+
+**Used by:** `/handoff` workflow to programmatically generate handoff content before piping to `save_handoff.ts`.
+
+**Note:** Currently not imported by any files. Moved here for logical grouping and completeness.
+
+## Command Integration
+
+**Thin pointer pattern:**
+
+`.claude/commands/handoff.md` (user-facing, discoverable via `/`)
+→ References `.aiwcli/_shared/handoff-system/workflows/handoff.md` (detailed procedural steps)
+
+**Benefits:**
+- Command files stay concise (easy to scan in `/` menu)
+- Workflow files can expand without bloating command discovery
+- Single source of truth for procedural details
+
+**Example reference format:**
+```markdown
+See `.aiwcli/_shared/handoff-system/workflows/handoff.md` for complete process documentation.
+```
+
+## Testing
+
+**Integration test:**
+`_shared/lib-ts/__tests__/integration/handoff-lifecycle.test.ts`
+
+**Coverage:**
+- Creation: active + handoff → session_end → has_staged_work
+- Restoration: /clear → session_start → active + work_consumed=true
+- One-shot latch: subsequent session_end does NOT re-stage (work_consumed=true)
+
+**Hook execution test:**
+```bash
+echo '{"hook_event_name":"SessionStart","session_id":"test","source":"clear"}' | \
+  bun .aiwcli/_shared/hooks-ts/session_start.ts
+```
+
+Expected: No import errors, clean execution.
+
+## Migration Notes (v0.13.0+)
+
+**Unified lifecycle:**
+- Old modes `has_plan` and `has_handoff` → unified `has_staged_work`
+- Old flags `plan_consumed` and `handoff_consumed` → unified `work_consumed`
+- New field `next_artifact_type` (`"plan" | "handoff" | null`) for explicit artifact tracking
+
+**Migration handled by migrateConsumedFlags()** in `state-io.ts`:
+- Runs on every `state.json` read
+- Transparently converts old modes to new structure
+- Idempotent (safe to run multiple times)
+
+**Latest-wins principle:**
+- Only ONE artifact staged at a time
+- New handoff clears plan fields
+- New plan clears handoff_path
+- Most recent creation wins
+
+**Work consumed as one-shot latch:**
+- Set to `true` when `has_staged_work` → `active` transition occurs
+- Prevents `session_end` from re-staging same artifact
+- Reset to `false` when new artifact created
+
+## Architecture Decisions
+
+**Why folder sharding (not single file)?**
+- Enables selective loading (resume script loads only needed sections)
+- Allows future extensions (e.g., attachments, screenshots)
+- Chronological discovery via timestamp folders
+
+**Why section markers (not frontmatter)?**
+- Flexible content generation (Claude outputs sections in natural flow)
+- No strict ordering required (script extracts by marker)
+- Easy to extend (add new sections without schema version bump)
+
+**Why latest-wins (not dual artifact tracking)?**
+- Simplifies state machine (one artifact, one mode transition)
+- Prevents ambiguity (which artifact to restore?)
+- Matches user mental model (most recent work is relevant)
+
+**Why unified work_consumed flag?**
+- Prevents infinite re-staging loop
+- Simpler than per-artifact flags (plan_consumed, handoff_consumed)
+- One-shot latch pattern is well-understood
+
+## Gotchas
+
+**Template sync is mandatory:**
+Both `.aiwcli/_shared/handoff-system/` (working copy) and `packages/cli/src/templates/_shared/handoff-system/` (template source) must stay in sync per CLAUDE.md template sync rules.
+
+**Import paths after move:**
+- From `scripts/resume_handoff.ts` → `lib/handoff-reader.ts`: `../lib/handoff-reader.js`
+- From `lib/handoff-reader.ts` → `lib-ts/base/constants.ts`: `../../lib-ts/base/constants.js`
+
+**Hooks don't import handoff-reader:**
+- `session_start.ts` uses `formatHandoffContinuation()` from `context-formatter.ts`
+- `context-formatter.ts` reads `ctx.handoff_path` directly
+- No direct handoff-reader dependency in hooks
+
+**Command file script paths are absolute:**
+- Reference from project root: `.aiwcli/_shared/handoff-system/scripts/save_handoff.ts`
+- NOT relative to command file location
+
+**Section markers must be HTML comments:**
+```markdown
+<!-- SECTION: PENDING -->  ✅ Correct
+# SECTION: PENDING        ❌ Incorrect (parsed as heading, not marker)
+```
+
+**Windsurf and Codex workflows also reference scripts:**
+When updating script paths, check:
+- `packages/cli/src/templates/_shared/.windsurf/workflows/handoff.md`
+- `packages/cli/src/templates/_shared/.codex/workflows/handoff.md`

package/dist/templates/_shared/{lib-ts/handoff → handoff-system/lib}/document-generator.ts

@@ -6,18 +6,17 @@
  * work to a new session (typically due to context window limits).
  */
 
-import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-
+import * as crypto from "node:crypto";
+import { getContextHandoffsDir, getContextDir } from "../base/constants.js";
 import { atomicWrite } from "../base/atomic-write.js";
-import { getContextDir, getContextHandoffsDir } from "../base/constants.js";
-import { logError, logInfo } from "../base/logger.js";
+import { logInfo, logError } from "../base/logger.js";
 import { nowIso } from "../base/utils.js";
-import { getContext, saveState as _saveState } from "../context/context-store.js";
+import { getContext, saveState } from "../context/context-store.js";
 import { getTasks } from "../context/task-tracker.js";
-import { formatContinuationHeader, formatReason, renderTaskList } from "../templates/formatters.js";
-import type { HandoffDocument, Task as _Task } from "../types.js";
+import { renderTaskList, formatContinuationHeader, formatReason } from "../templates/formatters.js";
+import type { HandoffDocument, Task } from "../types.js";
 
 /**
  * Generate and save a handoff document for a context.
@@ -125,7 +124,8 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
   );
 
   // Active tasks
-  lines.push(renderTaskList(doc.active_tasks, "Active Tasks", true).trimEnd(), "");
+  lines.push(renderTaskList(doc.active_tasks, "Active Tasks", true).trimEnd());
+  lines.push("");
 
   // Completed this session
   if (doc.completed_tasks_this_session.length > 0) {
@@ -133,7 +133,8 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
       doc.completed_tasks_this_session as any[],
       "Completed This Session",
       false,
-    ).trimEnd(), "");
+    ).trimEnd());
+    lines.push("");
   }
 
   // Work summary
@@ -147,7 +148,6 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
     for (let i = 0; i < doc.next_steps.length; i++) {
       lines.push(`${i + 1}. ${doc.next_steps[i]}`);
     }
-
     lines.push("");
   }
 
@@ -157,7 +157,6 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
     for (const note of doc.important_notes) {
       lines.push(`- ${note}`);
     }
-
     lines.push("");
   }
 

package/dist/templates/_shared/{lib-ts/handoff → handoff-system/lib}/handoff-reader.ts

@@ -7,11 +7,10 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { getContextHandoffsDir } from "../base/constants.js";
-import { getContext } from "../context/context-store.js";
-import type { HandoffSections } from "../types.js";
+import * as path from "node:path";
+import { getContextHandoffsDir } from "../../lib-ts/base/constants.js";
+import { getContext } from "../../lib-ts/context/context-store.js";
+import type { HandoffSections } from "../../lib-ts/types.js";
 
 /**
  * Find the most recent handoff folder for a context.
@@ -30,7 +29,7 @@ export function findLatestHandoff(contextId: string, projectRoot?: string): stri
       .sort();
 
     if (entries.length === 0) return null;
-    return path.join(handoffsDir, entries.at(-1)!);
+    return path.join(handoffsDir, entries[entries.length - 1]!);
   } catch {
     return null;
   }

package/dist/templates/_shared/{scripts → handoff-system/scripts}/resume_handoff.ts

@@ -4,8 +4,8 @@
  * a structured briefing to stdout.
  *
  * Usage:
- *   bun .aiwcli/_shared/scripts/resume_handoff.ts <handoff_folder_or_index>
- *   bun .aiwcli/_shared/scripts/resume_handoff.ts --context <context_id>
+ *   bun .aiwcli/_shared/handoff-system/scripts/resume_handoff.ts <handoff_folder_or_index>
+ *   bun .aiwcli/_shared/handoff-system/scripts/resume_handoff.ts --context <context_id>
  *
  * If no args, auto-discovers the active context and finds the latest handoff.
  *
@@ -15,16 +15,16 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import { getProjectRoot } from "../lib-ts/base/constants.js";
-import { getGitStatusShort } from "../lib-ts/base/git-state.js";
-import { eprint } from "../lib-ts/base/utils.js";
-import { findActiveContextId } from "../lib-ts/context/context-store.js";
 import {
   findLatestHandoff,
   readHandoffSections,
   getHandoffTimestamp,
   getHandoffPlanReference,
-} from "../lib-ts/handoff/handoff-reader.js";
+} from "../lib/handoff-reader.js";
+import { getProjectRoot } from "../../lib-ts/base/constants.js";
+import { getContextBySessionId } from "../../lib-ts/context/context-store.js";
+import { getGitStatusShort } from "../../lib-ts/base/git-state.js";
+import { eprint } from "../../lib-ts/base/utils.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -117,19 +117,22 @@ function resolveHandoffFolder(args: string[]): [string, string | null] {
     return [target, null];
   }
 
-  // Auto-discover active context
-  const discoveredId = findActiveContextId(projectRoot);
-  if (discoveredId) {
-    const folder = findLatestHandoff(discoveredId, projectRoot);
-    if (!folder) {
-      eprint(`No handoff folders found for context: ${discoveredId} (auto-discovered)`);
-      process.exit(1);
+  // Auto-discover via session ID (when running from Claude Code)
+  const sessionId = process.env.CLAUDE_SESSION_ID;
+  if (sessionId) {
+    const context = getContextBySessionId(sessionId, projectRoot);
+    if (context) {
+      const folder = findLatestHandoff(context.id, projectRoot);
+      if (!folder) {
+        eprint(`No handoff folders found for context: ${context.id} (from session ${sessionId})`);
+        process.exit(1);
+      }
+      return [folder, context.id];
     }
-    return [folder, discoveredId];
   }
 
   eprint(
-    "No active context found.\n\n" +
+    "No context found for current session.\n\n" +
     "Usage: bun resume_handoff.ts <handoff_folder_or_index>\n" +
     "       bun resume_handoff.ts --context <context_id>",
   );