@wazir-dev/cli 1.0.0

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

@@ -0,0 +1,130 @@
+# post-tool-lint
+
+> `PostToolUse` · Guard · Validates JavaScript file syntax immediately after any write that produces a `.js` file.
+
+| Property | Value |
+|---|---|
+| **Script** | `hooks/post-tool-lint` |
+| **Trigger event** | After a tool write that produces a `.js` file |
+| **Failure mode** | Syntax error blocks — exits `2` |
+| **Exit codes** | `0` allow · `2` syntax error |
+
+## What It Guards
+
+`post-tool-lint` catches JavaScript syntax errors the moment a `.js` file is written — before the error can propagate to a test run or a runtime crash. It runs `node --check` on the written file immediately after each write, producing an actionable error message pinpointing exactly which file has the problem.
+
+This is the fastest possible syntax feedback loop: error surfaces at write time, not at execution time.
+
+## Trigger Event
+
+Fires after any tool execution that writes a file. Checks whether the written file path ends in `.js`. If not, exits immediately with `0` (no-op). If yes, runs the syntax check.
+
+## Logic
+
+1. **Read payload** — attempt to parse tool input JSON from stdin; fall back to `CLAUDE_TOOL_FILE_PATH` env variable.
+2. **Extract file path** — from `tool_input.file_path` in payload or the env variable.
+3. **Check extension** — if not `.js`, exit `0` immediately (no-op for all other file types).
+4. **Check file existence** — if the file doesn't exist on disk, exit `0` (write may have been blocked or virtual).
+5. **Run `node --check`** — execute syntax-only validation (no execution, no side effects).
+6. **If valid** — exit `0`.
+7. **If syntax error** — write error details to stderr. Exit `2`.
+
+## Configuration
+
+| Parameter | Source | Description |
+|---|---|---|
+| File path | `tool_input.file_path` or `CLAUDE_TOOL_FILE_PATH` | The `.js` file to lint |
+
+The hook is stateless — no configuration files or manifests needed.
+
+## What Happens on Violation
+
+When a `.js` file has a syntax error:
+
+1. Script writes a detailed error to stderr:
+   ```
+   Syntax error in src/middleware/rate-limit.js:
+   /path/to/src/middleware/rate-limit.js:23
+   const foo = {
+                ^
+   SyntaxError: Unexpected token '}'
+   ```
+2. Script exits `2`.
+3. The host surfaces the error to the agent.
+4. The agent must fix the syntax error and rewrite the file.
+
+> [!WARNING]
+> Exit `2` from this hook means the last write produced invalid JavaScript. Do not continue to the next implementation step — fix the syntax error first. A broken `.js` file that passes to the next tool call is harder to debug than one caught immediately.
+
+## Example
+
+**Scenario:** Agent writes a middleware file with a missing closing brace.
+
+```javascript
+// Written: src/middleware/rate-limit.js (line 23 has missing brace)
+export function rateLimit(options) {
+  return (req, res, next) => {
+    const tokens = getTokens(req.auth);
+    if (tokens <= 0) {
+      return res.status(429).json({ error: 'Rate limit exceeded' });
+    // Missing: closing brace for if block
+    next();
+  };
+}
+```
+
+```
+post-tool-lint fires:
+  File: src/middleware/rate-limit.js
+  Extension: .js — proceed with check
+  Runs: node --check src/middleware/rate-limit.js
+
+  Syntax error in src/middleware/rate-limit.js:
+    ...
+    SyntaxError: Unexpected token '}'
+    at line 28
+
+  Exit: 2
+
+Agent receives the error:
+"Syntax error in the written file. Fixing the missing closing brace in the if block."
+[Agent rewrites the file with correct syntax]
+
+post-tool-lint fires again:
+  node --check → exits 0
+  Exit: 0 — file is valid
+```
+
+**Scenario:** Agent writes a markdown file — hook is a no-op.
+
+```
+post-tool-lint fires:
+  File: docs/plans/2026-03-13-design.md
+  Extension: .md — not .js, exit 0 immediately
+```
+
+## Testing
+
+```bash
+# Test with a valid JS file
+echo 'const x = 1;' > /tmp/test-valid.js
+CLAUDE_TOOL_FILE_PATH=/tmp/test-valid.js node hooks/post-tool-lint
+echo $?  # Expected: 0
+
+# Test with an invalid JS file
+echo 'const x = {' > /tmp/test-invalid.js
+CLAUDE_TOOL_FILE_PATH=/tmp/test-invalid.js node hooks/post-tool-lint
+echo $?  # Expected: 2
+
+# Test with a non-JS file (no-op)
+CLAUDE_TOOL_FILE_PATH=/tmp/README.md node hooks/post-tool-lint
+echo $?  # Expected: 0
+
+# Test with JSON payload
+echo '{"tool_input":{"file_path":"/tmp/test-valid.js"}}' | node hooks/post-tool-lint
+echo $?  # Expected: 0
+```
+
+## Scope
+
+`post-tool-lint` only checks `.js` files. TypeScript, JSON, YAML, and other file types are not checked by this hook. TypeScript syntax validation requires a separate tsc-based hook.

