@wazir-dev/cli 1.0.0

package/docs/readmes/features/exports/README.md

@@ -0,0 +1,222 @@
+# Host Exports
+
+Wazir's export system compiles canonical role, workflow, and hook sources into
+ready-to-deploy host packages for **Claude, Codex, Gemini, and Cursor**. Each host
+gets a package shaped for its native integration model — no manual copying, no hand-
+editing, no drift.
+
+---
+
+## What Host Exports Are
+
+Every AI host has its own convention for loading agent instructions:
+
+- Claude reads `CLAUDE.md`, `.claude/agents/`, and `.claude/commands/`
+- Codex reads `AGENTS.md`
+- Gemini reads `GEMINI.md`
+- Cursor reads `.cursor/rules/` and `.cursor/hooks.json`
+
+The export system generates all of these from a single set of canonical sources.
+The canonical sources are the ground truth. The exports are derived artifacts.
+
+**You never edit files in `exports/hosts/*` by hand.** Run `wazir export build`
+and the compiler overwrites them from the canonical sources.
+
+---
+
+## Supported Hosts
+
+| Host | Output path | Key files |
+|---|---|---|
+| Claude | `exports/hosts/claude/` | `CLAUDE.md`, `.claude/agents/*`, `.claude/commands/*`, `.claude/settings.json` |
+| Codex | `exports/hosts/codex/` | `AGENTS.md` |
+| Gemini | `exports/hosts/gemini/` | `GEMINI.md` |
+| Cursor | `exports/hosts/cursor/` | `.cursor/rules/wazir-core.mdc`, `.cursor/hooks.json` |
+
+---
+
+## How Packages Are Generated
+
+```
+wazir export build
+        │
+        ▼
+1. Validate wazir.manifest.yaml
+        │
+        ▼
+2. Validate canonical hook definitions
+        │
+        ▼
+3. Collect canonical sources
+   ┌────────────────────────────────┐
+   │ wazir.manifest.yaml       │
+   │ roles/*.md  (9 role files)     │
+   │ workflows/*.md (13 workflows)  │
+   │ hooks/definitions/*.yaml       │
+   └────────────────────────────────┘
+        │
+        ▼
+4. SHA-256 hash each source file
+        │
+        ▼
+5. For each host in export_targets:
+   ├── Render host-specific package files
+   ├── Write host-package.json  (sources + file list)
+   └── Write export.manifest.json  (source hashes)
+        │
+        ▼
+   exports/hosts/<host>/
+```
+
+The compiler (`tooling/src/export/compiler.js`) does not template files — it reads the
+canonical Markdown directly and writes it into the host-appropriate directory structure.
+This means roles and workflows appear verbatim in each host package.
+
+---
+
+## What Is Included in Each Package
+
+### Claude
+
+```
+exports/hosts/claude/
+  CLAUDE.md                      Project bootstrap + canonical facts
+  .claude/agents/clarifier.md
+  .claude/agents/designer.md
+  .claude/agents/executor.md
+  .claude/agents/learner.md
+  .claude/agents/planner.md
+  .claude/agents/researcher.md
+  .claude/agents/reviewer.md
+  .claude/agents/specifier.md
+  .claude/agents/verifier.md
+  .claude/commands/clarify.md
+  .claude/commands/design.md
+  .claude/commands/design-review.md
+  .claude/commands/discover.md
+  .claude/commands/execute.md
+  .claude/commands/learn.md
+  .claude/commands/plan.md
+  .claude/commands/plan-review.md
+  .claude/commands/prepare-next.md
+  .claude/commands/review.md
+  .claude/commands/spec-challenge.md
+  .claude/commands/specify.md
+  .claude/commands/verify.md
+  .claude/settings.json
+  export.manifest.json           Source hashes for drift detection
+  host-package.json              Source list + generated file list
+```
+
+### Codex
+
+```
+exports/hosts/codex/
+  AGENTS.md                      Single combined instruction file
+  export.manifest.json
+  host-package.json
+```
+
+### Gemini
+
+```
+exports/hosts/gemini/
+  GEMINI.md                      Single combined instruction file
+  export.manifest.json
+  host-package.json
+```
+
+### Cursor
+
+```
+exports/hosts/cursor/
+  .cursor/rules/wazir-core.mdc
+  .cursor/hooks.json
+  export.manifest.json
+  host-package.json
+```
+
+---
+
+## Drift Detection
+
+Every export includes `export.manifest.json` — a map of canonical source paths to
+their SHA-256 hashes at the time of the last build:
+
+```json
+{
+  "host": "claude",
+  "source_hashes": {
+    "wazir.manifest.yaml": "63d162af...",
+    "roles/clarifier.md": "5e59e8e7...",
+    "workflows/clarify.md": "93034dce...",
+    ...
+  }
+}
+```
+
+`wazir export --check` re-hashes the current canonical sources and compares them
+against the stored hashes. If any source has changed since the last build, the check
+fails non-zero — catching stale exports before they reach CI or production.
+
+**Recommended CI workflow:**
+
+```bash
+# In CI, after any change to roles/, workflows/, or hooks/
+wazir export --check
+# Fails if exports are out of date — developer must run `export build` and commit
+```
+
+---
+
+## Using Exports in Your Project
+
+### Claude
+
+Copy the contents of `exports/hosts/claude/` into your project root:
+
+```bash
+cp -r exports/hosts/claude/.claude /your/project/
+cp exports/hosts/claude/CLAUDE.md /your/project/
+```
+
+Claude will automatically load `CLAUDE.md` as its system context and discover agents
+and commands under `.claude/`.
+
+### Codex
+
+```bash
+cp exports/hosts/codex/AGENTS.md /your/project/
+```
+
+### Gemini
+
+```bash
+cp exports/hosts/gemini/GEMINI.md /your/project/
+```
+
+### Cursor
+
+```bash
+cp -r exports/hosts/cursor/.cursor /your/project/
+```
+
+---
+
+## Protected Paths
+
+`exports/hosts/` is declared as a protected path in `wazir.manifest.yaml`. The
+`protected_path_write_guard` hook prevents agents from writing directly to this
+directory. All changes must flow through `wazir export build`.
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `wazir export build` | Compile all host packages from canonical sources |
+| `wazir export --check` | Verify packages are current; exits non-zero on drift |
+
+Both commands resolve the project root automatically by walking upward to find
+`wazir.manifest.yaml`.

