@wazir-dev/cli 1.0.0

package/docs/readmes/features/skills/self-audit.md

@@ -0,0 +1,176 @@
+# self-audit
+
+> Worktree-isolated audit-fix loop for the Wazir project itself. Validates, audits, fixes, verifies, and merges only on all-green. The main worktree is never touched until every check passes.
+
+| Property | Value |
+|---|---|
+| **ID** | `self-audit` |
+| **Type** | Flexible |
+| **Trigger** | `/self-audit` or explicit operator request for a self-audit loop |
+| **Safety guarantee** | Main worktree untouched until all Phase 4 checks pass in isolation |
+
+## Purpose
+
+`self-audit` is `run-audit` with an important difference: it operates on the Wazir project itself, using git worktree isolation to guarantee that fixes are safe before they reach the main working tree. No partial fix state ever lands on main — the worktree is discarded if Phase 4 verification fails.
+
+It also goes beyond a standard audit by running every CLI validation check and performing a deep structural consistency analysis that CLI checks alone cannot catch.
+
+## When to Invoke
+
+- Before a release or major merge.
+- When documentation drift is suspected (roles, workflows, skills out of sync with manifest).
+- After a batch of changes to validate overall project coherence.
+- On a scheduled review cadence.
+- Explicitly: operator invokes `/self-audit`.
+
+## When NOT to Invoke
+
+- You want to audit a non-Wazir codebase — use `run-audit`.
+- You are making a known targeted fix — make the fix directly, then run `wz:verification`.
+
+> [!WARNING]
+> Never run self-audit on the main worktree directly. The skill's safety guarantee depends on worktree isolation. If the isolation step is skipped, fixes may leave the project in a broken intermediate state.
+
+## Worktree Isolation Model
+
+```
+main worktree (untouched throughout)
+  └── agent spawns in isolated git worktree
+        ├── Phase 1: CLI Validation Sweep
+        ├── Phase 2: Deep Structural Audit
+        ├── Phase 3: Fix (auto-fixable issues)
+        ├── Phase 4: Verify (re-run all checks — must be all-green)
+        └── Phase 5: Report + commit in worktree (if green)
+                          ↓
+              caller merges back to main (on green)
+```
+
+If Phase 4 fails: worktree is discarded. Main is unchanged.
+
+## Phase 1: CLI Validation Sweep
+
+Runs every validation check and captures pass/fail:
+
+```bash
+node tooling/src/cli.js validate manifest
+node tooling/src/cli.js validate hooks
+node tooling/src/cli.js validate docs
+node tooling/src/cli.js validate brand
+node tooling/src/cli.js validate runtime
+node tooling/src/cli.js validate changelog
+node tooling/src/cli.js validate commits
+node tooling/src/cli.js doctor --json
+node tooling/src/cli.js export --check
+```
+
+Any failure is a finding that goes into the audit report.
+
+## Phase 2: Deep Structural Audit
+
+Six categories of structural checks that CLI validation does not cover:
+
+| Category | What Is Checked |
+|---|---|
+| Cross-reference consistency | Every manifest role/workflow has a corresponding file; every skill dir has `SKILL.md`; composition map concerns reference existing modules |
+| Documentation drift | `docs/architecture.md` component table vs. actual dirs; `docs/roles-and-workflows.md` vs. manifest; README claims vs. actual state |
+| Export freshness | Generated exports match canonical sources via `export --check` |
+| Schema coverage | Every workflow that produces artifacts has a corresponding schema; all schema files are valid JSON |
+| Hook integrity | Hook scripts in `.claude/settings.json` exist and are executable; hook definitions cover all manifest-required hooks |
+| Skill structure | Each `skills/` directory has well-formed `SKILL.md` with frontmatter; referenced skills exist |
+
+## Phase 3: Fix
+
+For each finding:
+
+| Category | Action |
+|---|---|
+| Auto-fixable | Apply fix directly (missing stubs, stale exports, doc drift, permission issues, schema formatting) |
+| Manual-required | Document in audit report with remediation guidance |
+
+Fix constraints:
+- Never modify `input/` (read-only operator surface)
+- Prefer updating docs to match code (code is truth) unless code is clearly wrong
+- Keep fixes minimal — one concern per change
+
+## Phase 4: Verify
+
+Re-runs the entire Phase 1 CLI sweep. **All checks must pass.**
+
+If any check fails after fixes:
+1. Revert the failing fix.
+2. Document the revert and root cause.
+3. Re-verify.
+4. If still failing, mark as manual-required and proceed with remaining passing checks.
+
+## Phase 5: Report and Commit
+
+Produces a structured report:
+
+```markdown
+# Self-Audit Report — Loop N — 2026-03-13
+
+## Validation Sweep
+| Check    | Before | After |
+|----------|--------|-------|
+| manifest | FAIL   | PASS  |
+| hooks    | PASS   | PASS  |
+
+## Auto-Fixed (2)
+- [F-001] skills/scan-project/SKILL.md missing frontmatter — added name/description fields
+- [F-002] docs/architecture.md component count was 8, actual is 9 — updated count
+
+## Manual Required (1)
+- [M-001] schema for `design_review` workflow missing — create schemas/design-review.schema.json
+
+## Verification
+All checks: PASS
+```
+
+On all-green: commits in the worktree with `fix(self-audit): loop N — <summary>`. Caller merges back.
+
+## Loop Behavior
+
+Multiple loops converge to clean:
+
+```
+Loop 1: finds 5 issues, fixes 4, 1 manual → all checks green → commit
+Loop 2: finds 1 issue (introduced by Loop 1), fixes it → all checks green → commit
+Loop 3: finds 0 issues → project is clean
+```
+
+Each loop runs in a fresh worktree, independent of previous loops.
+
+## Example
+
+**Scenario:** Running self-audit before a 0.2.0 release tag.
+
+```
+Operator: /self-audit
+
+Agent: Spawning isolated worktree for self-audit Loop 1...
+Phase 1: Running CLI validation sweep...
+  validate manifest: PASS
+  validate hooks: FAIL — session_start definition missing loop_cap field
+  validate docs: FAIL — skills count in README is 10, actual is 11
+  ...
+
+Phase 2: Deep structural audit...
+  F-003: skills/using-skills referenced in docs/skills.md but directory has wz:using-skills prefix — DRIFT
+  ...
+
+Phase 3: Fixing auto-fixable issues...
+  F-001: Added loop_cap to session_start.yaml
+  F-002: Updated README skill count to 11
+  F-003: Aligned docs/skills.md reference to match actual skill ID
+
+Phase 4: Re-running validation sweep...
+  All checks: PASS
+
+Phase 5: Committed — fix(self-audit): loop 1 — fix hook schema, skill count drift, doc reference alignment
+
+Worktree ready for merge.
+```
+
+## Integration
+
+`self-audit` is the Wazir equivalent of `run-audit` — it is the loop that keeps the OS kit itself coherent. After merge, the resulting commit can be used as a clean baseline for `prepare-next` handoffs.