package/docs/readmes/features/hooks/pre-compact-summary.md

@@ -0,0 +1,122 @@
+# pre_compact_summary
+
+> `PreCompact` · Observability · Summarizes captured session state before context compaction or handoff so nothing is lost when the context window shrinks.
+
+| Property | Value |
+|---|---|
+| **Hook ID** | `pre_compact_summary` |
+| **Trigger event** | Before context compaction or session handoff |
+| **Failure mode** | `warn` — exits 0, compaction proceeds even if summary fails |
+| **Exit codes** | `0` always |
+
+## What It Guards
+
+Context compaction discards detail to make room. `pre_compact_summary` runs immediately before compaction and writes a structured summary of everything captured in the current run — tool executions, outcomes, findings — so that information survives the compaction in human-readable form.
+
+Without this hook, compaction discards the raw `events.ndjson` detail and the next agent turn starts with no record of what was executed or what happened.
+
+## Trigger Event
+
+Fires immediately before the host performs context compaction or before a session handoff is initiated.
+
+## Logic
+
+1. **Receive run ID** — identify the current session's state directory.
+2. **Read `events.ndjson`** — load the complete event stream for this run.
+3. **Read any capture files** — load content from capture paths registered during the run.
+4. **Produce summary** — synthesize events and captures into a structured `summary.md`.
+5. **Write `summary.md`** — persist to the run state directory.
+6. **Exit 0** — compaction proceeds regardless.
+
+## Configuration
+
+| Parameter | Required | Description |
+|---|---|---|
+| `run_id` | Yes | The current session run identifier |
+
+## What Happens on Violation
+
+This hook does not block. On failure:
+
+| Condition | Outcome |
+|---|---|
+| `events.ndjson` not found | Warning emitted; summary written with "no events captured" note |
+| Write fails | Warning to stderr; compaction proceeds without summary |
+| Hook encounters an error | Warning emitted; compaction proceeds |
+
+**Side effects produced:**
+
+| Artifact | Location | Description |
+|---|---|---|
+| `summary.md` | `~/.wazir/projects/<slug>/summary.md` | Structured summary of session captured state |
+
+## Summary Format
+
+```markdown
+# Session Summary — run-42 — 2026-03-13T10:45:00Z
+
+## Tool Executions (7)
+| Command | Exit | Capture |
+|---------|------|---------|
+| npm test | 0 | captures/npm-test-001.txt (47KB, 127 passing) |
+| node tooling/src/cli.js validate hooks | 0 | — |
+| git diff | 0 | captures/git-diff-001.txt (12KB) |
+
+## Key Findings
+- All 127 tests passing after rate-limit middleware implementation
+- Hook validation: all 7 hooks validated
+
+## Captures
+- captures/npm-test-001.txt — full test run output (47KB)
+- captures/git-diff-001.txt — diff of changes in session (12KB)
+```
+
+## Example
+
+**Scenario:** Long implementation session is about to compact.
+
+```
+Agent has run 7 commands during the session. Context is 85% full.
+Host triggers context compaction.
+
+pre_compact_summary fires:
+  → Reads events.ndjson (7 events)
+  → Reads 3 capture files
+  → Produces summary.md:
+       7 tool executions
+       2 capture files (60KB total)
+       All verifications passed
+  → Writes to ~/.wazir/projects/myapp/summary.md
+
+Context compacts. Raw event detail discarded.
+Next agent turn reads summary.md — session continuity preserved.
+```
+
+## Testing
+
+```bash
+# Initialize and add test events
+wazir capture init
+wazir capture event --command "npm test" --exit-code 0
+
+# Run the summary
+wazir capture summary
+
+# Check the output
+cat ~/.wazir/projects/wazir/summary.md
+
+# Validate hook definition
+node tooling/src/cli.js validate hooks
+```
+
+> [!TIP]
+> The `stop_handoff_harvest` hook also produces a `summary.md` — but at session end, not at compaction time. `pre_compact_summary` may fire multiple times in a long session; `stop_handoff_harvest` fires exactly once.
+
+## Host Fallback
+
+| Host | Fallback |
+|---|---|
+| Claude | `native_or_wrapper` |
+| Codex | `wrapper_command` |
+| Gemini | `wrapper_command` |
+| Cursor | `wrapper_command` |