package/docs/readmes/features/hooks/README.md

@@ -0,0 +1,103 @@
+# Hooks
+
+> Canonical hook contracts that enforce protected paths, loop caps, capture routing, and session observability across every AI host.
+
+Hooks are **product contracts first**. Each hook definition in `hooks/definitions/*.yaml` specifies the authoritative behavior. Host-specific native hooks or wrapper scripts must preserve that behavior — they cannot relax it.
+
+## Hook Roster
+
+| Hook ID | Type | Event | Failure Mode |
+|---|---|---|---|
+| [session_start](session-start.md) | Observability | Session begins | capture |
+| [pre_tool_capture_route](pre-tool-capture-route.md) | Capture | Before large tool runs | warn |
+| [post_tool_capture](post-tool-capture.md) | Capture | After every tool execution | capture |
+| [pre_compact_summary](pre-compact-summary.md) | Observability | Before context compaction | warn |
+| [stop_handoff_harvest](stop-handoff-harvest.md) | Observability | Session ends | capture |
+| [protected_path_write_guard](protected-path-write-guard.md) | Guard | Write to protected path attempted | **block (exit 42)** |
+| [loop_cap_guard](loop-cap-guard.md) | Guard | Phase iteration limit exceeded | **block (exit 43)** |
+
+## Hook Categories
+
+| Category | Members | Purpose |
+|---|---|---|
+| **Guards** | `protected_path_write_guard`, `loop_cap_guard` | Hard blocks — prevent unsafe actions |
+| **Capture** | `pre_tool_capture_route`, `post_tool_capture` | Route and persist tool output outside model context |
+| **Observability** | `session_start`, `pre_compact_summary`, `stop_handoff_harvest` | Session lifecycle events and handoff data |
+
+## Guard Exit Codes
+
+| Hook | Allowed | Blocked |
+|---|---|---|
+| `protected_path_write_guard` | `0` | `42` |
+| `loop_cap_guard` | `0` | `43` |
+
+## Source of Truth
+
+```
+hooks/definitions/*.yaml     — canonical hook contracts
+schemas/hook.schema.json     — validation schema
+wazir.manifest.yaml     — required_hooks roster
+```
+
+Validate with:
+```bash
+node tooling/src/cli.js validate hooks
+```
+
+## Host Fallback Policy
+
+Every hook definition specifies `host_fallback` guidance for Claude, Codex, Gemini, and Cursor. Fallbacks must preserve:
+
+- The same trigger intent
+- The same protected-path policy
+- The same loop-cap policy
+- The same observable outputs (or a documented equivalent)
+
+| Hook ID | Claude | Codex | Gemini | Cursor |
+|---|---|---|---|---|
+| `session_start` | native_hook | wrapper | wrapper | native_or_wrapper |
+| `pre_tool_capture_route` | native_hook | wrapper | wrapper | native_or_wrapper |
+| `post_tool_capture` | native_hook | wrapper | wrapper | native_or_wrapper |
+| `pre_compact_summary` | native_or_wrapper | wrapper | wrapper | wrapper |
+| `stop_handoff_harvest` | native_hook | wrapper | wrapper | native_or_wrapper |
+| `protected_path_write_guard` | native_or_wrapper | wrapper | wrapper | native_or_wrapper |
+| `loop_cap_guard` | native_or_wrapper | wrapper | wrapper | native_or_wrapper |
+
+## Protected Paths
+
+The following paths are protected by `protected_path_write_guard`:
+
+```
+input/
+roles/
+workflows/
+schemas/
+exports/hosts/
+```
+
+Writes to these paths outside approved regeneration flows are blocked with exit code `42`.
+
+## CLI Capture Commands
+
+Capture hooks are backed by these CLI commands:
+
+```bash
+wazir capture init      # initialize status.json for the run
+wazir capture event     # append an event to events.ndjson
+wazir capture route     # register a capture target path
+wazir capture output    # write captured tool output
+wazir capture summary   # produce summary.md before compaction
+```
+
+## Implementation Status
+
+| Component | Status |
+|---|---|
+| Canonical hook definitions | Implemented |
+| Schema validation | Implemented |
+| CLI capture commands | Implemented |
+| `protected-path-write-guard` script | Implemented |
+| `loop-cap-guard` script | Implemented |
+| `session-start` script | Implemented |
+| `post-tool-lint` script | Implemented |
+| Native execution helpers | Planned |