package/docs/readmes/features/skills/tdd.md

@@ -0,0 +1,137 @@
+# wz:tdd
+
+> RED → GREEN → REFACTOR. No shortcuts. Every behavioral change earns a failing test first.
+
+| Property | Value |
+|---|---|
+| **ID** | `wz:tdd` |
+| **Type** | Rigid |
+| **Trigger** | Any implementation work that changes behavior |
+| **Failure mode** | Code written without test coverage, or tests rewritten to fit broken behavior |
+
+## Purpose
+
+`wz:tdd` enforces the test-driven development discipline for every behavioral change. It prevents the two most common AI coding failures: (1) confident implementation with no verification path, and (2) retrofitted tests written to confirm broken behavior rather than specify correct behavior. The discipline is the point — it cannot be adapted away.
+
+## When to Invoke
+
+- Implementing any new feature or behavioral change.
+- Fixing a bug where automated verification is feasible.
+- Any task in an implementation plan that changes how code behaves.
+
+> [!TIP]
+> If the implementation plan has been written by `wz:writing-plans`, each plan task becomes a RED → GREEN → REFACTOR cycle. Work through the plan one task at a time.
+
+## When NOT to Invoke
+
+- Pure documentation changes with no code impact.
+- Configuration changes with no behavioral implications.
+- Environments where automated testing is explicitly infeasible (document this explicitly — do not silently skip).
+
+> [!WARNING]
+> "I'll write the tests after" is not TDD. The failing test must exist before the implementation. If you skip RED, you are not following this skill — you are rationalizing around it.
+
+## Phases
+
+### 1. RED
+
+Write or update a test that expresses the new behavior or the bug being fixed.
+
+- The test must **fail** when you run it. Confirm failure explicitly.
+- A test that passes before the implementation is not a test — it is noise.
+- Record the failure output as evidence.
+
+```bash
+npm test -- --grep "new behavior"
+# Must show: 1 failing
+```
+
+### 2. GREEN
+
+Write the **smallest** implementation change that makes the failing test pass.
+
+- Do not write more code than the test requires.
+- Do not solve adjacent problems.
+- Run the test. Confirm it now passes.
+
+```bash
+npm test -- --grep "new behavior"
+# Must show: 1 passing
+```
+
+### 3. REFACTOR
+
+Improve the structure of the implementation without changing behavior.
+
+- Run the full relevant test set after each structural change.
+- All tests must remain green throughout refactor.
+- Stop when the code is clean — do not gold-plate.
+
+```bash
+npm test
+# Must show: all passing
+```
+
+## Rules
+
+| Rule | Enforcement |
+|---|---|
+| Do not skip the failing-test step when automated verification is feasible | RED is mandatory |
+| Do not rewrite tests to fit broken behavior | Tests specify behavior; code must satisfy tests |
+| Rerun verification after each meaningful refactor | REFACTOR must not break GREEN |
+
+## Input
+
+- Implementation plan task (from `wz:writing-plans`)
+- Existing test suite
+- Acceptance criteria from the plan section
+
+## Output
+
+| Artifact | Description |
+|---|---|
+| Failing test (RED) | Test expressing the new behavior, confirmed failing |
+| Passing implementation (GREEN) | Minimum code to satisfy the test |
+| Clean codebase (REFACTOR) | Improved structure with full test suite green |
+
+## Example
+
+**Task from plan:** "Rate limit middleware returns 429 when token bucket is exhausted."
+
+```javascript
+// RED: Write the failing test
+describe('rate-limit middleware', () => {
+  it('returns 429 when token bucket exhausted', async () => {
+    await exhaustBucket('token-abc');
+    const res = await request(app).get('/api/data').set('Authorization', 'Bearer token-abc');
+    expect(res.status).toBe(429);
+    expect(res.headers['retry-after']).toBeDefined();
+  });
+});
+// Run: 1 failing — ReferenceError: exhaustBucket is not defined (or 200 returned)
+```
+
+```javascript
+// GREEN: Write minimum implementation
+// src/middleware/rate-limit.js — add 429 return when bucket empty
+if (tokens <= 0) {
+  res.set('Retry-After', ttl);
+  return res.status(429).json({ error: 'Rate limit exceeded' });
+}
+// Run: 1 passing
+```
+
+```javascript
+// REFACTOR: Extract magic numbers to config
+// Run full suite: all passing
+```
+
+## Integration
+
+`wz:tdd` is the execution engine of the delivery chain:
+
+```
+wz:writing-plans (plan) → wz:tdd (RED/GREEN/REFACTOR per task) → wz:verification (completion proof)
+```
+
+When a test fails unexpectedly during GREEN or REFACTOR, invoke `wz:debugging` to diagnose before continuing.

