cclaw-cli 0.5.16 → 0.6.0

package/dist/content/examples.js

@@ -1,16 +1,16 @@
 const STAGE_EXAMPLES = {
-    brainstorm: `### Context
+    brainstorm: `## Context
 
 - **Project state:** Monorepo with CI pipeline using custom release scripts. Release checks are scattered across shell scripts with no shared validation logic.
 - **Relevant existing code/patterns:** \`scripts/pre-publish.sh\` does metadata checks. \`src/release/\` has partial validation helpers.
 
-### Problem
+## Problem
 
 - **What we're solving:** release checks are fragile and inconsistent between CI and local runs. Invalid metadata sometimes reaches npm publish.
 - **Success criteria:** invalid release preconditions are caught before publish with explicit operator feedback, in both CI and local workflows.
 - **Constraints:** no new runtime dependencies; must work within existing CI pipeline structure.
 
-### Clarifying Questions
+## Clarifying Questions
 
 | # | Question | Answer | Decision impact |
 | --- | --- | --- | --- |
@@ -18,7 +18,7 @@ const STAGE_EXAMPLES = {
 | 2 | Should the validation logic live in a reusable module or stay as shell scripts? | Reusable module. | Architecture: shared TypeScript module imported by CI and local tooling, not duplicated shell scripts. |
 | 3 | For v1, prioritize rapid delivery or maximum configurability? | Rapid delivery. | Minimal deterministic validation surface; defer plugin/config system to v2. |
 
-### Approaches
+## Approaches
 
 | Approach | Architecture | Trade-offs | Recommendation |
 | --- | --- | --- | --- |
@@ -26,33 +26,33 @@ const STAGE_EXAMPLES = {
 | B: Hardened shell scripts | Keep existing script approach, add stricter checks and error messages. | Lowest effort. Weak reuse, CI/local divergence risk grows over time. | Viable fallback if TS module is blocked. |
 | C: Full release framework | New release orchestrator with plugin system, config files, rollback commands. | Maximum flexibility. High risk, delivery delay, over-engineered for current needs. | Not recommended for v1. |
 
-### Selected Direction
+## Selected Direction
 
 - **Approach:** A — Reusable validation module
 - **Rationale:** shared TS module gives consistent behavior in CI and local, avoids script duplication, and stays within the no-new-dependency constraint.
 - **Approval:** approved
 
-### Design
+## Design
 
 - **Architecture:** single \`release-validator\` module in \`src/release/\` exporting typed check functions. CI script and local CLI both import and run the same checks.
 - **Key components:** \`validateMetadata()\`, \`validateChangelog()\`, \`validateVersion()\` — each returns a typed result with error details. A \`runAll()\` orchestrator runs checks and exits non-zero on any failure.
 - **Data flow:** package.json + CHANGELOG.md → validator module → structured result → CI/CLI renders human-readable report.
 
-### Assumptions and Open Questions
+## Assumptions and Open Questions
 
 - **Assumptions:** CI remains the primary execution path; existing release metadata files remain the source of truth; v1 prioritizes determinism over customization.
 - **Open questions:** What exact rollback sequence for failed publish? Should status output include machine-readable JSON alongside markdown?
 
-### Notes for the next stage
+## Notes for the next stage
 
 Carry the no-new-dependency constraint and hard-block behavior directly into scope in/out boundaries.`,
-    scope: `### Scope contract
+    scope: `## Scope contract
 
 **Mode selected:** SELECTIVE EXPANSION
 **Default heuristic used:** feature enhancement -> selective
 **Mode-specific analysis result:** hold-scope baseline accepted first; one expansion accepted (degraded-state UX), one deferred (real-time channel upgrade).
 
-### Prime Directives (applied)
+## Prime Directives (applied)
 
 - Zero silent failures: every delivery failure maps to a visible degraded state.
 - Named error surfaces: stream disconnect, auth drift, and publisher timeout are explicit.
@@ -60,11 +60,11 @@ Carry the no-new-dependency constraint and hard-block behavior directly into sco
 - Interaction edge cases in scope: double-open panel, reconnect after sleep, stale tab state.
 - Observability in scope: stream error counter, publish-to-visible lag metric, and alert threshold.
 
-### Premise challenge result
+## Premise challenge result
 
 The original premise (“add notifications”) was reframed to **“ensure users know when an action requires follow-up”**, which expands the solution space beyond toast spam to include durable inbox items, empty states, and recovery paths when delivery fails.
 
-### Dream State Mapping
+## Dream State Mapping
 
 | Stage | Statement |
 | --- | --- |
@@ -73,7 +73,7 @@ The original premise (“add notifications”) was reframed to **“ensure users
 | **12-MONTH IDEAL** | Unified notification center with reliable multi-channel fan-out and user-level routing preferences. |
 | **Alignment verdict** | Aligned: this scope builds the durability foundation without prematurely committing to channel expansion. |
 
-### Mode-Specific Analysis
+## Mode-Specific Analysis
 
 **Selected mode:** SELECTIVE EXPANSION
 
@@ -81,7 +81,7 @@ The original premise (“add notifications”) was reframed to **“ensure users
 - **Expansion evaluated — degraded-state UX (accepted):** Adding an explicit "live updates paused" banner and polling fallback turns a reliability gap into a visible, recoverable state. Low incremental effort (S), high user trust payoff.
 - **Expansion evaluated — real-time channel upgrade (deferred):** WebSocket channel provides lower latency but requires new infra (connection pool, auth handshake). Not justified for current load; deferred to post-v1 validation.
 
-### Implementation Alternatives
+## Implementation Alternatives
 
 | Option | Summary | Effort (S/M/L/XL) | Risk | Pros | Cons | Reuses |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -89,7 +89,7 @@ The original premise (“add notifications”) was reframed to **“ensure users
 | **B (recommended)** | SSE live updates + REST fallback snapshot | M | Med | Better timeliness, graceful degradation | Requires reconnect handling | Existing event publisher + REST path |
 | **C (ideal architecture)** | Event bus + WebSocket channel + feed projection | XL | High | Strong long-term scalability | Overbuilt for current demand | Partial reuse of publisher only |
 
-### Temporal Interrogation
+## Temporal Interrogation
 
 | Time slice | Likely decision pressure | Lock now or defer? | Reason |
 | --- | --- | --- | --- |
@@ -98,7 +98,7 @@ The original premise (“add notifications”) was reframed to **“ensure users
 | **HOUR 4-5 (integration)** | Handling gaps between snapshot and stream cursor | **Lock now** | Prevent silent data loss during reconnect windows |
 | **HOUR 6+ (polish/tests)** | Banner copy tone and polling cadence tuning | **Defer** | Safe to iterate after baseline reliability is proven |
 
-### In scope / out of scope / deferred
+## In scope / out of scope / deferred
 
 | Category | Items |
 | --- | --- |
@@ -106,29 +106,29 @@ The original premise (“add notifications”) was reframed to **“ensure users
 | **Out of scope** | Email/SMS/push providers; marketing campaigns; per-user notification preferences beyond on/off |
 | **Deferred** | WebSocket channel; rich media attachments in notifications; full-text search across historical events |
 
-### Discretion Areas
+## Discretion Areas
 
 - Client-side badge rendering strategy (optimistic vs server-confirmed) is implementation discretion.
 - Polling fallback backoff curve is implementation discretion if degraded-state UX remains explicit.
 
-### Error & Rescue Registry (sample entry)
+## Error & Rescue Registry (sample entry)
 
 | Capability | Failure mode | Detection | Fallback |
 | --- | --- | --- | --- |
 | Event delivery | SSE connection drops mid-session | Client \`EventSource\` error event + heartbeat timeout | Fall back to REST polling every 30s until SSE reconnect succeeds; show subtle “live updates paused” banner |
 
-### Completion Dashboard
+## Completion Dashboard
 
 - Checklist findings: 9/9 complete (complex path)
 - Resolved decisions count: 7
 - Unresolved decisions: None
 
-### Scope Summary
+## Scope Summary
 
 - Accepted scope: durable feed + SSE + explicit degraded UX.
 - Deferred: WebSocket channel and rich-media/search enhancements.
 - Explicitly excluded: outbound channels and marketing workflows for v1.`,
-    design: `### Codebase Investigation (blast-radius files)
+    design: `## Codebase Investigation (blast-radius files)
 
 | File | Current responsibility | Patterns discovered |
 | --- | --- | --- |
@@ -139,7 +139,7 @@ The original premise (“add notifications”) was reframed to **“ensure users
 
 Discovery: existing EventEmitter-based bus has no durability — notifications must add persistence layer on top, not replace the bus.
 
-### Search Before Building (sample result)
+## Search Before Building (sample result)
 
 | Layer | Label | What to reuse first |
 | --- | --- | --- |
@@ -147,7 +147,7 @@ Discovery: existing EventEmitter-based bus has no durability — notifications m
 | Layer 2 | existing codebase | Existing auth middleware, existing API client wrapper, existing feature flags helper |
 | Layer 3 | npm | A small, well-maintained SSE helper (only if Layer 1–2 cannot cover framing/reconnect ergonomics) |
 
-### Architecture Diagram (mandatory)
+## Architecture Diagram (mandatory)
 
 \`\`\`
 ┌─────────────┐      ┌──────────────┐      ┌────────────────┐
@@ -163,7 +163,7 @@ Discovery: existing EventEmitter-based bus has no durability — notifications m
 
 Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Queue (persist) → Read Model (project).
 
-### What Already Exists
+## What Already Exists
 
 | Sub-problem | Existing code/library | Layer | Reuse decision |
 | --- | --- | --- | --- |
@@ -172,7 +172,7 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 | SSE framing | None | Layer 3 | Evaluate \`better-sse\` npm package |
 | Notification schema | None | — | New: define in \`src/schemas/notification.ts\` |
 
-### Failure Mode Table
+## Failure Mode Table
 
 | Failure | Trigger | Detection | Mitigation | User impact |
 | --- | --- | --- | --- | --- |
@@ -180,13 +180,13 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 | Duplicate publish | Retry after timeout | Dedupe key check in outbox | Upsert with idempotency key | None (transparent) |
 | Queue backpressure | Spike >1000 events/s | Queue depth metric alarm | Back-pressure signal to publisher, shed non-critical events | Delayed delivery of low-priority notifications |
 
-### Test Strategy
+## Test Strategy
 
 - **Unit:** validator functions, dedupe-key logic, event schema factories — target 90%+ line coverage.
 - **Integration:** publisher → outbox → read-model pipeline via in-memory DB; SSE reconnect with simulated drops.
 - **E2E:** one happy-path browser test (publish → feed visible) and one degraded-path test (SSE down → REST fallback + banner).
 
-### Performance Budget
+## Performance Budget
 
 | Critical path | Metric | Target | Measurement method |
 | --- | --- | --- | --- |
@@ -194,13 +194,13 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 | Feed snapshot load | p99 response time | ≤ 200 ms | Load test with 1 000 items per user |
 | SSE reconnect | Time to first event after drop | ≤ 3 s | Simulated disconnect in integration suite |
 
-### NOT in scope
+## NOT in scope
 
 - Outbound channels (email, push, SMS) — deferred to v2.
 - Admin notification management UI — separate workstream.
 - Notification preferences / mute rules — requires user settings redesign.
 
-### Parallelization Strategy
+## Parallelization Strategy
 
 | Module | Depends on | Parallel lane | Conflict risk |
 | --- | --- | --- | --- |
@@ -208,18 +208,18 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 | Publisher + outbox (T2) | T1 | Lane A | None |
 | Client feed + SSE (T3) | T1, T2 | Lane B (after T1) | Shared event type definitions |
 
-### Unresolved Decisions
+## Unresolved Decisions
 
 | Decision | Status | Options | Missing info | Default if unanswered |
 | --- | --- | --- | --- | --- |
 | Feed storage model | OPEN | (A) append-only event log, (B) mutable rows, (C) hybrid | Load testing results on read patterns | (A) append-only — safest for audit trail |
 
-### Interface sketch (non-binding)
+## Interface sketch (non-binding)
 
 - **Client → server:** \`GET /api/me/notifications/snapshot?limit=50\` plus optional cursor parameters (if adopted).
 - **Server → client:** \`GET /api/me/notifications/stream\` as SSE with periodic heartbeats.
 
-### Completion Dashboard
+## Completion Dashboard
 
 | Review Section | Status | Issues |
 | --- | --- | --- |
@@ -231,10 +231,10 @@ Data flow: Gateway → Service (validate + enrich) → Publisher (fan-out) → Q
 
 **Decisions made:** 4 | **Unresolved:** 1 (feed storage model)
 
-### Quality bar for this stage
+## Quality bar for this stage
 
 Design output should be **reviewable by someone who did not attend brainstorming**: they can trace from constraints → components → open decisions without reading code.`,
-    spec: `### Acceptance Criteria
+    spec: `## Acceptance Criteria
 
 | ID | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
 | --- | --- | --- |
@@ -242,7 +242,7 @@ Design output should be **reviewable by someone who did not attend brainstorming
 | AC-2 | Given the same logical notification is published twice with the same dedupe key, when the client processes the stream, the feed contains exactly one visible item for that key. | Architecture: dedupe-key in event schema |
 | AC-3 | Given the live connection is unavailable, when the user opens the notifications panel, the UI shows a non-blocking "live updates paused" banner and loads the latest snapshot via REST within 2 seconds. | Architecture: REST fallback + degraded UX |
 
-### Edge Cases
+## Edge Cases
 
 | Criterion ID | Boundary case | Error case |
 | --- | --- | --- |
@@ -250,12 +250,12 @@ Design output should be **reviewable by someone who did not attend brainstorming
 | AC-2 | Two events with identical dedupe key arrive within same SSE frame (boundary: only one row rendered). | Dedupe-key field missing — reject event at publisher and log error. |
 | AC-3 | SSE disconnects after exactly 30 s heartbeat timeout (boundary: banner appears within 1 s of timeout). | REST snapshot endpoint returns 500 — panel shows "unable to load" with retry button. |
 
-### Constraints and Assumptions
+## Constraints and Assumptions
 
 - **Constraints:** Max feed size 1 000 items per user. SSE heartbeat interval 30 s (server-side). REST snapshot p99 \u2264 200 ms. No new runtime dependencies.
 - **Assumptions:** Users have a single active session at a time for v1. Existing auth middleware provides user context. Event publisher is single-writer per user.
 
-### Testability Map
+## Testability Map
 
 | Criterion ID | Verification approach | Command/manual steps |
 | --- | --- | --- |
@@ -263,11 +263,11 @@ Design output should be **reviewable by someone who did not attend brainstorming
 | AC-2 | Unit test: publish same dedupe key twice \u2192 assert single row in feed store. | \`pnpm vitest run tests/unit/dedupe-feed.test.ts\` |
 | AC-3 | E2E test: kill SSE transport \u2192 assert banner visible + REST snapshot loads. | \`pnpm playwright test tests/e2e/degraded-mode.spec.ts\` |
 
-### Approval
+## Approval
 
 - Approved by: user
 - Date: 2026-04-14`,
-    plan: `### Dependency Graph
+    plan: `## Dependency Graph
 
 \`\`\`
 T-1 ──▶ T-2 ──▶ T-3
@@ -277,7 +277,7 @@ T-1 ──▶ T-2 ──▶ T-3
 
 Parallel opportunity: T-1 is a prerequisite for both T-2 and T-3 (T-3 also needs T-2).
 
-### Dependency Waves
+## Dependency Waves
 
 #### Wave 1 (foundation)
 - Task IDs: T-1
@@ -295,7 +295,7 @@ Parallel opportunity: T-1 is a prerequisite for both T-2 and T-3 (T-3 also needs
 
 Execution rule: complete and verify each wave before starting the next wave.
 
-### Task List
+## Task List
 
 | Task ID | Description | Acceptance criterion | Verification command | Effort |
 | --- | --- | --- | --- | --- |
@@ -303,7 +303,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 | T-2 | Implement publisher + outbox write path | AC-1: integration test (happy path publish) | \`\`\`pnpm vitest run tests/integration/publisher.test.ts\`\`\` |
 | T-3 | Implement client feed + SSE subscribe + REST fallback | AC-1, AC-2, AC-3: e2e tests including degraded mode | \`\`\`pnpm playwright test tests/e2e/notification-feed.spec.ts\`\`\` |
 
-### Acceptance Mapping
+## Acceptance Mapping
 
 | Criterion ID | Task IDs |
 | --- | --- |
@@ -311,17 +311,17 @@ Execution rule: complete and verify each wave before starting the next wave.
 | AC-2 (idempotency) | T-1, T-2 |
 | AC-3 (failure visibility) | T-3 |
 
-### Risk Assessment
+## Risk Assessment
 
 | Task/Wave | Risk | Likelihood | Impact | Mitigation |
 | --- | --- | --- | --- | --- |
 | T-3 (Wave 3) | SSE reconnect logic complex | Medium | High | Spike reconnect in isolation before integrating with feed UI |
 | Wave 2 → 3 | Publisher API contract may shift | Low | Medium | Pin contract in T-1 schema; T-2 integration test validates |
 
-### WAIT_FOR_CONFIRM
+## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:`,
-    tdd: `### RED Evidence
+    tdd: `## RED Evidence
 
 | Slice | Test name | Command | Failure output summary |
 | --- | --- | --- | --- |
@@ -329,7 +329,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 | S-2 (publisher outbox) | publishes event to outbox with dedupe key | \`\`\`pnpm vitest run tests/integration/publisher.test.ts\`\`\` | publishToOutbox is not a function |
 | S-3 (client feed + fallback) | shows notification within 5s via SSE | \`\`\`pnpm playwright test tests/e2e/notification-feed.spec.ts\`\`\` | Element [data-testid="feed-item"] not found |
 
-### Acceptance Mapping
+## Acceptance Mapping
 
 | Slice | Plan task ID | Spec criterion ID |
 | --- | --- | --- |
@@ -337,7 +337,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 | S-2 | T-2 | AC-1 |
 | S-3 | T-3 | AC-1, AC-2, AC-3 |
 
-### Failure Analysis
+## Failure Analysis
 
 | Slice | Expected missing behavior | Actual failure reason |
 | --- | --- | --- |
@@ -345,22 +345,22 @@ Execution rule: complete and verify each wave before starting the next wave.
 | S-2 | publishToOutbox function not implemented | Function not found — correct: write path missing |
 | S-3 | Feed UI not rendered, SSE not connected | DOM element missing — correct: client component not built |
 
-### GREEN Evidence
+## GREEN Evidence
 
 - Full suite command: \`\`\`pnpm vitest run && pnpm playwright test\`\`\`
 - Full suite result: 47 tests passed (3 new + 44 existing), 0 failed, 0 skipped
 
-### REFACTOR Notes
+## REFACTOR Notes
 
 - What changed: Extracted \`\`\`mergeLatestByDedupeKey\`\`\` helper from inline loop in \`\`\`summarizeDedupedFeed\`\`\`; moved SSE reconnect logic into \`\`\`useSSEConnection\`\`\` hook.
 - Why: Dedupe merge logic is reused by both publisher and client; reconnect logic was duplicated across components.
 - Behavior preserved: Full suite re-run confirms 47/47 pass after refactor.
 
-### Traceability
+## Traceability
 
 - Plan task IDs: T-1, T-2, T-3
 - Spec criterion IDs: AC-1, AC-2, AC-3`,
-    review: `### Layer 1 Verdict
+    review: `## Layer 1 Verdict
 
 | Criterion | Verdict | Evidence |
 | --- | --- | --- |
@@ -368,7 +368,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 | AC-2: Dedupe — one visible item per key | PARTIAL | Unit tests cover publisher dedupe; UI merge path lacks test for race reordering (\`feedStore.test.ts\` missing case) |
 | AC-3: Degraded mode + REST snapshot | PASS | \`NotificationsPanel.tsx:112-140\` renders banner + calls snapshot endpoint |
 
-### Layer 2 Findings
+## Layer 2 Findings
 
 | ID | Severity | Category | Description | Status |
 | --- | --- | --- | --- | --- |
@@ -376,12 +376,12 @@ Execution rule: complete and verify each wave before starting the next wave.
 | R-2 | Important | performance | \`feedStore.merge()\` does full-array scan on every SSE event; O(n) per event where n is feed length. | open |
 | R-3 | Suggestion | architecture | SSE reconnect logic duplicated across \`useNotifications\` and \`usePresence\`; extract shared hook. | open |
 
-### Review Army Contract
+## Review Army Contract
 
 - See \`07-review-army.json\`
 - Reconciliation summary: 1 duplicate collapsed (R-1 reported by spec-reviewer and code-reviewer), 0 conflicts
 
-### Review Readiness Dashboard
+## Review Readiness Dashboard
 
 - Layer 1 complete: yes (3/3 criteria)
 - Layer 2 complete: yes (5 sections reviewed)
@@ -389,16 +389,16 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Open critical blockers: 1 (R-1)
 - Ship recommendation: BLOCKED until R-1 resolved
 
-### Severity Summary
+## Severity Summary
 
 - Critical: 1
 - Important: 1
 - Suggestion: 1
 
-### Final Verdict
+## Final Verdict
 
 - BLOCKED`,
-    ship: `### Preflight Results
+    ship: `## Preflight Results
 
 - Review verdict: APPROVED_WITH_CONCERNS (R-1 resolved, R-2 accepted as known debt)
 - Build: pass (\`pnpm build\` succeeds)
@@ -407,25 +407,25 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Type-check: pass (\`pnpm typecheck\` clean)
 - Working tree clean: yes (\`git status\` shows no uncommitted changes)
 
-### Release Notes
+## Release Notes
 
 - **Added:** In-app notification feed with SSE updates and REST fallback snapshotting (AC-1, AC-3).
 - **Changed:** Notification payloads now include a stable dedupe key for idempotent rendering (AC-2).
 - **Fixed:** Panel no longer drops the newest item when reconnecting after sleep/resume.
 - **Breaking changes:** None.
 
-### Rollback Plan
+## Rollback Plan
 
 - Trigger conditions: error rate on \`/notifications/stream\` exceeds 5% for >5 minutes, or p95 publish-to-visible lag exceeds 10s.
 - Rollback steps: \`git revert <merge-sha> && git push origin main\` then redeploy; if DB migrations shipped, run \`2026_04_12_notifications_cursor_down.sql\` before traffic.
 - Verification steps: confirm error rate returns to pre-release baseline within 10 minutes; smoke-test feed panel manually.
 
-### Monitoring
+## Monitoring
 
 - Metrics/logs to watch: error rate on \`/notifications/stream\` and snapshot endpoint for 24h; p95 publish-to-visible lag via metrics dashboard.
 - Risk note (if no monitoring): N/A — monitoring is in place.
 
-### Finalization
+## Finalization
 
 - Selected enum: FINALIZE_OPEN_PR
 - Selected label: B
@@ -436,5 +436,14 @@ export function stageExamples(stage) {
     const examples = STAGE_EXAMPLES[stage];
     if (!examples)
         return "";
-    return `## Examples\n\nConcrete samples of what good output looks like for this stage.\n\n${examples}\n`;
+    return [
+        "## Examples",
+        "",
+        "Concrete artifact samples. These mirror the exact heading levels agents must use when authoring the stage artifact (all H2 `##` sections), so they are presented inside a markdown fence to avoid collapsing into the SKILL outline.",
+        "",
+        "```markdown",
+        examples,
+        "```",
+        ""
+    ].join("\n");
 }

package/dist/content/hooks.d.ts

@@ -11,6 +11,7 @@ export interface HookRuntimeOptions {
 export declare const RUNTIME_SHELL_DETECT_ROOT = "HARNESS=\"codex\"\nif [ -n \"${CLAUDE_PROJECT_DIR:-}\" ]; then\n  HARNESS=\"claude\"\nelif [ -n \"${CURSOR_PROJECT_DIR:-}\" ] || [ -n \"${CURSOR_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"cursor\"\nelif [ -n \"${OPENCODE_PROJECT_DIR:-}\" ] || [ -n \"${OPENCODE_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"opencode\"\nfi\n\nROOT=\"\"\nfor candidate in \"${CCLAW_PROJECT_ROOT:-}\" \"${CLAUDE_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_ROOT:-}\" \"${OPENCODE_PROJECT_DIR:-}\" \"${OPENCODE_PROJECT_ROOT:-}\" \"${PWD:-}\"; do\n  if [ -n \"$candidate\" ] && [ -d \"$candidate/.cclaw\" ]; then\n    ROOT=\"$candidate\"\n    break\n  fi\ndone\nif [ -z \"$ROOT\" ]; then\n  ROOT=\"${CCLAW_PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-${CURSOR_PROJECT_ROOT:-${OPENCODE_PROJECT_DIR:-${OPENCODE_PROJECT_ROOT:-${PWD}}}}}}}\"\nfi";
 export declare function sessionStartScript(_options?: HookRuntimeOptions): string;
 export declare function stopCheckpointScript(): string;
+export declare function preCompactScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
 export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -616,6 +616,151 @@ case "$HARNESS" in
 esac
 `;
 }
+export function preCompactScript() {
+    return `#!/usr/bin/env bash
+# cclaw pre-compact hook — generated by cclaw sync
+# Persists a session digest before the harness compacts/clears context, so the
+# next session-start hook can restore the most important state without the agent
+# having to re-derive it from scratch.
+set -uo pipefail
+
+${DETECT_ROOT}
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
+STATE_FILE="$STATE_DIR/flow-state.json"
+DELEGATION_FILE="$STATE_DIR/delegation-log.json"
+KNOWLEDGE_FILE="$ROOT/${RUNTIME_ROOT}/knowledge.md"
+DIGEST_FILE="$STATE_DIR/session-digest.md"
+DIGEST_TMP="$STATE_DIR/session-digest.md.tmp.$$"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+cleanup_digest_tmp() {
+  rm -f "$DIGEST_TMP" 2>/dev/null || true
+}
+trap cleanup_digest_tmp EXIT INT TERM
+
+STAGE="none"
+TRACK="standard"
+COMPLETED="0"
+SKIPPED=""
+ACTIVE_RUN="none"
+PASSED_GATES=""
+BLOCKED_GATES=""
+
+if [ -f "$STATE_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    STAGE=$(jq -r '.currentStage // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+    TRACK=$(jq -r '.track // "standard"' "$STATE_FILE" 2>/dev/null || echo "standard")
+    COMPLETED=$(jq -r '(.completedStages // []) | length' "$STATE_FILE" 2>/dev/null || echo "0")
+    SKIPPED=$(jq -r '(.skippedStages // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+    ACTIVE_RUN=$(jq -r '.activeRunId // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+    PASSED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGates[$stage].passed // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+    BLOCKED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGates[$stage].blocked // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+  elif command -v python3 >/dev/null 2>&1; then
+    OUTPUT=$(python3 - "$STATE_FILE" <<'PY'
+import json, sys
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+except Exception:
+    data = {}
+stage = data.get("currentStage") or "none"
+track = data.get("track") or "standard"
+completed = data.get("completedStages") or []
+skipped = data.get("skippedStages") or []
+run = data.get("activeRunId") or "none"
+gates = (data.get("stageGates") or {}).get(stage) or {}
+passed = gates.get("passed") or []
+blocked = gates.get("blocked") or []
+print(stage)
+print(track)
+print(len(completed) if isinstance(completed, list) else 0)
+print(",".join(skipped) if isinstance(skipped, list) else "")
+print(run)
+print(",".join(passed) if isinstance(passed, list) else "")
+print(",".join(blocked) if isinstance(blocked, list) else "")
+PY
+)
+    {
+      IFS= read -r STAGE
+      IFS= read -r TRACK
+      IFS= read -r COMPLETED
+      IFS= read -r SKIPPED
+      IFS= read -r ACTIVE_RUN
+      IFS= read -r PASSED_GATES
+      IFS= read -r BLOCKED_GATES
+    } <<EOF
+$OUTPUT
+EOF
+  fi
+fi
+
+DELEGATION_PENDING=""
+if [ -f "$DELEGATION_FILE" ] && command -v jq >/dev/null 2>&1; then
+  DELEGATION_PENDING=$(jq -r --arg stage "$STAGE" '
+    (.entries // [])
+    | map(select((.stage // "") == $stage and (.status // "") != "completed" and (.status // "") != "waived"))
+    | map(.agent // "unknown")
+    | unique
+    | join(",")
+  ' "$DELEGATION_FILE" 2>/dev/null || echo "")
+fi
+
+KNOWLEDGE_TAIL=""
+if [ -f "$KNOWLEDGE_FILE" ] && [ -s "$KNOWLEDGE_FILE" ]; then
+  KNOWLEDGE_TAIL=$(tail -n 12 "$KNOWLEDGE_FILE" 2>/dev/null || echo "")
+fi
+
+GIT_HEAD=""
+GIT_BRANCH=""
+GIT_DIRTY="unknown"
+if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  GIT_HEAD=$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo "")
+  GIT_BRANCH=$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  if [ -n "$(git -C "$ROOT" status --porcelain 2>/dev/null)" ]; then
+    GIT_DIRTY="dirty"
+  else
+    GIT_DIRTY="clean"
+  fi
+fi
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+
+{
+  printf '# Session Digest\n'
+  printf '_Generated by pre-compact hook at %s_\n\n' "$TS"
+  printf '## Flow snapshot\n'
+  printf '- track: %s\n' "$TRACK"
+  printf '- current stage: %s\n' "$STAGE"
+  printf '- completed: %s stages\n' "$COMPLETED"
+  printf '- skipped: %s\n' "\${SKIPPED:-(none)}"
+  printf '- run: %s\n\n' "$ACTIVE_RUN"
+  printf '## Gates (current stage)\n'
+  printf '- passed: %s\n' "\${PASSED_GATES:-(none)}"
+  printf '- blocked: %s\n\n' "\${BLOCKED_GATES:-(none)}"
+  printf '## Outstanding delegations\n'
+  printf '- pending: %s\n\n' "\${DELEGATION_PENDING:-(none)}"
+  printf '## Git\n'
+  printf '- branch: %s\n' "\${GIT_BRANCH:-(unknown)}"
+  printf '- head: %s\n' "\${GIT_HEAD:-(unknown)}"
+  printf '- worktree: %s\n\n' "$GIT_DIRTY"
+  if [ -n "$KNOWLEDGE_TAIL" ]; then
+    printf '## Knowledge tail\n'
+    printf '%s\n' "$KNOWLEDGE_TAIL"
+  fi
+} > "$DIGEST_TMP" 2>/dev/null || true
+
+if [ -s "$DIGEST_TMP" ]; then
+  mv "$DIGEST_TMP" "$DIGEST_FILE" 2>/dev/null || rm -f "$DIGEST_TMP" 2>/dev/null || true
+fi
+
+trap - EXIT INT TERM
+exit 0
+`;
+}
 // ---------------------------------------------------------------------------
 // hooks.json generators are defined in observe.ts (shared across harnesses).
 // ---------------------------------------------------------------------------