package/docs/readmes/features/hooks/loop-cap-guard.md

@@ -0,0 +1,133 @@
+# loop_cap_guard
+
+> `PreToolUse` · Guard · Stops additional loop iterations after the configured phase cap is reached. Hard stop — exit 43.
+
+| Property | Value |
+|---|---|
+| **Hook ID** | `loop_cap_guard` |
+| **Trigger event** | Before each phase iteration, after the cap threshold is reached |
+| **Failure mode** | `block` — exits `43` on violation |
+| **Exit codes** | `0` allow · `43` block |
+| **Script** | `hooks/loop-cap-guard` |
+
+## What It Guards
+
+`loop_cap_guard` prevents runaway iteration. AI agents in a loop — debugging, verification retries, re-planning cycles — can iterate indefinitely when not constrained. This guard reads the current loop count from `status.json` and blocks the iteration if the configured cap for the current phase has been exceeded.
+
+This is a hard block. Exit code `43` causes the host to reject the next iteration and surface the situation to the operator for a decision.
+
+## Why Loop Caps Matter
+
+| Without loop_cap_guard | With loop_cap_guard |
+|---|---|
+| Debug loop runs 20+ cycles, no resolution | Debug loop capped at 3 — unresolved after cap is reported |
+| Verification retries forever on a flaky test | Verification retries capped — flakiness documented, escalated |
+| Re-planning cycles consume entire context window | Re-planning capped — operator is asked to unblock |
+| No way to distinguish "working hard" from "spinning" | Cap breach is an explicit signal: escalation needed |
+
+## Trigger Event
+
+Fires before each new iteration of a phase loop. Receives `run_id` and `phase` as inputs and reads the current iteration count from `status.json`.
+
+## Logic
+
+1. **Read payload** — `run_id` and `phase` from stdin.
+2. **Read `status.json`** — load the current loop count for the phase.
+3. **Load phase cap** — look up the configured cap for this phase.
+4. **Evaluate** — is `current_count >= cap`?
+5. **If under cap** — allow. Emit `{ "guard_decision": { "allowed": true } }`. Exit `0`.
+6. **If at or over cap** — block. Emit `{ "guard_decision": { "allowed": false } }`. Exit `43`.
+
+```javascript
+// Decision shapes
+{ "guard_decision": { "allowed": true } }
+{ "guard_decision": { "allowed": false, "reason": "loop cap exceeded for phase: debug (cap: 3, current: 3)" } }
+```
+
+## Configuration
+
+| Parameter | Required | Source | Description |
+|---|---|---|---|
+| `run_id` | Yes | Payload | Current session run identifier |
+| `phase` | Yes | Payload | Phase name being iterated (e.g., `debug`, `verify`) |
+| Phase caps | Yes | Status/config | Per-phase iteration limits |
+
+## What Happens on Violation
+
+When the loop cap is exceeded:
+
+1. Guard emits `{ "guard_decision": { "allowed": false } }` to stdout.
+2. Script exits `43`.
+3. The host rejects the next iteration.
+4. The agent receives a block notification.
+5. The agent must surface the situation to the operator.
+
+When the agent receives a `43` exit:
+- Do not retry the blocked iteration.
+- Do not invent certainty about what would have happened next.
+- Record the block in the active execution artifact or handoff.
+- Present the unresolved state and the evidence gathered so far to the operator.
+- Ask the operator to decide: continue (with a raised cap), investigate differently, or defer.
+
+> [!WARNING]
+> A loop cap breach is not a failure of the agent — it is a signal that human judgment is needed. The correct response is escalation with evidence, not a workaround.
+
+## Example
+
+**Scenario:** Debugging loop reaches 3 cycles without resolving the issue.
+
+```
+Loop 1: wz:debugging cycle — hypothesis H1 tested, rejected
+Loop 2: wz:debugging cycle — hypothesis H2 tested, rejected
+Loop 3: wz:debugging cycle — hypothesis H3 tested, rejected
+
+Loop 4 attempted:
+loop_cap_guard fires:
+  Input: { "run_id": "run-42", "phase": "debug" }
+  Reads status.json: { "debug_loop_count": 3 }
+  Configured cap for "debug": 3
+  3 >= 3 → BLOCK
+  Output: { "guard_decision": { "allowed": false, "reason": "loop cap exceeded..." } }
+  Exit: 43
+
+Host blocks Loop 4.
+Agent responds:
+  "I've completed 3 debugging cycles without resolving the failure. The loop cap has been reached.
+
+  Evidence gathered:
+  - H1: Redis not connected (rejected — connection log shows it is connected)
+  - H2: Test setup race condition (rejected — added await, same failure)
+  - H3: Off-by-one in token count (rejected — manual inspection shows correct math)
+
+  Unresolved: I don't know why the middleware returns 200 instead of 429.
+  Next step options:
+  1. Add verbose debug logging and re-run with cap raised
+  2. Escalate to a human reviewer with the evidence above
+  3. Defer and open an issue"
+```
+
+## Testing
+
+```bash
+# Test the guard script
+echo '{"run_id":"test-run","phase":"debug"}' | node hooks/loop-cap-guard
+# With no status file: should allow (exit 0) — no loop count yet
+
+# Test with a status file showing cap exceeded
+# (requires setting up a status.json with loop count at cap)
+
+# Validate hook definition
+node tooling/src/cli.js validate hooks
+
+# Doctor check (includes loop cap guard status)
+node tooling/src/cli.js doctor --json
+```
+
+## Host Fallback
+
+| Host | Fallback |
+|---|---|
+| Claude | `native_or_wrapper` |
+| Codex | `wrapper_command` |
+| Gemini | `wrapper_command` |
+| Cursor | `native_or_wrapper` |