package/docs/readmes/features/skills/using-skills.md

@@ -0,0 +1,92 @@
+# wz:using-skills
+
+> The skill discovery bootstrap. Fires before any response. Makes every other skill reachable.
+
+| Property | Value |
+|---|---|
+| **ID** | `wz:using-skills` |
+| **Type** | Rigid |
+| **Trigger** | Session start — every new conversation |
+| **Failure mode** | Silent degradation (skills not discovered) |
+
+## Purpose
+
+`wz:using-skills` establishes the rule that skill invocation must happen **before any response** — including clarifying questions. Without this skill firing at session start, an agent may answer confidently from memory instead of consulting the live, current skill definitions. Skills evolve; memory does not.
+
+This skill is not optional scaffolding. It is the enforcement mechanism that makes all other skills reachable and current.
+
+## When to Invoke
+
+- At the start of every session, automatically via the `session-start` hook.
+- Any time there is even a 1% chance another skill applies to the current task.
+
+> [!WARNING]
+> These thoughts indicate you are rationalizing your way out of skill invocation:
+> - "This is just a simple question" — questions are tasks, check for skills.
+> - "I need more context first" — skill check comes BEFORE clarifying questions.
+> - "I remember this skill" — skills evolve. Read the current version.
+> - "I know what that means" — knowing the concept is not the same as invoking the skill.
+
+## When NOT to Invoke
+
+There is no situation where this skill should be suppressed. It is the meta-skill that governs all others.
+
+## Phases
+
+1. **Session hook fires** — the `hooks/session-start` script runs, reads `skills/using-skills/SKILL.md`, and injects the full content into the agent's system context as `<EXTREMELY_IMPORTANT>`.
+2. **Agent receives skill** — the agent now knows the skill invocation rule and the skill priority order.
+3. **On every user message** — agent checks: might any skill apply?
+4. **Invoke Skill tool** — if yes (even 1%), invoke via the `Skill` tool before any other action.
+5. **Announce** — state "Using [skill] to [purpose]".
+6. **Follow the loaded skill** — if the invoked skill has a checklist, create a TodoWrite item per item.
+
+## Input
+
+- Session start event (automatic via hook)
+- Any user message (manual check)
+
+## Output
+
+- Agent operating with current skill definitions loaded
+- Skill invocation announcement before any response
+
+## Example
+
+```
+User: "Help me fix this test that's failing"
+
+Agent (internal): Might a skill apply? "fix failing test" -> wz:debugging (100%)
+Agent: Invoking wz:debugging skill...
+Agent: "Using wz:debugging to diagnose the failing test via observe-hypothesize-test-fix loop."
+[Follows wz:debugging exactly from here]
+```
+
+Without `wz:using-skills` active, the agent might skip straight to guessing the fix — bypassing the disciplined debugging loop entirely.
+
+## Integration
+
+`wz:using-skills` is the gateway skill. It does not perform work itself — it ensures the right skill is invoked for every piece of work:
+
+| Situation | Skill invoked via wz:using-skills |
+|---|---|
+| About to enter plan mode | `wz:brainstorming` (if not yet brainstormed) |
+| Implementation task | `wz:tdd` |
+| Bug / unexpected behavior | `wz:debugging` |
+| Claiming work is done | `wz:verification` |
+| End of session | `prepare-next` |
+
+## Skill Priority Order
+
+1. Process skills (`wz:brainstorming`, `wz:debugging`) — determine HOW to approach.
+2. Implementation skills (`wz:tdd`, `wz:design`) — guide execution.
+
+## Testing
+
+Verify the hook fires correctly:
+
+```bash
+node hooks/session-start
+# Should print: <EXTREMELY_IMPORTANT>You have skills...
+```
+
+If `skills/using-skills/SKILL.md` is missing, the script emits a WARNING and exits 0 — the session proceeds without skill bootstrap.

