@bookedsolid/rea 0.1.0

package/agents/typescript-specialist.md

@@ -0,0 +1,111 @@
+---
+name: typescript-specialist
+description: TypeScript specialist enforcing strict mode, type system design, declaration files, and type safety across the codebase
+---
+
+# TypeScript Specialist
+
+You are the TypeScript specialist for this project.
+
+## Project Context Discovery
+
+Before acting, read:
+
+- `package.json` — TypeScript version, build scripts
+- `tsconfig.json` — strict flags, path aliases, lib targets
+- Framework config (`astro.config.*`, `next.config.*`, etc.)
+- `.rea/policy.yaml` — autonomy level and constraints
+- Existing type patterns in the codebase
+
+Adapt to the project's actual TypeScript configuration and conventions.
+
+## Your Role
+
+- Enforce `"strict": true` across all code
+- Design type interfaces for components, API responses, content collections
+- Resolve type errors in framework frontmatter, components, and web component consumption
+- Ensure component library types work correctly in JSX/TSX contexts
+- Manage `HTMLElementTagNameMap` declarations for custom elements
+
+## Standards
+
+- Zero `any` — use `unknown` + type guards when the type is truly unknown
+- Zero `@ts-ignore` / `@ts-expect-error` — fix the type, don't suppress
+- Prefer `interface` over `type` for object shapes (better extension)
+- Use `satisfies` for type-safe object literals with inference
+- Use discriminated unions for variant types
+- Use `readonly` for arrays/tuples that should not mutate
+- Use `import type` for type-only imports
+- Export types from barrel files only when consumed externally
+
+## Common Patterns
+
+### Framework Component Props
+
+```typescript
+interface Props {
+  title: string;
+  description?: string;
+  class?: string;
+}
+
+const { title, description, class: className } = Astro.props;
+```
+
+### React Component Props
+
+```typescript
+interface ServiceCardProps {
+  title: string;
+  description: string;
+  icon: IconDefinition;
+  features: readonly string[];
+}
+```
+
+### Custom Element Types
+
+```typescript
+declare namespace astroHTML.JSX {
+  interface IntrinsicElements {
+    'my-button': Record<string, unknown>;
+    'my-nav': Record<string, unknown>;
+  }
+}
+```
+
+### Unknown Narrowing
+
+```typescript
+function isServiceCard(value: unknown): value is ServiceCardProps {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'title' in value &&
+    typeof (value as { title: unknown }).title === 'string'
+  );
+}
+```
+
+## Constraints
+
+- NEVER use `any` — no exceptions
+- NEVER use `@ts-ignore` or `@ts-expect-error` without a linked issue and sunset date
+- NEVER use non-null assertions (`!`) without proving safety
+- NEVER use `object` or `Function` or `{}` as types — use `Record<string, unknown>` or proper interfaces or specific signatures
+- ALWAYS use `readonly` for arrays/tuples that shouldn't mutate
+- ALWAYS type function parameters explicitly on public APIs
+
+## Zero-Trust Protocol
+
+1. Read before writing
+2. Never trust LLM memory — verify via tools, git, file reads
+3. Verify before claiming
+4. Validate dependencies — `npm view` before install
+5. Graduated autonomy — respect L0–L3 from `.rea/policy.yaml`
+6. HALT compliance — check `.rea/HALT` before any action
+7. Audit awareness — every tool call may be logged
+
+---
+
+_Part of the [rea](https://github.com/bookedsolidtech/rea) agent team._

package/commands/codex-review.md

@@ -0,0 +1,104 @@
+---
+description: Run an adversarial review of the current branch via the Codex plugin (GPT-5.4). First-class step in the REA engineering process.
+argument-hint: "[diff-target]"
+allowed-tools:
+  - Bash(git diff:*)
+  - Bash(git log:*)
+  - Bash(git branch:*)
+  - Bash(git rev-parse:*)
+  - Read
+---
+
+# /codex-review — Adversarial Review via Codex
+
+Invokes the Codex plugin (`/codex adversarial-review`) on the current branch's diff, captures the result, and records it to the REA audit log. Adversarial review by an independent model (GPT-5.4) is a **first-class, non-optional step** in the REA engineering process — it is the counterweight to Opus-authored code.
+
+## Why this exists
+
+The default workflow in REA is Plan → Build → Review, with the Review leg handed to a different model than the one that wrote the code. Codex adversarial review is free, fast, and independent — it catches the mistakes the authoring model is most likely to miss: security assumptions, correctness under edge cases, and logical gaps in tests. Treat it with the same weight as a human second set of eyes.
+
+## Arguments
+
+- `$ARGUMENTS` (optional) — diff target, same semantics as `/review`. Defaults to `main`.
+
+## Preflight
+
+1. Read `.rea/policy.yaml` — confirm autonomy is at least L1
+2. Check `.rea/HALT` — if present, stop and report FROZEN
+3. Verify the Codex plugin is installed. If `/codex` is not available in this Claude Code install, report: "Codex plugin not installed. See https://github.com/openai/codex for install steps." and stop.
+
+## Step 1 — Resolve the diff target
+
+Same logic as `/review`:
+
+- Empty `$ARGUMENTS` → `main`
+- Otherwise → use the provided ref
+
+Capture:
+
+- Current branch name (`git rev-parse --abbrev-ref HEAD`)
+- Head SHA (`git rev-parse HEAD`)
+- Diff target SHA (`git rev-parse <target>`)
+- Commit log from target to HEAD
+
+If the diff is empty, stop and report: "No changes to review against `<target>`."
+
+## Step 2 — Delegate to codex-adversarial agent
+
+Invoke the `codex-adversarial` agent with:
+
+- The diff target and head SHA
+- The branch name
+- The commit log summary
+- The full diff text
+
+The agent wraps `/codex adversarial-review` and returns structured findings.
+
+## Step 3 — Record to audit log
+
+Every Codex invocation produces an audit entry. The `codex-adversarial` agent writes it via the middleware chain automatically, but verify the entry was recorded:
+
+```bash
+tail -n 1 .rea/audit.jsonl
+```
+
+The entry must include:
+
+- `tool: "codex-adversarial-review"`
+- `head_sha: <SHA>`
+- `target: <ref>`
+- `finding_count: <N>`
+- `verdict: pass | concerns | blocking`
+
+If the audit entry is missing, report it clearly — do not proceed as if the review happened.
+
+## Step 4 — Report
+
+Print a summary:
+
+```
+/codex-review — <branch> vs <target>
+Head SHA:    <SHA>
+Verdict:     pass | concerns | blocking
+Findings:    <total>
+Audit:       .rea/audit.jsonl:<entry-index>
+
+<grouped findings>
+```
+
+If the verdict is `blocking`, state plainly: "Do not merge until the blocking findings are addressed."
+
+## Pre-merge usage
+
+The recommended BST workflow runs `/codex-review` twice:
+
+1. After implementation, on the feature branch — catches issues early
+2. Immediately before merge, on the PR branch — records a fresh audit entry that the `push-review-gate` hook can check for freshness
+
+Both invocations are cheap. Run both.
+
+## Constraints
+
+- Read-only with respect to source files. Writes only to `.rea/audit.jsonl` (via middleware).
+- Never silently fails. If Codex is unavailable, unresponsive, or returns an error, surface it to the user and record the failure in audit.
+- Never retries automatically on non-deterministic Codex errors — surface and let the user decide.

package/commands/freeze.md

@@ -0,0 +1,81 @@
+---
+description: Activate the REA kill switch — writes .rea/HALT with a reason, blocking all governed tool calls until unfrozen
+argument-hint: "<reason>"
+allowed-tools:
+  - Bash(npx rea freeze:*)
+---
+
+# /freeze — Activate the Kill Switch
+
+Writes `.rea/HALT` with a timestamped reason. Once frozen, every REA-governed tool call (native MCP, proxied downstream, and hook-gated) refuses to execute until `npx rea unfreeze` is run.
+
+Use this when:
+
+- You see the agent doing something unexpected and you want to stop it immediately
+- You are handing the session off and want to be sure nothing runs unattended
+- A hook or middleware is misbehaving and you need to isolate the problem
+- You are about to do something outside the normal governance envelope and want an obvious tripwire
+
+## Arguments
+
+- `$ARGUMENTS` (required) — a short reason (one sentence). If empty, prompt the user for one before proceeding. Never freeze without a reason.
+
+## Preflight
+
+1. Read `.rea/policy.yaml` — confirm REA is installed. If missing, report "REA not initialized" and stop.
+2. Check whether `.rea/HALT` already exists. If it does, show the existing reason and ask whether to overwrite.
+
+## Step 1 — Validate the reason
+
+- If `$ARGUMENTS` is empty or whitespace, prompt: "Reason is required. Describe why you are freezing this session."
+- If the reason is a placeholder like "test", "asdf", or "freeze", confirm with the user — the reason ends up in the audit log and should be meaningful.
+
+## Step 2 — Invoke the freeze CLI
+
+```bash
+npx rea freeze --reason "$ARGUMENTS"
+```
+
+This command:
+
+1. Writes `.rea/HALT` with a JSON payload: `{ reason, timestamp, invoker: "slash-command" }`
+2. Appends an entry to `.rea/audit.jsonl`
+3. Returns exit code 0 on success, non-zero on failure
+
+## Step 3 — Confirm
+
+Print the confirmation plainly:
+
+```
+REA session FROZEN
+  Reason:    <reason>
+  Timestamp: <ISO-8601>
+  HALT file: .rea/HALT
+
+All governed tool calls are now blocked. To resume: npx rea unfreeze
+```
+
+## Behavior under HALT
+
+Once `.rea/HALT` is present:
+
+- Every hook checks `hooks/_lib/halt-check.sh` at its top and exits non-zero (blocked)
+- Every middleware invocation checks `kill-switch` first and refuses
+- Slash commands that take actions (not read-only status commands) report FROZEN and refuse to proceed
+- `/rea` continues to work — it is read-only and needs to be able to report the frozen state
+
+## Unfreezing
+
+Unfreezing is explicit and requires its own command:
+
+```bash
+npx rea unfreeze --reason "<why it is safe to resume>"
+```
+
+The slash-command variant is not provided on purpose — unfreezing should be a deliberate CLI action, not a one-keystroke reflex.
+
+## Constraints
+
+- Writes only to `.rea/HALT` and `.rea/audit.jsonl`. Never modifies policy, source files, or git state.
+- Does not auto-unfreeze on any condition. HALT is sticky.
+- If the CLI is unavailable, fall back to writing the HALT file directly with `printf`, but record this in the audit log as a CLI-unavailable fallback.

package/commands/halt-check.md

@@ -0,0 +1,120 @@
+---
+description: Smoke test — verify every hook and middleware respects the HALT kill switch. Advisory, read-only.
+allowed-tools:
+  - Bash(npx rea check:*)
+  - Bash(ls:*)
+  - Read
+---
+
+# /halt-check — Kill Switch Smoke Test
+
+Verifies that the REA HALT kill switch is actually enforced end-to-end: hooks check for `.rea/HALT` at their top, middleware short-circuits on kill-switch, and governed tool calls are denied when the file is present. Run this after any change to hooks, middleware, or `.claude/settings.json`. Run it at least once per release.
+
+This command is **advisory and read-only**. It writes a temporary HALT file, observes behavior, and removes it — but the observation is all through safe, declarative checks. It never issues destructive tool calls to probe the system.
+
+## Preflight
+
+1. Read `.rea/policy.yaml` — confirm REA is installed
+2. Check if `.rea/HALT` already exists. If it does, report "Session already frozen — cannot run smoke test without disturbing existing HALT. Unfreeze first." and stop.
+3. Verify the user has permission — this is an L1+ operation because it writes `.rea/HALT` (briefly).
+
+## Step 1 — Baseline check
+
+Before writing HALT, capture the baseline:
+
+```bash
+npx rea check --json
+```
+
+Record:
+
+- `halt_present: false` (must be)
+- `autonomy_level`
+- `profile`
+- `hook_count` from `.claude/settings.json`
+- `middleware_enabled` list
+
+If the baseline reports `halt_present: true`, stop — the smoke test requires a clean starting state.
+
+## Step 2 — Write the test HALT
+
+```bash
+printf '{"reason":"halt-check smoke test","timestamp":"%s","invoker":"halt-check"}\n' "$(date -u +%FT%TZ)" > .rea/HALT
+```
+
+Confirm the file exists and is readable:
+
+```bash
+ls -la .rea/HALT
+```
+
+## Step 3 — Verify denial paths
+
+Run the diagnostic CLI which simulates representative tool calls through the middleware without actually executing them:
+
+```bash
+npx rea check --simulate
+```
+
+Expected output: each simulated call returns `denied: kill-switch`. Record the results.
+
+Then inspect the hook library — every hook should source `hooks/_lib/halt-check.sh`:
+
+```bash
+for hook in .claude/hooks/*.sh; do
+  if ! grep -q 'halt-check.sh' "$hook"; then
+    echo "MISSING HALT CHECK: $hook"
+  fi
+done
+```
+
+Any hook that does not source `halt-check.sh` is a finding.
+
+## Step 4 — Remove the test HALT
+
+```bash
+rm .rea/HALT
+```
+
+Then verify removal:
+
+```bash
+npx rea check --json | grep halt_present
+```
+
+Must report `halt_present: false`.
+
+## Step 5 — Report
+
+Print a structured result:
+
+```
+/halt-check — HALT smoke test
+  Baseline:           clean (halt_present=false)
+  HALT written:       ok
+  Middleware denial:  <N of M> layers returned denied
+  Hook coverage:      <N of M> hooks source halt-check.sh
+  HALT removed:       ok
+  Final state:        clean
+
+Missing coverage:
+  - <list of hooks without halt-check.sh, if any>
+
+Middleware gaps:
+  - <list of layers that did not short-circuit, if any>
+
+Verdict: PASS | CONCERNS | FAIL
+```
+
+## Failure modes
+
+- **Any hook missing halt-check.sh** → FAIL. Hooks that do not check HALT can run during a frozen session.
+- **Any middleware layer that executes past kill-switch** → FAIL. The ordering guarantee is the whole point.
+- **`.rea/HALT` removal fails** → FAIL loudly. Do not exit until the file is cleaned up. Instruct the user to remove it manually if needed.
+- **CLI unavailable** → CONCERNS, not FAIL. The shell-based hook audit still runs.
+
+## Constraints
+
+- Never destructive. The only file written and removed is `.rea/HALT`.
+- Never issues real tool calls during the test — only `--simulate` through the CLI. Real tool calls would pollute the audit log with denied entries and could have side effects if a hook does not correctly short-circuit.
+- Always cleans up, even on partial failure. If cleanup fails, exit non-zero and print the cleanup instruction prominently.

package/commands/rea.md

@@ -0,0 +1,52 @@
+---
+description: Print REA session status — autonomy level, HALT state, policy profile, and recent audit entries
+allowed-tools:
+  - Bash(npx rea check:*)
+  - Read
+---
+
+# /rea — Session Status
+
+Prints a concise status overview of the REA governance layer for the current project. Use this at the start of a session, after policy changes, or whenever you need to confirm the runtime posture before acting.
+
+## What it reports
+
+- **Autonomy level** — current `autonomy_level` from `.rea/policy.yaml` (L0–L3) and the `max_autonomy_level` ceiling
+- **HALT status** — whether `.rea/HALT` exists (FROZEN vs. ACTIVE) and, if frozen, the reason
+- **Policy profile** — the active profile (e.g. `bst-internal`, `client-engagement`, `minimal`)
+- **Blocked paths** — paths the middleware chain refuses to touch
+- **Attribution gating** — `block_ai_attribution` on/off
+- **Recent audit entries** — last 5 entries from `.rea/audit.jsonl` with tool name, decision, and timestamp
+
+## Behavior
+
+1. Invoke the CLI: `npx rea check`
+2. Render the output verbatim — do not interpret, summarize, or add commentary unless the user asks
+3. If `.rea/policy.yaml` is missing, report: "REA not initialized in this project. Run `npx rea init` to scaffold."
+4. If `.rea/HALT` exists, highlight the FROZEN state prominently — the user needs to see this first
+
+## Constraints
+
+- Read-only. This command never writes to `.rea/` or any project file.
+- If the CLI is not available (`npx rea check` fails), report the error and suggest `pnpm install` or `npm install -g @bookedsolid/rea`.
+- Never print the contents of `audit.jsonl` beyond what `npx rea check` surfaces — the audit log may contain redacted payloads and should be accessed through the CLI, not directly.
+
+## Typical output shape
+
+```
+REA Status
+  Profile:           bst-internal
+  Autonomy:          L1 (ceiling L2)
+  HALT:              ACTIVE (unfrozen)
+  Attribution gate:  enforced
+  Blocked paths:     .env, .env.*, .rea/, node_modules/
+
+Recent audit (last 5):
+  2026-04-18T10:42:11Z  Bash              allowed
+  2026-04-18T10:41:58Z  Write             allowed
+  2026-04-18T10:41:22Z  Edit              denied (blocked-paths)
+  2026-04-18T10:40:03Z  mcp__helixir__*   allowed
+  2026-04-18T10:39:47Z  Bash              allowed
+```
+
+If the user wants more detail, point them at `npx rea check --verbose` or `npx rea doctor`.

package/commands/review.md

@@ -0,0 +1,79 @@
+---
+description: Run the code-reviewer agent against the current branch's diff and produce structured findings
+argument-hint: "[diff-target]"
+allowed-tools:
+  - Bash(git diff:*)
+  - Bash(git log:*)
+  - Bash(git branch:*)
+  - Bash(git status:*)
+  - Read
+---
+
+# /review — Code Review on Current Changes
+
+Invokes the `code-reviewer` agent on the uncommitted and/or branched changes in the current working tree. Use this as a first-pass quality gate before you open a PR.
+
+## Arguments
+
+- `$ARGUMENTS` (optional) — diff target. Defaults to `main`. Examples:
+  - `/review` → diff against `main`
+  - `/review staging` → diff against `staging`
+  - `/review HEAD~3` → diff against three commits back
+  - `/review --staged` → only staged changes
+
+## Preflight
+
+1. Read `.rea/policy.yaml` — confirm autonomy is at least L1 (review is read-only, so L0 also permitted)
+2. Check `.rea/HALT` — if present, stop and report FROZEN
+3. Verify you are inside a git repo: `git rev-parse --show-toplevel`
+
+## Step 1 — Gather the diff
+
+Resolve the diff target:
+
+- If `$ARGUMENTS` is empty → use `main`
+- If `$ARGUMENTS` starts with `--staged` → use `git diff --staged`
+- Otherwise → use `git diff $ARGUMENTS...HEAD`
+
+Run in parallel:
+
+```bash
+git diff <target>...HEAD
+git log <target>..HEAD --oneline
+git status --short
+```
+
+If the diff is empty, stop and report: "No changes to review against `<target>`."
+
+## Step 2 — Delegate to code-reviewer
+
+Invoke the `code-reviewer` agent with:
+
+- **Tier**: `standard` (default). For diffs over 500 lines or cross-module changes, escalate to `senior`.
+- **Context**: the full diff, the commit log, and the current branch name
+- **Project config**: pass paths to `package.json`, `tsconfig.json`, and `.rea/policy.yaml` so the reviewer can adapt to the project's standards
+
+Prompt shape for the delegation:
+
+> Review the following git diff at tier `<standard|senior>`. Produce structured findings:
+> each finding has file, line, severity (high/medium/low), issue, and suggestion_code when applicable.
+> Output JSON array. Empty array if no findings. Diff follows.
+
+## Step 3 — Summarize
+
+Print a clean summary:
+
+```
+/review — <branch> vs <target>
+Files changed: <N>
+Findings: <total> (<high> high, <medium> medium, <low> low)
+
+<grouped findings by severity, most severe first>
+```
+
+If the user asks "post this to a PR", invoke `/review-pr <PR#>` instead — that is the PR-posting variant and requires a PR number.
+
+## Constraints
+
+- Read-only. Never writes to files, never creates commits, never pushes.
+- If `code-reviewer` returns invalid JSON, report the raw output and stop — do not retry automatically.

package/dist/cli/check.d.ts

@@ -0,0 +1 @@
+export declare function runCheck(): void;

package/dist/cli/check.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import { loadPolicy } from '../policy/loader.js';
+import { AUDIT_FILE, HALT_FILE, POLICY_FILE, err, exitWithMissingPolicy, log, reaPath, } from './utils.js';
+const AUDIT_TAIL_LINES = 5;
+function readLastLines(filePath, n) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const lines = content.split('\n').filter((line) => line.length > 0);
+        return lines.slice(-n);
+    }
+    catch {
+        return [];
+    }
+}
+export function runCheck() {
+    const baseDir = process.cwd();
+    const policyPath = reaPath(baseDir, POLICY_FILE);
+    const haltPath = reaPath(baseDir, HALT_FILE);
+    const auditPath = reaPath(baseDir, AUDIT_FILE);
+    if (!fs.existsSync(policyPath)) {
+        exitWithMissingPolicy(policyPath);
+    }
+    let policy;
+    try {
+        policy = loadPolicy(baseDir);
+    }
+    catch (e) {
+        err(`Failed to parse policy: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+    console.log('');
+    log(`Status — ${baseDir}`);
+    console.log('');
+    console.log(`  Profile:              ${policy.profile}`);
+    console.log(`  Autonomy level:       ${policy.autonomy_level}`);
+    console.log(`  Max autonomy:         ${policy.max_autonomy_level}`);
+    console.log(`  Block AI attribution: ${policy.block_ai_attribution ? 'yes' : 'no'}`);
+    console.log(`  Blocked paths:        ${policy.blocked_paths.length} entries`);
+    if (fs.existsSync(haltPath)) {
+        const reason = fs.readFileSync(haltPath, 'utf8').trim();
+        console.log('');
+        console.log('  HALT: ACTIVE');
+        console.log(`        ${reason}`);
+        console.log('        Run `rea unfreeze` to resume.');
+    }
+    else {
+        console.log(`  HALT:                 inactive`);
+    }
+    console.log('');
+    if (fs.existsSync(auditPath)) {
+        const tail = readLastLines(auditPath, AUDIT_TAIL_LINES);
+        if (tail.length === 0) {
+            console.log(`  Audit log:            .rea/audit.jsonl (empty)`);
+        }
+        else {
+            console.log(`  Audit log:            last ${tail.length} entries (.rea/audit.jsonl)`);
+            for (const entry of tail) {
+                console.log(`    ${entry.slice(0, 160)}${entry.length > 160 ? '…' : ''}`);
+            }
+        }
+    }
+    else {
+        console.log(`  Audit log:            not yet written`);
+    }
+    console.log('');
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1 @@
+export declare function runDoctor(): void;