package/docs/readmes/features/hooks/pre-tool-capture-route.md

@@ -0,0 +1,100 @@
+# pre_tool_capture_route
+
+> `PreToolUse` · Capture · Routes large command output away from model context before the tool runs.
+
+| Property | Value |
+|---|---|
+| **Hook ID** | `pre_tool_capture_route` |
+| **Trigger event** | Before a tool execution that may produce large output |
+| **Failure mode** | `warn` — exits 0, never blocks tool execution |
+| **Exit codes** | `0` always |
+
+## What It Guards
+
+`pre_tool_capture_route` prevents large tool outputs from flooding the model's context window. When a command is about to run that could produce substantial output (test suites, build logs, audit results), this hook registers a capture target so the output is written to disk rather than injected directly into the model's active context.
+
+Without this hook, large outputs can consume the context window, degrade response quality, and trigger expensive context compaction cycles.
+
+## Trigger Event
+
+Fires before each tool execution, evaluated against the command being run to determine whether capture routing is needed.
+
+## Logic
+
+1. **Receive command** — the incoming tool's command string is passed as input.
+2. **Evaluate output size risk** — assess whether the command is likely to produce large output (e.g., full test suites, build systems, log tails, dependency scans).
+3. **Register capture target** — if routing is warranted, create a capture path where output will be written (a file under the run's state directory).
+4. **Emit capture path** — return the `capture_path` so the tool execution layer knows where to redirect output.
+5. **Exit 0** — tool execution proceeds in all cases.
+
+## Configuration
+
+| Parameter | Required | Description |
+|---|---|---|
+| `command` | Yes | The command string about to be executed |
+
+## What Happens on Violation
+
+This hook does not block. On failure or when routing is not needed:
+
+| Condition | Outcome |
+|---|---|
+| Command unlikely to produce large output | No capture path registered; output goes to context normally |
+| Hook encounters an error | Warning emitted; tool proceeds without capture routing |
+
+**Side effects produced:**
+
+| Artifact | Location | Description |
+|---|---|---|
+| `capture_path` | State root | File path where captured output will be written |
+| Capture target registration | Session state | Records the intent to capture for this command |
+
+## Example
+
+**Scenario:** Agent is about to run a full test suite.
+
+```
+Pre-tool hook fires with: { "command": "npm test" }
+
+Hook evaluates: npm test likely produces > 500 lines of output
+Hook creates capture target: ~/.wazir/projects/myapp/captures/run-42/npm-test-001.txt
+Hook returns: { "capture_path": "~/.wazir/projects/myapp/captures/run-42/npm-test-001.txt" }
+
+Tool execution proceeds, output routed to capture path.
+Model context receives a summary reference rather than raw test output.
+```
+
+**Scenario:** Agent runs a small targeted command.
+
+```
+Pre-tool hook fires with: { "command": "node --version" }
+
+Hook evaluates: single-line output, no capture needed.
+No capture path registered.
+Output goes directly to context normally.
+```
+
+## Testing
+
+```bash
+# Validate hook definition
+node tooling/src/cli.js validate hooks
+
+# Test capture init (which pre_tool_capture_route depends on)
+wazir capture init
+
+# Test capture route registration
+wazir capture route --path /tmp/test-capture.txt
+```
+
+> [!TIP]
+> The `post_tool_capture` hook is the counterpart to this hook — it writes the actual captured output after tool execution. Both hooks must be registered for the capture pipeline to work end-to-end.
+
+## Host Fallback
+
+| Host | Fallback |
+|---|---|
+| Claude | `native_hook` |
+| Codex | `wrapper_command` |
+| Gemini | `wrapper_command` |
+| Cursor | `native_or_wrapper` |

package/docs/readmes/features/hooks/protected-path-write-guard.md

@@ -0,0 +1,128 @@
+# protected_path_write_guard
+
+> `PreToolUse` · Guard · Blocks writes to canonical protected paths outside approved regeneration flows. Hard stop — exit 42.
+
+| Property | Value |
+|---|---|
+| **Hook ID** | `protected_path_write_guard` |
+| **Trigger event** | Any write operation targeting a protected path |
+| **Failure mode** | `block` — exits `42` on violation |
+| **Exit codes** | `0` allow · `42` block |
+| **Script** | `hooks/protected-path-write-guard` |
+
+## What It Guards
+
+`protected_path_write_guard` enforces the boundary between read-only operator truth and agent-modifiable surfaces. Certain paths in the Wazir repo are canonical — they define roles, schemas, workflows, and host exports. Modifying them outside of the approved `export build` regeneration flow would silently corrupt the project's source of truth.
+
+This guard is a hard block. Exit code `42` causes the host to reject the write immediately.
+
+## Protected Paths
+
+| Path | Why Protected |
+|---|---|
+| `input/` | Operator-supplied requirements — read-only by agents |
+| `roles/` | Canonical role contracts — modified only by maintainers |
+| `workflows/` | Phase entrypoints — modified only by maintainers |
+| `schemas/` | Validation schemas — modified only by maintainers |
+| `exports/hosts/` | Generated host packages — regenerated only via `export build` |
+
+## Trigger Event
+
+Fires before any file write operation. Receives the target path as input and evaluates it against the protected path list from `wazir.manifest.yaml`.
+
+## Logic
+
+1. **Read target path** from tool input payload.
+2. **Load protected paths** from manifest (`wazir.manifest.yaml → protected_paths`).
+3. **Evaluate match** — does the target path fall under any protected path prefix?
+4. **If no match** — write is allowed. Exit `0`.
+5. **If match** — write is blocked. Emit guard decision JSON to stdout. Exit `42`.
+
+```javascript
+// Decision shape
+{ "guard_decision": { "allowed": false, "reason": "protected path: input/" } }
+```
+
+## Configuration
+
+| Parameter | Required | Source | Description |
+|---|---|---|---|
+| `target_path` | Yes | Tool input payload | The file path being written |
+| Protected paths list | Yes | `wazir.manifest.yaml` | `protected_paths` array |
+
+## What Happens on Violation
+
+When a write targets a protected path:
+
+1. Guard emits `{ "guard_decision": { "allowed": false } }` to stdout.
+2. Script exits `42`.
+3. The host rejects the write operation.
+4. The agent receives a block notification.
+5. No write occurs.
+
+The agent should respond to a `42` exit by:
+- Explaining why the write was blocked.
+- Asking the operator if a regeneration flow should be triggered (`export build`) if the intent was to update exports.
+- Proceeding without the write if the intent was a direct edit of a protected file.
+
+> [!WARNING]
+> Exit code `42` is not an error — it is an intentional block. Do not retry the write. Do not attempt to work around the guard by writing to a temporary path and then moving the file.
+
+## Example
+
+**Scenario:** Agent attempts to directly edit a role file.
+
+```
+Agent attempts: Write to roles/executor.md
+
+protected_path_write_guard fires:
+  Input: { "target_path": "roles/executor.md" }
+  Checks against protected_paths: ["input", "roles", "workflows", "schemas", "exports/hosts"]
+  Match found: "roles"
+  Output: { "guard_decision": { "allowed": false, "reason": "protected path: roles/" } }
+  Exit: 42
+
+Host blocks the write.
+Agent receives block notification.
+Agent responds: "roles/executor.md is a protected canonical path and cannot be written directly.
+To modify role contracts, make changes through the maintainer review process."
+```
+
+**Scenario:** Agent writes to an allowed path.
+
+```
+Agent attempts: Write to docs/plans/2026-03-13-design.md
+
+protected_path_write_guard fires:
+  Input: { "target_path": "docs/plans/2026-03-13-design.md" }
+  Checks against protected_paths — no match.
+  Output: { "guard_decision": { "allowed": true } }
+  Exit: 0
+
+Write proceeds normally.
+```
+
+## Testing
+
+```bash
+# Test the guard script directly
+echo '{"target_path": "input/requirements.md"}' | node hooks/protected-path-write-guard
+# Expected exit: 42
+# Expected stdout: {"guard_decision":{"allowed":false,...}}
+
+echo '{"target_path": "docs/plans/my-plan.md"}' | node hooks/protected-path-write-guard
+# Expected exit: 0
+# Expected stdout: {"guard_decision":{"allowed":true}}
+
+# Validate hook definition
+node tooling/src/cli.js validate hooks
+```
+
+## Host Fallback
+
+| Host | Fallback |
+|---|---|
+| Claude | `native_or_wrapper` |
+| Codex | `wrapper_command` |
+| Gemini | `wrapper_command` |
+| Cursor | `native_or_wrapper` |

package/docs/readmes/features/hooks/session-start.md

@@ -0,0 +1,119 @@
+# session_start
+
+> `PreToolUse` · Observability · Initializes run-local status capture and injects the skill bootstrap at every session start.
+
+| Property | Value |
+|---|---|
+| **Hook ID** | `session_start` |
+| **Trigger event** | Session begins |
+| **Failure mode** | `capture` — always exits 0, never blocks the session |
+| **Exit codes** | `0` always |
+| **Script** | `hooks/session-start` |
+
+## What It Guards
+
+`session_start` does two things: it bootstraps skill discovery by injecting the `wz:using-skills` skill content into the agent's system context, and it initializes the run-local `status.json` file that all other capture hooks write to throughout the session.
+
+Without this hook firing correctly:
+- Skills are not auto-discovered — the agent operates without the skill framework.
+- Capture hooks have no status file to append to — observability is broken.
+
+## Trigger Event
+
+Fires once at the start of every session, before any tool or agent response.
+
+## Logic
+
+1. **Resolve skill file** — locate `skills/using-skills/SKILL.md` relative to the hooks directory.
+2. **Read skill content** — read the full `SKILL.md` file.
+3. **Write to stdout** — emit the skill content wrapped in `<EXTREMELY_IMPORTANT>` tags so the host injects it as a system-level instruction.
+4. **Exit 0** — session proceeds regardless of outcome.
+
+If `SKILL.md` is not found:
+1. Write a `<system-reminder>` warning to stdout indicating the skill is missing.
+2. Exit 0 — session proceeds without skill bootstrap.
+
+## Configuration
+
+| Parameter | Source | Description |
+|---|---|---|
+| `project_root` | Runtime (resolved from script location) | Root of the Wazir repo |
+| `run_id` | Runtime (session context) | Unique identifier for this session run |
+| Skill file path | Hardcoded relative: `skills/using-skills/SKILL.md` | Location of the bootstrap skill |
+
+## What Happens on Violation
+
+This hook does not block. It always exits 0. Failure modes:
+
+| Condition | Outcome |
+|---|---|
+| `SKILL.md` not found | Warning emitted to stdout; session proceeds without skill bootstrap |
+| Script parse/runtime error | Error written to stderr; session proceeds |
+
+**Side effects produced:**
+
+| Artifact | Location | Description |
+|---|---|---|
+| `status.json` | `~/.wazir/projects/<slug>/status.json` | Run-local status file, initialized for this session |
+| Skill content | Agent system context | Full `wz:using-skills` skill injected as `<EXTREMELY_IMPORTANT>` |
+
+## Example
+
+**Normal operation:**
+
+```bash
+node hooks/session-start
+# Stdout:
+<EXTREMELY_IMPORTANT>
+You have skills.
+
+**Below is the full content of your 'wz:using-skills' skill:**
+
+---
+name: wz:using-skills
+...
+</EXTREMELY_IMPORTANT>
+```
+
+**Missing skill file:**
+
+```bash
+# After removing skills/using-skills/SKILL.md
+node hooks/session-start
+# Stdout:
+<system-reminder>
+WARNING: wz:using-skills skill not found at /path/to/skills/using-skills/SKILL.md
+The Wazir skill bootstrap is not available. Skills will not be auto-discovered.
+Run: check that skills/using-skills/SKILL.md exists.
+</system-reminder>
+```
+
+## Testing
+
+```bash
+# Verify normal operation
+node hooks/session-start | head -3
+# Expected: <EXTREMELY_IMPORTANT>
+
+# Verify skill content is present
+node hooks/session-start | grep "wz:using-skills"
+# Expected: name: wz:using-skills
+
+# Verify graceful degradation
+mv skills/using-skills/SKILL.md /tmp/SKILL.md.bak
+node hooks/session-start | grep "WARNING"
+# Expected: WARNING: wz:using-skills skill not found
+mv /tmp/SKILL.md.bak skills/using-skills/SKILL.md
+
+# Validate hook definition against schema
+node tooling/src/cli.js validate hooks
+```
+
+## Host Fallback
+
+| Host | Fallback |
+|---|---|
+| Claude | `native_hook` |
+| Codex | `wrapper_command` |
+| Gemini | `wrapper_command` |
+| Cursor | `native_or_wrapper` |