package/docs/readmes/features/skills/verification.md

@@ -0,0 +1,120 @@
+# wz:verification
+
+> No success claim without fresh evidence from the current change. Evidence means a command you ran, not a command you remember running.
+
+| Property | Value |
+|---|---|
+| **ID** | `wz:verification` |
+| **Type** | Rigid |
+| **Trigger** | Before any claim that work is complete |
+| **Failure mode** | False completion — declaring done without proof, creating silent technical debt |
+
+## Purpose
+
+`wz:verification` closes the loop on every unit of work. AI agents are capable of confidently asserting completion while the implementation is broken, the tests are skipped, or the wrong problem was solved. This skill makes that impossible by requiring a documented proof path — not a plausibility argument — before any completion claim is accepted.
+
+The rule is simple: if you cannot show the output of a command that proves it works, the work is not done.
+
+## When to Invoke
+
+- Before saying "done", "complete", "finished", "working", or any equivalent.
+- After each task in a `wz:writing-plans` implementation plan section.
+- After every `wz:tdd` REFACTOR cycle.
+- After applying a fix from `wz:debugging`.
+- Before handing off to `prepare-next`.
+
+> [!WARNING]
+> "It should work" is not verification. "I tested it earlier" is not verification. "The logic looks correct" is not verification. Only fresh command output from the current change state counts.
+
+## When NOT to Invoke
+
+- You are still mid-implementation (RED or GREEN phase of TDD) — verification applies to completed work.
+- The task is explicitly documentation-only and has no executable verification path — document this explicitly rather than silently skipping.
+
+## Phases
+
+1. **Identify what to verify** — every completion claim must state what is being verified.
+2. **Determine the verification path** — a specific command, or a deterministic manual check if commands are not available.
+3. **Run the verification** — execute it now, against the current state of the change.
+4. **Record the result** — actual output, exit code, or observable outcome.
+5. **Pass or fail** — if pass, the completion claim is valid. If fail, fix and re-verify.
+
+## Input
+
+- The work claimed to be complete
+- The acceptance criteria for that work (from the implementation plan, if one exists)
+
+## Output
+
+A verification record with three required fields:
+
+| Field | Description |
+|---|---|
+| What was verified | The specific behavior, output, or state confirmed |
+| The exact command or check | Reproducible by anyone reading the record |
+| The actual result | Not the expected result — the actual output |
+
+## Verification Record Format
+
+```
+Verified: rate-limit middleware returns 429 when token bucket is exhausted
+Command:  npm test -- --grep "rate-limit returns 429"
+Result:   1 passing (34ms)
+```
+
+## Example
+
+**Scenario:** Implementation plan Section 2 (rate-limit middleware) is complete.
+
+```
+Agent: Invoking wz:verification before claiming Section 2 complete.
+
+What to verify: middleware returns 429 + Retry-After header when bucket exhausted
+Command: npm test -- --grep rate-limit
+Result:
+  rate-limit middleware
+    ✓ allows request when bucket has tokens (12ms)
+    ✓ returns 429 when bucket exhausted (18ms)
+    ✓ sets Retry-After header (8ms)
+  3 passing (38ms)
+
+Section 2: VERIFIED. Proceeding to Section 3.
+```
+
+**Failure scenario:**
+
+```
+Agent: Invoking wz:verification.
+Command: npm test
+Result:
+  1) rate-limit middleware — returns 429 when bucket exhausted
+     AssertionError: expected 200 to equal 429
+
+Verification FAILED. Invoking wz:debugging.
+[Debugging cycle resolves the issue]
+[Re-running verification]
+Command: npm test
+Result: 4 passing
+Verification PASSED. Completion claim now valid.
+```
+
+## When Verification Fails
+
+1. Do not mark the work complete.
+2. Do not adjust the acceptance criteria to match the failure.
+3. Fix the issue — invoke `wz:debugging` if the cause is unclear.
+4. Re-run verification after the fix.
+5. Only claim completion after verification passes.
+
+## Integration
+
+`wz:verification` is the mandatory exit gate for every execution unit:
+
+```
+wz:tdd (GREEN) → wz:verification → move to next task
+wz:tdd (REFACTOR) → wz:verification → section complete
+fix applied → wz:verification → wz:debugging if still failing
+execution phase done → wz:verification → prepare-next
+```
+
+Verification records become the evidence trail in `prepare-next` handoffs and `stop_handoff_harvest` observability data.

