npm - @matt82198/aesop - Versions diffs - 0.1.0 → 0.3.1 - Mend

@matt82198/aesop 0.1.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (130) hide show

package/CHANGELOG.md +117 -2
package/README.md +59 -218
package/bin/cli.js +168 -41
package/daemons/run-watchdog.sh +16 -4
package/daemons/selfheal.sh +231 -0
package/docs/ANY-REPO.md +427 -0
package/docs/CONTRIBUTING.md +72 -0
package/docs/DEMO.md +334 -0
package/docs/HOOK-INSTALL.md +15 -56
package/docs/INSTALL.md +74 -4
package/docs/PORTING.md +166 -0
package/docs/README.md +33 -3
package/docs/TEAM-STATE.md +372 -0
package/docs/reproduce.md +33 -3
package/driver/CLAUDE.md +150 -0
package/driver/README.md +383 -0
package/driver/aesop.config.example.json +80 -0
package/driver/agent_driver.py +355 -0
package/driver/backend_config.py +253 -0
package/driver/claude_code_driver.py +198 -0
package/driver/codex_driver.py +673 -0
package/driver/openai_compatible_driver.py +249 -0
package/driver/openai_transport.py +179 -0
package/driver/verification_policy.py +75 -0
package/driver/wave_bridge.py +254 -0
package/driver/wave_loop.py +1408 -0
package/driver/wave_scheduler.py +890 -0
package/hooks/pre-push-policy.sh +131 -33
package/mcp/server.mjs +320 -4
package/monitor/collect-signals.mjs +69 -0
package/package.json +22 -14
package/skills/CLAUDE.md +132 -2
package/skills/buildsystem/SKILL.md +330 -0
package/skills/buildsystem/wave-flat-dispatch.template.mjs +658 -0
package/skills/fleet/SKILL.md +113 -0
package/skills/power/SKILL.md +246 -131
package/state_store/__init__.py +4 -2
package/state_store/api.py +19 -4
package/state_store/coordination.py +209 -0
package/state_store/identity.py +51 -0
package/state_store/projections.py +63 -0
package/state_store/read_api.py +156 -0
package/state_store/store.py +185 -73
package/state_store/write_api.py +462 -0
package/templates/wave-presets/data.json +65 -0
package/templates/wave-presets/library.json +65 -0
package/templates/wave-presets/saas.json +64 -0
package/tools/audit_report.py +388 -0
package/tools/bench_runner.py +100 -3
package/tools/ci_merge_wait.py +256 -35
package/tools/ci_workflow_lint.py +430 -0
package/tools/claudemd_drift.py +394 -0
package/tools/claudemd_lint.py +359 -0
package/tools/common.py +39 -3
package/tools/cost_ceiling.py +166 -43
package/tools/cost_econ.py +480 -0
package/tools/cost_projection.py +559 -0
package/tools/crossos_drift.py +394 -0
package/tools/defect_escape.py +252 -0
package/tools/doctor.js +1 -1
package/tools/eod_sweep.py +188 -26
package/tools/fleet.js +260 -0
package/tools/fleet_ledger.py +209 -7
package/tools/git_identity_check.py +315 -0
package/tools/health-score.js +40 -0
package/tools/health_score.py +361 -0
package/tools/metrics_gate.py +13 -4
package/tools/mutation_test.py +523 -0
package/tools/portability_check.py +206 -0
package/tools/proposals.mjs +47 -2
package/tools/reconcile.py +7 -4
package/tools/reproduce.js +405 -0
package/tools/secret_scan.py +207 -65
package/tools/self_stats.py +20 -0
package/tools/stall_check.py +247 -16
package/tools/stateapi_lint.py +325 -0
package/tools/test_battery.py +173 -0
package/tools/transcript_digest.py +380 -0
package/tools/verify_activity_filter.py +437 -0
package/tools/verify_agent_inspector.py +2 -0
package/tools/verify_cost_panel.py +345 -0
package/tools/verify_dash.py +2 -0
package/tools/verify_dispatch_panel.py +301 -0
package/tools/verify_failure_drilldown.py +188 -0
package/tools/verify_prboard.py +2 -0
package/tools/verify_scorecards.py +281 -0
package/tools/verify_submit_encoding.py +2 -0
package/tools/verify_ui_trio.py +409 -0
package/tools/verify_wave_telemetry.py +268 -0
package/tools/wave_backlog_analyzer.py +490 -0
package/tools/wave_ledger_hook.py +150 -0
package/tools/wave_preflight.py +779 -0
package/tools/wave_resume.py +215 -0
package/tools/wave_templates.py +340 -0
package/ui/agents.py +68 -14
package/ui/collectors.py +81 -55
package/ui/config.py +7 -2
package/ui/cost.py +231 -12
package/ui/handler.py +383 -55
package/ui/quality_scorecard.py +232 -0
package/ui/sse.py +3 -3
package/ui/wave_audit_tail.py +213 -0
package/ui/wave_dispatch.py +280 -0
package/ui/wave_failure.py +288 -0
package/ui/wave_gantt.py +152 -0
package/ui/wave_reasoning_tail.py +176 -0
package/ui/wave_telemetry.py +383 -0
package/ui/web/dist/assets/index-CNQxaiOW.css +1 -0
package/ui/web/dist/assets/index-CP68RIh3.js +9 -0
package/ui/web/dist/index.html +2 -2
package/bin/CLAUDE.md +0 -76
package/daemons/CLAUDE.md +0 -36
package/dash/CLAUDE.md +0 -32
package/docs/archive/README.md +0 -3
package/docs/archive/spikes/tiered-cognition/ACTIVATION.md +0 -125
package/docs/archive/spikes/tiered-cognition/DESIGN.md +0 -287
package/docs/archive/spikes/tiered-cognition/FINDINGS.md +0 -113
package/docs/archive/spikes/tiered-cognition/README.md +0 -27
package/docs/archive/spikes/tiered-cognition/aesop-cognition.example.md +0 -32
package/docs/archive/spikes/tiered-cognition/force-model-policy.merged.mjs +0 -673
package/docs/archive/spikes/tiered-cognition/strip-tools-hook.mjs +0 -434
package/hooks/CLAUDE.md +0 -89
package/mcp/CLAUDE.md +0 -213
package/monitor/CLAUDE.md +0 -40
package/scan/CLAUDE.md +0 -30
package/state_store/CLAUDE.md +0 -39
package/tools/CLAUDE.md +0 -79
package/ui/CLAUDE.md +0 -127
package/ui/web/dist/assets/index-0qQYnvMC.js +0 -9
package/ui/web/dist/assets/index-BdIlFieV.css +0 -1