package/docs/readmes/features/hooks/post-tool-capture.md

@@ -0,0 +1,121 @@
+# post_tool_capture
+
+> `PostToolUse` · Capture · Appends tool execution events and captures output metadata after every tool run.
+
+| Property | Value |
+|---|---|
+| **Hook ID** | `post_tool_capture` |
+| **Trigger event** | After every tool execution completes |
+| **Failure mode** | `capture` — exits 0, never interrupts the agent |
+| **Exit codes** | `0` always |
+
+## What It Guards
+
+`post_tool_capture` is the write half of the capture pipeline. After every tool executes, this hook appends a structured event record to `events.ndjson`, writes any captured output to the registered capture path, and updates `status.json` with the latest tool execution state.
+
+This creates a complete, queryable record of every tool call in a session — the raw material for `pre_compact_summary` and `stop_handoff_harvest`.
+
+## Trigger Event
+
+Fires after every tool execution, receiving the command and exit code as inputs.
+
+## Logic
+
+1. **Receive execution result** — command string and exit code from the completed tool.
+2. **Write captured output** — if a capture path was registered by `pre_tool_capture_route`, write the output to that file.
+3. **Append event** — append a structured event to `events.ndjson` with timestamp, command, exit code, and capture path reference.
+4. **Update status** — write latest tool execution state to `status.json`.
+5. **Exit 0** — agent proceeds in all cases.
+
+## Configuration
+
+| Parameter | Required | Description |
+|---|---|---|
+| `command` | Yes | The command that just executed |
+| `exit_code` | Yes | The exit code from the tool execution |
+
+## What Happens on Violation
+
+This hook does not block. On failure:
+
+| Condition | Outcome |
+|---|---|
+| Write fails (disk full, permissions) | Error logged to stderr; agent proceeds |
+| `status.json` not initialized | Event append attempted, may fail silently |
+| No capture path registered | Output not written to file; event still recorded |
+
+**Side effects produced:**
+
+| Artifact | Location | Description |
+|---|---|---|
+| `events.ndjson` | `~/.wazir/projects/<slug>/events.ndjson` | Newline-delimited JSON event stream |
+| Capture file | Registered capture path | Raw tool output (if capture was routed) |
+| `status.json` | `~/.wazir/projects/<slug>/status.json` | Updated run status |
+
+## Event Record Format
+
+Each appended event has this shape:
+
+```json
+{
+  "ts": "2026-03-13T10:23:45.123Z",
+  "type": "tool_execution",
+  "command": "npm test",
+  "exit_code": 0,
+  "capture_path": "~/.wazir/projects/myapp/captures/run-42/npm-test-001.txt"
+}
+```
+
+## Example
+
+**Scenario:** Full session showing the capture pipeline in action.
+
+```
+1. session_start fires → status.json initialized
+
+2. Agent runs: npm test
+   pre_tool_capture_route → capture_path registered: captures/run-42/npm-test-001.txt
+   Tool executes: npm test (exit 0, 127 tests passing)
+   post_tool_capture fires:
+     → Writes test output to captures/run-42/npm-test-001.txt (47KB)
+     → Appends to events.ndjson: { "command": "npm test", "exit_code": 0, ... }
+     → Updates status.json: { "last_command": "npm test", "status": "ok" }
+
+3. Agent runs: node --version
+   pre_tool_capture_route → no capture needed
+   Tool executes: node --version (exit 0)
+   post_tool_capture fires:
+     → No capture file to write
+     → Appends to events.ndjson: { "command": "node --version", "exit_code": 0 }
+     → Updates status.json
+
+4. pre_compact_summary fires → reads events.ndjson, produces summary.md
+```
+
+## Testing
+
+```bash
+# Initialize a test run
+wazir capture init
+
+# Simulate an event append
+wazir capture event --command "npm test" --exit-code 0
+
+# Check the events file
+cat ~/.wazir/projects/wazir/events.ndjson
+
+# Validate hook definition
+node tooling/src/cli.js validate hooks
+```
+
+> [!TIP]
+> The events.ndjson file is the authoritative session audit trail. `pre_compact_summary` and `stop_handoff_harvest` both read from it to produce their summaries.
+
+## Host Fallback
+
+| Host | Fallback |
+|---|---|
+| Claude | `native_hook` |
+| Codex | `wrapper_command` |
+| Gemini | `wrapper_command` |
+| Cursor | `native_or_wrapper` |