package/docs/readmes/features/skills/writing-plans.md

@@ -0,0 +1,104 @@
+# wz:writing-plans
+
+> Transform an approved design into an execution-grade implementation plan — detailed enough that a weaker model can follow it without inventing missing steps.
+
+| Property | Value |
+|---|---|
+| **ID** | `wz:writing-plans` |
+| **Type** | Rigid |
+| **Trigger** | After design approval from `wz:brainstorming` or `run-audit` plan mode |
+| **Failure mode** | Vague plans that force improvisation during execution |
+
+## Purpose
+
+`wz:writing-plans` converts approved intent into a concrete, ordered execution plan. The bar is explicit: the plan must be detailed enough that another agent — potentially a less capable one — can execute it without needing to invent steps, make scope decisions, or guess at acceptance criteria. Ambiguity left in a plan becomes compounding rework during execution.
+
+## When to Invoke
+
+- Immediately after `wz:brainstorming` produces an operator-approved design.
+- After `run-audit` plan mode — when audit findings are approved as a fix basis.
+- When a clarified direction has been approved and implementation is ready to start.
+
+> [!WARNING]
+> Do not invoke this skill without an approved design or approved direction in `docs/plans/`. Writing a plan from an unreviewed design skips the human approval gate and produces work the operator hasn't signed off on.
+
+## When NOT to Invoke
+
+- No approved design exists yet — invoke `wz:brainstorming` first.
+- The task is exploratory research — use `scan-project` or `run-audit` instead.
+- You are mid-execution and already have a plan — do not re-plan, execute.
+
+## Phases
+
+1. **Read the approved design** — from `docs/plans/YYYY-MM-DD-<topic>-design.md`.
+2. **Read current repo state** — understand what already exists vs. what needs to be created or changed.
+3. **Incorporate research findings** — pull in any relevant findings from the discover phase.
+4. **Write the implementation plan** — to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
+5. **Review plan structure** — verify it satisfies all required sections before handing off to execution.
+
+## Input
+
+| Source | Required |
+|---|---|
+| Approved design doc in `docs/plans/` | Yes |
+| Current repo state | Yes |
+| Research findings from discover phase | If available |
+
+## Output
+
+One implementation plan at `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
+
+### Required Plan Sections
+
+| Section | Content |
+|---|---|
+| Ordered sections | Logical execution sequence with no gaps |
+| Concrete tasks and subtasks | Specific, unambiguous actions |
+| Acceptance criteria per section | How to know each section is done |
+| Verification commands | Exact commands or manual checks per section |
+| Cleanup steps | Temp files, stubs, or scaffolding to remove |
+
+## Example
+
+**Scenario:** Design for Redis token-bucket rate limiting has been approved.
+
+```
+Plan: docs/plans/2026-03-13-rate-limiting-implementation.md
+
+## Section 1: Redis client setup
+- Task: Install ioredis (npm install ioredis)
+- Task: Create src/lib/redis-client.js with connection config from env
+- Acceptance: `node -e "require('./src/lib/redis-client')"` exits 0
+- Verification: `npm test -- --grep redis-client`
+
+## Section 2: Rate limit middleware
+- Task: Create src/middleware/rate-limit.js implementing token bucket
+  - Subtask: Read token count from Redis key `ratelimit:{token}`
+  - Subtask: Decrement and set TTL atomically via Lua script
+  - Subtask: Return 429 with Retry-After header when exhausted
+- Acceptance: Unit tests cover allow / deny / TTL-reset scenarios
+- Verification: `npm test -- --grep rate-limit`
+
+## Section 3: Wire middleware to router
+...
+
+## Cleanup
+- Remove TODO comment in src/api/router.js added in Section 3
+```
+
+## Rules
+
+- Do not write repo-local task files outside `docs/plans/`.
+- Do not rely on retired `run-*` workflow wrappers.
+- Make tasks concrete enough that no invention is needed during execution.
+
+## Integration
+
+`wz:writing-plans` sits in the middle of the delivery chain:
+
+```
+wz:brainstorming → [operator approval] → wz:writing-plans → wz:tdd
+                                                          → wz:verification (after execution)
+```
+
+Plans produced here are the direct input to the `execute` phase. The `wz:tdd` skill consumes the plan task-by-task, writing a failing test for each task before implementing it.