package/ui/web/dist/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Aesop Fleet Dashboard</title>
     <script>window.__AESOP_CSRF_TOKEN__ = __AESOP_CSRF_SENTINEL__;</script>
-    <script type="module" crossorigin src="/assets/index-0qQYnvMC.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BdIlFieV.css">
+    <script type="module" crossorigin src="/assets/index-CP68RIh3.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CNQxaiOW.css">
   </head>
   <body>
     <div id="root"></div>

package/bin/CLAUDE.md DELETED Viewed

@@ -1,76 +0,0 @@
-# bin/ — CLI scaffolder
-**Purpose**: Node.js CLI entry point that clones the aesop orchestration template into a target directory with idempotent validation, plus an interactive onboarding wizard for new adopters.
-## Invocation
-- **npm registry**: `npx @matt82198/aesop [target-dir]` (default: `aesop-fleet`)
-- **Local dev**: `node bin/cli.js [target-dir]`
-- **Help**: `npx @matt82198/aesop --help` or `-h`
-- **Interactive wizard**: `npx @matt82198/aesop wizard` (on a TTY, prompts; with `--yes`, uses defaults)
-## Runtime subcommands
-cli.js dispatches runtime management subcommands to `tools/{subcommand}.js`:
-- **`aesop doctor`** (or `node bin/cli.js doctor`) — Preflight readiness check; validates Node.js, Python, git, config, directories, hooks, and dashboard port availability.
-- **`aesop watch`** (or `node bin/cli.js watch`) — Launch the watchdog daemon; spawns `daemons/run-watchdog.sh` for continuous fleet monitoring.
-- **`aesop dash`** (or `node bin/cli.js dash`) — Launch the web dashboard; spawns `python ui/serve.py` to serve realtime fleet status at localhost:8770 (default).
-- **`aesop status`** (or `node bin/cli.js status`) — One-shot fleet status snapshot; displays heartbeats, dashboard port, and git branch status.
-## What gets copied
-Files in `filesToCopy` array (cli.js lines 239–256):
-- **Directories**: `daemons/`, `dash/`, `monitor/`, `tools/`, `ui/`, `docs/`, `state_store/`, `skills/`, `mcp/`, `scan/`, `hooks/`
-- **Files**: `aesop.config.example.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, `CLAUDE-TEMPLATE.md`
-- **Brain templates** (in docs/): `MEMORY-TEMPLATE.md` (via docs/ directory copy)
-## What does NOT get copied
-- `aesop.config.json` (users must `cp aesop.config.example.json` and edit)
-- `state/` (runtime durable state, git-ignored, created by daemons)
-- `.git/`, `node_modules/`, build artifacts
-## Post-scaffold guidance
-Scaffolder prints steps for users:
-1. `cd target-dir && cp aesop.config.example.json aesop.config.json`
-2. Edit config with paths and repos
-3. Initialize brain: `cp CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md` (edit)
-4. Initialize memory: `cp docs/MEMORY-TEMPLATE.md ~/.claude/MEMORY.md` (edit)
-5. Test daemon: `bash daemons/run-watchdog.sh --once`
-6. Launch dashboard: `python ui/serve.py`
-## Interactive wizard (`aesop wizard`)
-The wizard mode provides an interactive onboarding flow for new adopters, guiding them through fleet setup in ~60 seconds:
-1. **Trigger**: `npx @matt82198/aesop wizard` on a TTY (interactive terminal)
-2. **Questions** (all have sensible defaults, press Enter-Enter-Enter to skip):
-   - Project name (default: "my-fleet")
-   - Repos to watch (auto-discovers git repos under `~`, offers choices)
-   - Dashboard port (default: 8770, validates 1–65535)
-   - Brain root directory (default: `~/.claude`)
-3. **Output**:
-   - Scaffolds template files
-   - Generates CLAUDE.md (substituted with project name)
-   - Generates aesop.config.json (with discovered repos)
-   - Prints "next 3 commands" epilogue
-   - Offers to run `watchdog --once` smoke test immediately
-4. **Non-interactive mode** (`--yes` flag or non-TTY stdin): Uses defaults, zero prompts (CI-safe)
-### Wizard implementation details
-- **Repo discovery** (`discoverRepos`): Scans `~` for `.git` directories at first level (non-recursive)
-- **Port validation** (`validatePort`): Rejects invalid ports, accepts 1–65535
-- **Portable paths**: All config paths use `~` form (`~/.claude`, `~/scripts`, etc.) for cross-platform compatibility
-- **Defaults**: Every prompt has a default so users can skip it (press Enter)
-- **Non-destructive**: Never overwrites existing `aesop.config.json` without user confirmation
-## Invariants & gotchas
-- **Idempotent on empty targets**: Fails if `targetDir` exists and is non-empty (non-destructive). Safe to retry.
-- **Adding shipped files**: Any new file/dir added to `filesToCopy` array must also be added to `package.json` `files` array (lines 9–27 in package.json) so npm publish includes it.
-- **No machine-specific paths**: Use relative paths only; `__dirname` and `path.join()` handle cross-platform resolution.
-- **Wizard prompts are async**: Main execution is wrapped in async IIFE to support readline prompts
-- **Help text accuracy**: If invocation steps or output paths change, update help text

package/daemons/CLAUDE.md DELETED Viewed

@@ -1,36 +0,0 @@
-# daemons/ — Watchdog daemon
-**Purpose**: Long-running backup and secret-scan daemon for fleet-wide repo safety.
-## Files
-- **run-watchdog.sh** (1.7K): Interactive daemon supervisor; spawns backup-fleet.sh every 150s, maintains heartbeat guard (200s dedupe window), logs to FLEET-BACKUP.log. Calls tools/alert_bridge.py --scan after each cycle to post HIGH/CRITICAL alerts to Slack/Discord (opt-in). Traps INT/TERM cleanly.
-- **backup-fleet.sh** (5K): Core backup worker; discovers repos (~/.*, ~/*, ~/dev/*), stashes uncommitted work to backup/* branches, pushes unpushed commits, scans tracked files for secrets. Blocks push if secret-scan fails (marks BLOCKED state).
-## Contracts
-**Env vars consumed**: `AESOP_ROOT` (defaults to `.`) — root of project; prepends to all state/ and tools/ paths.
-**State files written** (git-ignored):
-- `$AESOP_ROOT/state/.watchdog-heartbeat` — epoch seconds; dedupe guard (200s window).
-- `$AESOP_ROOT/state/.watchdog-repos.json` — per-cycle snapshot: [{repo, state: CLEAN|PUSHED|SNAPSHOTTED|BLOCKED, age}].
-- `$AESOP_ROOT/state/FLEET-BACKUP.log` — append-only; cycle start/end, repo statuses, secret-scan blocks.
-- `$AESOP_ROOT/state/SECURITY-ALERTS.log` — append-only; security alerts (read by alert_bridge.py to post to webhooks).
-- `$AESOP_ROOT/state/.alert-bridge-cursor` — line number of last sent alert (ensures idempotent alert dispatch).
-**Exit behaviors**: run-watchdog exits 0 always (trap handles clean shutdown). backup-fleet exits 0 even on secret-scan block (marks repo BLOCKED, continues).
-**Cadence**: 150s cycle; heartbeat dedupe within 200s.
-## Invariants & Gotchas
-1. **Single-instance guard (atomic lock)**: run-watchdog.sh uses atomic mkdir-based lockfile (`.watchdog-lock/`) to prevent concurrent daemons.
-   - Atomic acquire: `mkdir $LOCK_DIR` is guaranteed atomic on POSIX systems (returns 0 only to first caller).
-   - Stale-lock recovery: Crashed holder won't wedge daemon forever; lock older than 300s is reclaimed atomically.
-   - Guards both daemon mode and `--once` mode (no bypass).
-2. **Testing override**: Set `AESOP_WATCHDOG_CYCLE_CMD` env var to replace backup-fleet.sh invocation (allows tests to use mock cycle without running real backup).
-3. **CRLF-safe, no line continuations**: Use POSIX-safe heredocs; never add `\` for line wrap.
-4. **Secret-scan gate**: `scan_tracked_files()` calls `$AESOP_ROOT/tools/secret_scan.py` on tracked modifications and untracked files; non-0 exit blocks push, marks repo BLOCKED.
-5. **Append-only logs**: FLEET-BACKUP.log only grows; rotate via tools/rotate_logs.py.
-6. **Path dedup via realpath**: Avoids processing symlinked repos or dot-dir aliases twice.
-7. **Alert Bridge integration** (NEW wave-14): After each backup-fleet.sh cycle, run-watchdog.sh calls `python $AESOP_ROOT/tools/alert_bridge.py --scan || true` to post HIGH/CRITICAL security alerts and heartbeat staleness to Slack/Discord. No-op if webhook_url null/absent in aesop.config.json (feature opt-in). Uses cursor file for idempotent dispatch (no re-sends). See tools/alert_bridge.py for details.

package/dash/CLAUDE.md DELETED Viewed

@@ -1,32 +0,0 @@
-# dash/ — Dashboard TUI
-**Purpose**: Real-time TUI fleet monitoring — watchdog daemon + agent activity display.
-## Files
-- **watchdog-gui.sh** — Read-only terminal UI (4s refresh, double-buffered, no flicker). Displays daemon status, backed-up repos, heartbeats, recent events. Launch in own window; never inside tool shell. CRLF-safe (no line continuations).
-- **dash-extra.mjs** — Node.js agent activity detector. Scans AESOP_TRANSCRIPTS_ROOT for agent-*.jsonl files (last 12 min). TUI output by default; --json for web endpoints. Requires node on PATH (unavailable fallback if missing).
-## State contracts
-**watchdog-gui.sh reads** (heartbeat staleness thresholds applied):
-- `state/.watchdog-heartbeat` (epoch, threshold: 300s for watchdog)
-- `state/FLEET-BACKUP.log` (append-only, tail 3 lines)
-- `state/SECURITY-ALERTS.log` (counts HIGH/MED, grep filtering RESOLVED-FP)
-- `state/.watchdog-repos.json` (jq-parsed, status per repo)
-- `state/.heartbeats/*` (epoch, per-agent thresholds: 3600s monitor, 300s watchdog, 1800s default)
-**dash-extra.mjs reads**:
-- `~/.claude/projects/**/ agent-*.jsonl` (modified time, <12min filter, top 8 recent)
-- `state/SECURITY-ALERTS.log` (severity classification: HIGH/MED/DRIFT)
-**Refresh cadence**:
-- watchdog-gui.sh: 4s loop (infinite, Ctrl-C to exit)
-- dash-extra.mjs: called on-demand (no built-in loop)
-## Invariants & TUI conventions
-- **Never modify fleet state** — both tools are read-only dashboards.
-- **Infinite loop design** — watchdog-gui.sh runs forever; launch in dedicated terminal window, never inside tool shells.
-- **CRLF-safe** — no bash line continuations; portable POSIX.
-- **Node optional** — dash-extra.mjs gracefully prints "unavailable" if node missing; doesn't fail watchdog-gui.sh.

package/docs/archive/README.md DELETED Viewed

@@ -1,3 +0,0 @@
-# Archived Spike Investigations
-Spike investigations that were cancelled or superseded; kept for reference and historical context.

package/docs/archive/spikes/tiered-cognition/ACTIVATION.md DELETED Viewed

@@ -1,125 +0,0 @@
-# ACTIVATION runbook — force-model-policy.merged.mjs
-Swap the staged merged hook in for the live model-policy hook. **Do not run
-this casually** — the live hook governs every subagent dispatch in every
-session. Perform the swap between waves, not mid-fleet.
-Paths used below:
-- LIVE hook: `C:\Users\matt8\.claude\hooks\force-haiku-subagents.mjs`
-- STAGED file: `<aesop>\docs\spikes\tiered-cognition\force-model-policy.merged.mjs`
-- Shim agent def: `<aesop>\docs\spikes\tiered-cognition\aesop-cognition.example.md`
-## Phase A activation (recommended first step)
-Default behavior after the swap: model policy identical to today, plus
-opus/fable-frontmatter dispatches rewritten to the message-only
-`aesop-cognition` shim. Sonnet specialists untouched (no prompt loss —
-FINDINGS.md condition 3 deferred). Layer 2 stays dormant.
-1. **Install the shim agent definition** (the merged hook rewrites cognition
-   dispatches to `subagent_type: aesop-cognition`; without the definition
-   those dispatches would fail):
-   ```powershell
-   Copy-Item <aesop>\docs\spikes\tiered-cognition\aesop-cognition.example.md `
-             C:\Users\matt8\.claude\agents\aesop-cognition.md
-   ```
-   Then edit the copied file's `description:` to remove the "NOT INSTALLED"
-   sentence. Keep `tools: Agent, SendMessage, TaskStop, Monitor` and do NOT
-   add a `model:` line (the hook passes the effective model explicitly).
-2. **Back up the live hook** (timestamped, same directory):
-   ```powershell
-   Copy-Item C:\Users\matt8\.claude\hooks\force-haiku-subagents.mjs `
-             C:\Users\matt8\.claude\hooks\force-haiku-subagents.mjs.bak-$(Get-Date -Format yyyyMMdd-HHmmss)
-   ```
-3. **Verify the staged file before copying** (must print `SELF-TEST: ALL PASS`,
-   exit 0):
-   ```powershell
-   node --check <aesop>\docs\spikes\tiered-cognition\force-model-policy.merged.mjs
-   node <aesop>\docs\spikes\tiered-cognition\force-model-policy.merged.mjs --self-test
-   ```
-4. **Copy over the live hook, keeping the live FILENAME** so settings.json
-   needs no edit:
-   ```powershell
-   Copy-Item <aesop>\docs\spikes\tiered-cognition\force-model-policy.merged.mjs `
-             C:\Users\matt8\.claude\hooks\force-haiku-subagents.mjs -Force
-   ```
-5. **Verify the settings matcher is unchanged and correct.** In
-   `C:\Users\matt8\.claude\settings.json` the `hooks.PreToolUse` entry with
-   matcher `Agent|Task` must point at
-   `~/.claude/hooks/force-haiku-subagents.mjs` (node command). Do NOT add any
-   other hook on that matcher — this file must remain the ONLY `updatedInput`
-   owner for `Agent|Task`; wiring a second rewriting hook there reintroduces
-   the exact collision this merge exists to fix.
-6. **Re-run the self-test on the installed copy** (proves the copy is intact):
-   ```powershell
-   node C:\Users\matt8\.claude\hooks\force-haiku-subagents.mjs --self-test
-   ```
-7. **Restart.** Claude Code snapshots hook config at session start — running
-   sessions keep the old hook until restarted. Restart the orchestrator
-   session and any long-lived fleet sessions/daemons that dispatch subagents.
-8. **Smoke-check in a fresh session:** dispatch a generic Haiku agent (expect
-   pass/route-to-haiku, no shim), a `bash-pro` (expect claude-sonnet-5, no
-   shim), and — if any opus/fable-frontmatter agent def is installed — one of
-   those (expect the `⛓ … tools stripped via 'aesop-cognition' shim` system
-   message). Confirm escape uses append to
-   `state/MODEL-POLICY-ESCAPES.log` / `state/TIER-POLICY-ESCAPES.log`.
-## Phase B (later, deliberate)
-Set `TIER_STRIP_SCOPE=all` in the environment Claude Code launches from to
-extend the shim to sonnet specialists — ONLY after per-specialist cognition
-variants exist (FINDINGS.md condition 3), otherwise specialist system prompts
-are lost to the generic shim. `TIER_STRIP_SCOPE=off` reduces the hook to pure
-live-hook model-policy behavior (useful as a soft rollback).
-## Phase C — arming Layer 2 (call-time backstop; later, deliberate)
-Dormant until BOTH of these are true:
-1. `TIER_ENFORCE=1` in the environment.
-2. settings.json gains a second `PreToolUse` entry running this same hook file
-   with a matcher covering the denied tools, e.g.
-   `Read|Write|Edit|MultiEdit|NotebookEdit|Bash|PowerShell|Glob|Grep|WebFetch|WebSearch|Skill|Artifact`.
-   (That entry never emits `updatedInput` — deny/allow only — so the
-   single-owner rule is preserved.)
-Before arming: validate transcript sniffing on real sidechain transcripts and
-decide the main-thread carve-out (FINDINGS.md condition 2 / risk 4).
-## Rollback
-1. Restore the newest backup:
-   ```powershell
-   Copy-Item C:\Users\matt8\.claude\hooks\force-haiku-subagents.mjs.bak-<TS> `
-             C:\Users\matt8\.claude\hooks\force-haiku-subagents.mjs -Force
-   ```
-2. Optionally remove `C:\Users\matt8\.claude\agents\aesop-cognition.md`
-   (harmless to leave installed; nothing routes to it without the merged hook).
-3. Unset `TIER_ENFORCE` / `TIER_STRIP_SCOPE` if set; remove any Layer-2
-   matcher added in Phase C.
-4. Restart running sessions (same snapshot rule as step 7 above).
-## Env knobs (merged hook)
-| Var | Default | Effect |
-|---|---|---|
-| `FORCE_ALL_HAIKU=1` | off | Every dispatch → haiku (bash-pro excepted) — unchanged from live hook |
-| `TIER_STRIP_SCOPE` | `opus-fable` | `opus-fable` (Phase A) / `all` (Phase B) / `off` (model policy only) |
-| `TIER_ENFORCE=1` | off | Arms the Layer-2 call-time backstop (needs the Phase C matcher too) |
-| `AESOP_ROOT` | `~/aesop` | Root for `state/*-ESCAPES.log` audit logs |

package/docs/archive/spikes/tiered-cognition/DESIGN.md DELETED Viewed

@@ -1,287 +0,0 @@
-# Tiered Cognition/Execution — Wave-11 Spike Design
-> **STATUS: SPIKE — NOTHING HERE IS ACTIVATED.** No live hook, settings.json,
-> or skill was modified. The prototype (`strip-tools-hook.mjs`) and shim agent
-> (`aesop-cognition.example.md`) live only in this directory. Rollout is a
-> wave-12 decision — see `FINDINGS.md` for the GO/NO-GO and steps.
-Source plan: `conductor3/plans/aesop-wave11-tiered-cognition.md`.
-## 1. Architecture recap
-```
-Fable 5  ⇄  Haiku  ⇄  Opus  ⇄  Haiku  ⇄  Sonnet 5  ⇄  Haiku  ⇄  (files / git / tools / tests)
-(cognition)  courier  (cognition) courier  (cognition)  executor
-```
-| Tier | Models | May do | May NOT do |
-|---|---|---|---|
-| Cognition | Fable 5, Opus, Sonnet 5 | Reason, decide, emit WORK-ORDERs, dispatch/message Haiku | Read, Write, Edit, Bash, Glob, Grep, WebFetch — any direct I/O/exec |
-| Substrate | Haiku | Everything real: read/write/exec/git/tests + carry messages between tiers | Improvise, silently "fix" a work-order, summarize away errors |
-Two mechanisms realize this: **(A)** a PreToolUse hook that strips I/O/exec
-tools from cognition-tier subagents, and **(B)** a structured courier/executor
-hand-off (WORK-ORDER → EXEC-BRIEF) so cognition output is mechanically
-applicable and results flow back as typed briefs.
-## 2. Mechanism A — the tool-stripping PreToolUse hook
-Prototype: [`strip-tools-hook.mjs`](strip-tools-hook.mjs) — standalone, pure
-`decide()` core, `--self-test` builds fixtures and asserts 27 cases (all pass).
-### 2.1 Harness facts that shape the design
-1. **The Agent tool input has NO `tools` field.** Its schema is
-   `{description, prompt, subagent_type, model, isolation, run_in_background}`
-   with `additionalProperties: false`. A hook's `updatedInput` therefore
-   *cannot* inject a per-dispatch tool list (it would be an
-   InputValidationError). The only supported way to constrain a subagent's
-   tools today is the agent definition's `tools:` frontmatter
-   (`~/.claude/agents/*.md`) — so dispatch-time stripping is implemented as a
-   **rewrite to a shim agent type** whose definition carries the allowlist.
-2. **PreToolUse hooks fire for subagents' own tool calls too**, which enables a
-   call-time backstop independent of how the agent was dispatched.
-3. **The hook payload does not name the session's model**
-   (`{session_id, transcript_path, cwd, tool_name, tool_input, ...}`), so
-   call-time tier detection is inferred from the transcript (§2.3).
-4. **Hook composition hazard:** the live `force-haiku-subagents.mjs` already
-   emits `updatedInput` on the same `Agent|Task` matcher. Two hooks rewriting
-   the same call have no defined merge; at rollout the tier policy must be
-   **merged into the model-policy hook as one file** (model routing decides the
-   tier; the same decision then strips or keeps tools — one decision point, no
-   ordering hazard).
-### 2.2 Layer 1 — dispatch guard (matcher `Agent|Task`)
-**Tier detection**, in order:
-1. Explicit `tool_input.model` — substring match: `haiku` → substrate;
-   `sonnet` / `opus` / `fable` → cognition.
-2. Blank model + `subagent_type` → the installed agent definition's `model:`
-   frontmatter (same catalog walk the model-policy hook uses).
-3. Neither → **haiku** (correct by construction: the model-policy hook lands
-   every non-specialist, non-escaped dispatch on Haiku).
-**Decision table:**
-| Dispatch | Action |
-|---|---|
-| Tier = haiku (or `subagent_type: fork`) | pass untouched |
-| Tier = cognition, prompt has escape token | allow untouched + **audit** (§2.4) |
-| Tier = cognition, no escape | **strip** — rewrite `subagent_type` → `aesop-cognition`, prepend `[COGNITION CONTRACT v1]` header naming the originally requested type |
-| Malformed payload / unreadable catalog | pass (fail-open) |
-**Kept tools** (via the shim's `tools:` frontmatter, see
-[`aesop-cognition.example.md`](aesop-cognition.example.md)):
-`Agent, SendMessage, TaskStop, Monitor` — reason, message, dispatch Haiku,
-stop/monitor what it dispatched. Nothing else.
-**Stripped (denied) tools:**
-`Read, Write, Edit, MultiEdit, NotebookEdit, Bash, PowerShell, BashOutput,
-KillShell, Glob, Grep, WebFetch, WebSearch, Skill, Artifact, ToolSearch,
-EnterWorktree, ExitWorktree`.
-Note the mission's generalization: cognition tiers lose **Read/Grep/Glob too**
-— facts arrive via Haiku courier briefs, never raw file ingestion. This is the
-"orchestrator reads nothing" cardinal rule applied to every expensive tier.
-**Cost of the shim rewrite:** the original specialist's system prompt (its
-`.md` body) is lost; the role survives only as the contract header line. §5
-lists the wave-12 fix (generated per-specialist cognition variants).
-### 2.3 Layer 2 — call-time backstop (matcher `Read|Write|Edit|NotebookEdit|Bash|PowerShell|Glob|Grep|WebFetch|WebSearch|Skill|Artifact`)
-Defense in depth for dispatches that bypass Layer 1 (pre-existing sessions,
-SDK-defined agents, the main thread, drift after a harness update).
-1. Parse `transcript_path` (JSONL). Tier = model of the **last** assistant
-   entry (`message.model`) — robust to mid-session model switches.
-2. Escape check: any user entry containing an escape token (a subagent's
-   dispatch prompt is the first user message of its transcript, so an escaped
-   dispatch is visible here).
-3. Decision: haiku or escaped → allow; cognition → **deny**; transcript
-   missing/unreadable/model-free → pass (fail-open, no opinion).
-The deny is **self-correcting**: `permissionDecision: "deny"` returns the
-reason to the model, and the reason is an instruction —
-> "Do NOT retry {tool}. Instead emit a WORK-ORDER v1 … and dispatch a Haiku
-> executor agent to apply it and report back an EXEC-BRIEF."
-so a cognition agent that tries to touch a file is redirected into the courier
-pattern mid-flight instead of just failing.
-**Main-thread consequence:** the backstop as specified also denies a Fable
-main thread's direct writes — which *is* the cardinal rule ("orchestrator
-never hand-writes files") — but today's orchestrator legitimately runs short
-git one-liners. Rollout needs either a read-only Bash allowlist
-(`git status|log|diff --stat` patterns) or a main-thread carve-out. Flagged in
-FINDINGS; the spike prototype governs the listed tools uniformly.
-### 2.4 Escape hatch — `[[ALLOW-TIER-TOOLS]]`
-Same contract as the model policy's `[[ALLOW-NON-HAIKU]]`:
-- Token in the dispatch prompt → the agent keeps its full toolset.
-- **Never silent**: announced via `permissionDecisionReason` in the transcript
-  AND appended as a JSON line to
-  `${AESOP_ROOT:-~/aesop}/state/TIER-POLICY-ESCAPES.log`
-  (`{ts, event: "tier_policy_escape", tool, session_id, cwd, description,
-  requested_model, prompt_head}`).
-- During migration, `[[ALLOW-NON-HAIKU]]` is grandfathered as implying tool
-  retention (today's escalations are hands-on missions — this spike itself ran
-  under it). Once cognition dispatch is the norm, escalate-model-but-stay-
-  cognition becomes the default and `[[ALLOW-NON-HAIKU]]` stops implying tools.
-## 3. Mechanism B — the courier/executor hand-off
-### 3.1 WORK-ORDER v1 (cognition → executor)
-A cognition agent's entire real-world intent for one coherent change-set,
-batched into a single JSON document:
-```json
-{
-  "kind": "work-order",
-  "version": 1,
-  "id": "wo-<slug>",
-  "intent": "one-line goal (for logs and the brief)",
-  "worktree": "C:/abs/path/to/isolated/worktree",
-  "branch": "expected branch (executor verifies before acting)",
-  "patch": "<unified diff as a single string, or null>",
-  "commands": [
-    { "run": "exact command line", "cwd": "abs path", "expect_exit": 0, "timeout_s": 120 }
-  ],
-  "verify": [
-    { "run": "exact command line", "expect_exit": 0, "expect_stdout_re": "optional regex" }
-  ],
-  "report": { "format": "exec-brief/v1", "max_words": 200 }
-}
-```
-Semantics:
-- `patch` is applied with `git apply` (byte-exact context; a failed hunk is a
-  FAILED brief, never hand-merged). `commands` run in listed order, stopping at
-  the first unexpected exit. `verify` always runs after (even partially) —
-  it is the evidence section of the brief.
-- Ambiguity is an error: if the executor cannot apply the order *exactly as
-  written*, it stops and reports; it never substitutes judgment.
-- One work-order per coherent change-set (**batching amortizes the round-trip**
-  — a whole patch + command plan, never line-by-line).
-### 3.2 EXEC-BRIEF v1 (executor → cognition)
-```json
-{
-  "kind": "exec-brief",
-  "version": 1,
-  "work_order_id": "wo-<slug>",
-  "status": "APPLIED | FAILED | PARTIAL",
-  "steps": [ { "step": "apply-patch | cmd:<n> | verify:<n>", "ok": true, "detail": "≤1 line" } ],
-  "verify_results": [ { "run": "…", "exit": 0, "stdout_tail": "last ≤3 lines" } ],
-  "verbatim_errors": [ "exact error text, untrimmed — empty array iff none" ],
-  "files_touched": [ "relative paths" ],
-  "commit": "sha or null"
-}
-```
-### 3.3 Courier honesty rules
-1. Apply **exactly** what the order says; no improvisation, no "small fixes".
-2. Failures are reported **verbatim** in `verbatim_errors` — never summarized,
-   never softened. The substrate must not editorialize.
-3. A brief is **always** produced (inputs always produce outputs) — even a
-   crash mid-order yields `status: FAILED` with whatever evidence exists.
-4. Verification stays owner-owned: the executor *runs* the verify commands;
-   the owning cognition tier *judges* the pass/fail brief
-   (per `[[subagents-push-orchestrator-verifies]]`).
-## 4. Worked example — a real round-trip (executed in this spike)
-Task: one-line real doc change — link this spike directory from
-`docs/README.md`. The cognition tier (Fable, this session) authored the
-work-order below; a **real Haiku executor subagent** applied it.
-### 4.1 The cognition-authored WORK-ORDER
-```json
-{
-  "kind": "work-order",
-  "version": 1,
-  "id": "wo-w11-readme-spikes-link",
-  "intent": "Add a Design Spikes section to docs/README.md linking the tiered-cognition spike",
-  "worktree": "C:/Users/matt8/aesop-wt-wave11-mission-spike",
-  "branch": "spike/wave11-tiered-cognition",
-  "patch": "<the unified diff below, embedded verbatim>",
-  "commands": [],
-  "verify": [
-    { "run": "git -C C:/Users/matt8/aesop-wt-wave11-mission-spike diff --numstat -- docs/README.md", "expect_exit": 0, "expect_stdout_re": "^4\\t0\\tdocs/README.md$" },
-    { "run": "grep -n \"## Design Spikes\" docs/README.md", "expect_exit": 0, "expect_stdout_re": "^38:" },
-    { "run": "grep -c \"spikes/tiered-cognition/\" docs/README.md", "expect_exit": 0, "expect_stdout_re": "^1$" }
-  ],
-  "report": { "format": "exec-brief/v1", "max_words": 200 }
-}
-```
-```diff
---- a/docs/README.md
-+++ b/docs/README.md
-@@ -33,4 +33,8 @@
- ## Operational Guides
- - [PUBLISHING.md](PUBLISHING.md) — Release Aesop to npm using GitHub Actions with OIDC trusted publishing
- - [av-resilience.md](av-resilience.md) — Antivirus & behavioral-engine resilience patterns for reliable agent execution
-+
-+## Design Spikes
-+
-+- [spikes/tiered-cognition/](spikes/tiered-cognition/) — Wave-11 spike: tiered cognition/execution architecture (Haiku as sole I/O substrate; Sonnet/Opus/Fable cognition tiers emit structured work-orders)
-```
-### 4.2 The EXEC-BRIEF as received from the Haiku executor
-Captured verbatim from a live general-purpose sub-dispatch (which the live
-model policy landed on **Haiku**, as the architecture requires). Round-trip:
-**33.9 s wall-clock, 33,932 subagent tokens, 6 tool uses**; the change was then
-independently re-verified by the owner (`git diff --numstat` = `4 0
-docs/README.md`, nothing else touched, em-dash bytes intact).
-```json
-{
-  "kind": "exec-brief",
-  "version": 1,
-  "work_order_id": "wo-w11-readme-spikes-link",
-  "status": "APPLIED",
-  "steps": [
-    { "step": "branch-check", "ok": true, "detail": "On spike/wave11-tiered-cognition" },
-    { "step": "write-patch",  "ok": true, "detail": "Patch file written to scratchpad" },
-    { "step": "apply-patch",  "ok": true, "detail": "git apply succeeded with exit 0" },
-    { "step": "verify:1",     "ok": true, "detail": "diff --numstat: 4 additions, 0 deletions" },
-    { "step": "verify:2",     "ok": true, "detail": "## Design Spikes found at line 38" },
-    { "step": "verify:3",     "ok": true, "detail": "tiered-cognition reference count: 1" }
-  ],
-  "verify_results": [
-    { "run": "git diff --numstat -- docs/README.md", "exit": 0, "stdout_tail": "4\t0\tdocs/README.md" },
-    { "run": "grep -n '## Design Spikes' docs/README.md", "exit": 0, "stdout_tail": "38:## Design Spikes" },
-    { "run": "grep -c 'spikes/tiered-cognition/' docs/README.md", "exit": 0, "stdout_tail": "1" }
-  ],
-  "verbatim_errors": [],
-  "files_touched": ["docs/README.md"],
-  "commit": null
-}
-```
-## 5. Rollout sketch (wave 12 — only if GO)
-1. Merge the tier policy into `force-haiku-subagents.mjs` (one decision point:
-   route model → strip or keep tools) — eliminates the dual-`updatedInput`
-   hazard of §2.1(4).
-2. Install `aesop-cognition.md`; generate per-specialist cognition variants
-   (`aesop-cognition-<specialist>.md`: specialist body + cognition tool
-   allowlist) so the specialist system prompt survives stripping.
-3. Add the Layer-2 backstop matcher to settings.json; decide the main-thread
-   carve-out (read-only git allowlist vs. exempting the top-level session).
-4. Teach `/buildsystem` dispatch prompts the WORK-ORDER/EXEC-BRIEF contract;
-   add an `aesop-executor` Haiku agent definition embedding §3.3.
-5. Verify transcript-sniff fidelity on real sidechain transcripts (the one
-   mechanism this spike could not fully validate in-harness — see FINDINGS).