holistic 0.2.0

package/docs/handoff-walkthrough.md

@@ -0,0 +1,119 @@
+# Cross-Agent Handoff Walkthrough
+
+This is a practical example of the workflow Holistic is built for.
+
+## Scenario
+
+You start work in one agent, switch tools later, then pick the same project back up from a phone session.
+
+Without Holistic, each session starts with a re-brief.
+
+With Holistic, the repo carries the memory forward.
+
+## The problem in one diagram
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C1 as Cowork
+    participant R as Repo
+    participant A as Antigravity
+    participant M as Mobile Codex
+
+    U->>C1: Start session and fix a bug
+    C1->>R: Write checkpoints and handoff state
+    U->>A: Open repo later in a different tool
+    A->>R: Read HOLISTIC.md, history, regression watch
+    A->>U: Recap current state and ask continue/tweak/new
+    A->>R: Update progress and handoff
+    U->>M: Reopen repo from phone
+    M->>R: Read the same repo memory
+    M->>U: Continue with shared context
+```
+
+## Step-by-step
+
+### 1. Session starts in Cowork
+
+The agent should read:
+
+- `HOLISTIC.md`
+- `.holistic/context/project-history.md`
+- `.holistic/context/regression-watch.md`
+
+Then it should recap:
+
+- the active objective
+- the latest status
+- what has already been tried
+- what should happen next
+
+### 2. Work happens
+
+Mid-session, Holistic should preserve:
+
+- the current goal
+- any attempted fixes
+- important assumptions
+- blockers
+- project impact
+- regression risks
+
+This matters when a future agent touches the same files but does not share the original context window.
+
+### 3. Session ends
+
+At handoff time, the agent should show a summary for review before finalizing it.
+
+That handoff should answer:
+
+| Question | Example |
+| --- | --- |
+| What changed? | Added resume flow state and daemon setup |
+| Why did it change? | To preserve context across agent switches |
+| What still needs attention? | Test sync behavior from a second device |
+| What must not regress? | Do not lose active goal when a new session starts |
+
+### 4. A different agent picks up later
+
+When Antigravity opens the repo, it should not need a fresh brief from scratch.
+
+Its first 30 seconds should look like this:
+
+1. read the Holistic entrypoint
+2. read history and regression memory
+3. recap the last known state
+4. ask whether to continue, tweak, or start something new
+
+## What a good recap sounds like
+
+> Current objective: finish the sync handoff flow.  
+> Latest status: the state branch automation is in place.  
+> Already tried: generated restore and sync helpers for Windows, macOS, and Linux.  
+> Try next: verify the handoff flow from a second device.  
+> Regression watch: do not lose the prior unfinished task when a new session starts.
+
+## What gets better over time
+
+Holistic becomes more valuable the more often the project changes hands.
+
+That long-term archive helps future agents see:
+
+- which fixes were durable
+- which changes created regressions
+- what tradeoffs were already accepted
+- what not to "clean up" without understanding the original reason
+
+## Why this works on mobile too
+
+The portable layer is the repo itself.
+
+A laptop daemon can improve passive capture on that laptop, but the real continuity comes from:
+
+- repo-visible handoff docs
+- long-term project history
+- regression watch memory
+- portable state synced through git
+
+That is why Holistic is cross-agent and cross-platform instead of laptop-bound.
+

package/docs/structured-metadata.md

@@ -0,0 +1,341 @@
+# Structured Metadata Guide
+
+Holistic v1.1+ supports enhanced structured metadata for impact notes and regression risks. This provides richer context for future agents while maintaining backward compatibility with plain text.
+
+## Overview
+
+**Why structured metadata?**
+- **Severity levels** - Quickly identify critical vs. low-priority changes
+- **Area tags** - Filter and search by component (CLI, daemon, docs, etc.)
+- **Outcome tracking** - Know if changes succeeded, partially worked, or failed
+- **Validation checklists** - Concrete steps to verify regression prevention
+- **Session relationships** - Link related work across sessions
+
+## New Types
+
+### Severity
+```typescript
+type Severity = "critical" | "high" | "medium" | "low" | "info";
+```
+
+### Outcome Status
+```typescript
+type OutcomeStatus = "success" | "partial" | "failed" | "ongoing" | "unknown";
+```
+
+### Area Tags
+```typescript
+type AreaTag = 
+  | "cli"           // Command-line interface
+  | "daemon"        // Background daemon/watcher
+  | "state-management" // Session and state handling
+  | "docs"          // Documentation generation
+  | "git-integration"  // Git snapshot and commit handling
+  | "sync"          // Cross-device sync functionality
+  | "adapters"      // Agent-specific adapters
+  | "tests"         // Test infrastructure
+  | "types"         // TypeScript type definitions
+  | "architecture"  // System architecture/design
+  | "ux";           // User experience
+```
+
+## Structured Impact Notes
+
+### Basic Structure
+```typescript
+interface ImpactNote {
+  description: string;           // What changed and why it matters
+  severity?: Severity;           // How important is this change?
+  affectedAreas?: AreaTag[];     // Which components were affected?
+  outcome?: OutcomeStatus;       // Was it successful?
+}
+```
+
+### Example Usage
+
+**Plain text (still supported):**
+```bash
+holistic checkpoint \
+  --impact "Added resume flow state and daemon setup"
+```
+
+**Structured metadata (new):**
+```typescript
+// In code or via JSON input
+{
+  impactsStructured: [
+    {
+      description: "Added resume flow state and daemon setup",
+      severity: "high",
+      affectedAreas: ["cli", "state-management", "daemon"],
+      outcome: "success"
+    }
+  ]
+}
+```
+
+**Rendered output:**
+```markdown
+- Why it mattered:
+- Added resume flow state and daemon setup _[severity: high | areas: cli, state-management, daemon | outcome: success]_
+```
+
+## Structured Regression Risks
+
+### Basic Structure
+```typescript
+interface RegressionRisk {
+  description: string;
+  severity?: Severity;
+  affectedAreas?: AreaTag[];
+  validationChecklist?: ValidationItem[];
+}
+
+interface ValidationItem {
+  description: string;
+  command?: string;
+  expectedOutcome?: string;
+}
+```
+
+### Example Usage
+
+**Plain text (still supported):**
+```bash
+holistic checkpoint \
+  --regression "Do not lose active goal when a new session starts"
+```
+
+**Structured metadata with validation (new):**
+```typescript
+{
+  regressionsStructured: [
+    {
+      description: "Do not lose active goal when a new session starts",
+      severity: "critical",
+      affectedAreas: ["state-management", "cli"],
+      validationChecklist: [
+        {
+          description: "Start a session with a goal",
+          command: "holistic start-new --goal 'Test goal'",
+          expectedOutcome: "Session created with currentGoal set"
+        },
+        {
+          description: "Start another session without ending the first",
+          command: "holistic start-new --goal 'Second goal'",
+          expectedOutcome: "First session preserved in pendingWork with original goal"
+        },
+        {
+          description: "Resume and verify first goal is still accessible",
+          command: "holistic resume --json",
+          expectedOutcome: "JSON shows first goal in pendingWork array"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Rendered output:**
+```markdown
+- Do not regress:
+- Do not lose active goal when a new session starts _[severity: critical | areas: state-management, cli]_
+  - Validation checklist:
+  - Start a session with a goal
+    - Command: `holistic start-new --goal 'Test goal'`
+    - Expected: Session created with currentGoal set
+  - Start another session without ending the first
+    - Command: `holistic start-new --goal 'Second goal'`
+    - Expected: First session preserved in pendingWork with original goal
+  - Resume and verify first goal is still accessible
+    - Command: `holistic resume --json`
+    - Expected: JSON shows first goal in pendingWork array
+```
+
+## Session-Level Metadata
+
+You can also add session-level structured metadata:
+
+```typescript
+interface SessionRecord {
+  // ... existing fields ...
+  
+  // Session-level metadata
+  severity?: Severity;              // Overall session importance
+  outcomeStatus?: OutcomeStatus;    // Did the session achieve its goal?
+  affectedAreas?: AreaTag[];        // Which components did this session touch?
+  relatedSessions?: string[];       // IDs of related/dependent sessions
+}
+```
+
+### Example
+
+```typescript
+{
+  severity: "high",
+  outcomeStatus: "success",
+  affectedAreas: ["daemon", "sync", "state-management"],
+  relatedSessions: [
+    "session-2026-03-19T19-30-32-935Z",
+    "session-2026-03-20T00-04-53-218Z"
+  ]
+}
+```
+
+**Rendered in project-history.md:**
+```markdown
+## Daemon passive capture implementation
+
+- Session: session-2026-03-20T14-22-15-442Z
+- Agent: claude
+- Status: handed_off
+- When: 2026-03-20T16:45:30.123Z
+- Severity: high
+- Outcome: success
+- Affected areas: daemon, sync, state-management
+- Related sessions: session-2026-03-19T19-30-32-935Z, session-2026-03-20T00-04-53-218Z
+- Goal: Implement background file watcher for passive capture
+- Summary: ...
+```
+
+## Backward Compatibility
+
+**Important:** The legacy string arrays (`impactNotes`, `regressionRisks`) are maintained for backward compatibility:
+
+```typescript
+interface SessionRecord {
+  // Legacy - always populated from CLI string inputs
+  impactNotes: string[];
+  regressionRisks: string[];
+  
+  // New - optional structured versions
+  impactNotesStructured?: ImpactNote[];
+  regressionRisksStructured?: RegressionRisk[];
+}
+```
+
+- If only plain text is provided, it goes into the legacy arrays
+- If structured metadata is provided, it uses the new fields
+- The rendering logic prefers structured metadata when available, falls back to plain text
+- Existing sessions with plain text continue to work exactly as before
+
+## CLI Integration (Future)
+
+Currently, structured metadata is accessible via TypeScript/JSON. Future CLI enhancements could include:
+
+```bash
+# Add structured impact with inline metadata
+holistic checkpoint \
+  --impact-structured "Added daemon watch mode" \
+  --impact-severity high \
+  --impact-areas daemon,cli \
+  --impact-outcome success
+
+# Add regression with validation checklist
+holistic checkpoint \
+  --regression-structured "Daemon must auto-restart after crash" \
+  --regression-severity critical \
+  --regression-areas daemon \
+  --regression-validate "ps aux | grep holistic-daemon" \
+  --regression-validate-expect "One daemon process running"
+```
+
+## Benefits
+
+### For Agents
+- **Faster context recovery** - Scan by severity and area instead of reading everything
+- **Better decision making** - Know outcome status before attempting similar work
+- **Concrete validation** - Run checklist commands to verify regression prevention
+
+### For Teams
+- **Searchability** - `holistic history --search --areas daemon --severity critical`
+- **Metrics** - Track success rates, identify problematic areas
+- **Documentation** - Validation checklists become living test specs
+
+### For Long-Term Memory
+- **Rich filters** - "Show all critical regressions affecting state-management"
+- **Impact analysis** - "What succeeded vs. what's still ongoing?"
+- **Dependency tracking** - "Which sessions are related to this fix?"
+
+## Migration Strategy
+
+You don't need to migrate existing sessions. The system handles both formats:
+
+1. **Leave existing sessions as-is** - They'll continue using plain text rendering
+2. **Use structured metadata for new critical work** - Especially for:
+   - Critical bug fixes that must not regress
+   - Complex multi-session features
+   - Changes affecting core architecture
+3. **Add validation checklists** when you fix something another agent might break later
+
+## Example: Real-World Structured Handoff
+
+```typescript
+// Hypothetical handoff for implementing portable state sync
+{
+  summary: "Implemented cross-device state sync via dedicated portable state ref",
+  severity: "high",
+  outcomeStatus: "success",
+  affectedAreas: ["sync", "git-integration", "daemon"],
+  relatedSessions: ["session-2026-03-19T19-30-32-935Z"], // Original sync planning session
+  
+  impactsStructured: [
+    {
+      description: "Portable state now syncs through refs/holistic/state",
+      severity: "high",
+      affectedAreas: ["sync", "git-integration"],
+      outcome: "success"
+    },
+    {
+      description: "Restore scripts can now pull remote state on new devices",
+      severity: "medium",
+      affectedAreas: ["sync", "cli"],
+      outcome: "success"
+    }
+  ],
+  
+  regressionsStructured: [
+    {
+      description: "Portable state ref must stay isolated from the main working branch history",
+      severity: "critical",
+      affectedAreas: ["sync", "git-integration"],
+      validationChecklist: [
+        {
+          description: "Verify the remote portable state ref exists",
+          command: "git ls-remote origin refs/holistic/state",
+          expectedOutcome: "A ref named refs/holistic/state is present on the remote"
+        },
+        {
+          description: "Verify restore script fetches the portable state ref explicitly",
+          command: "grep -n 'refs/holistic/state' .holistic/system/restore-state.sh",
+          expectedOutcome: "Restore helper references refs/holistic/state directly"
+        }
+      ]
+    },
+    {
+      description: "Sync must handle concurrent updates from multiple devices",
+      severity: "high",
+      affectedAreas: ["sync", "state-management"],
+      validationChecklist: [
+        {
+          description: "Create handoff on device A",
+          command: "holistic handoff && ./.holistic/system/sync-state.sh",
+          expectedOutcome: "Portable state ref updated with device A handoff"
+        },
+        {
+          description: "Create different handoff on device B before pulling A",
+          command: "holistic handoff",
+          expectedOutcome: "Local portable state has device B handoff"
+        },
+        {
+          description: "Pull and verify both handoffs are preserved",
+          command: ".holistic/system/restore-state.sh && cat .holistic/state.json",
+          expectedOutcome: "Either both handoffs merged or user prompted for conflict resolution"
+        }
+      ]
+    }
+  ]
+}
+```
+
+This creates rich, searchable, verifiable project memory that travels with the repo.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "holistic",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Repo memory, MCP handoffs, and session continuity for AI coding agents",
+  "keywords": [
+    "ai",
+    "ai-agents",
+    "coding-assistant",
+    "developer-tools",
+    "cli",
+    "mcp",
+    "repo-memory",
+    "agent-handoff",
+    "session-continuity",
+    "context-management",
+    "context-preservation",
+    "claude",
+    "codex",
+    "cursor",
+    "copilot",
+    "gemini",
+    "multi-agent"
+  ],
+  "author": "lweis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lweiss01/holistic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lweiss01/holistic/issues"
+  },
+  "homepage": "https://github.com/lweiss01/holistic#readme",
+  "type": "module",
+  "bin": "bin/holistic.js",
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "clean": "node scripts/clean.mjs",
+    "prepublishOnly": "npm run clean && npm run build && npm test",
+    "holistic": "node --experimental-strip-types ./src/cli.ts",
+    "daemon": "node --experimental-strip-types ./src/daemon.ts",
+    "release:check": "node scripts/release-check.mjs",
+    "test": "node --experimental-strip-types ./tests/run-tests.ts",
+    "test:smoke": "node scripts/smoke-test.mjs"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "docs/handoff-walkthrough.md",
+    "docs/structured-metadata.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  }
+}