@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.4

package/docs/spikes/tiered-cognition/DESIGN.md

@@ -0,0 +1,287 @@
+# 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).

package/docs/spikes/tiered-cognition/FINDINGS.md

@@ -0,0 +1,113 @@
+# Tiered Cognition/Execution — Wave-11 Spike Findings
+
+**Verdict: GO (conditional)** — mechanism is buildable with today's harness
+primitives, the courier round-trip works with full fidelity on a real task,
+and the prototype hook passes its self-test. Three conditions must be closed
+in wave 12 before activation (below).
+
+## What was proven
+
+1. **Hook prototype works.** `strip-tools-hook.mjs --self-test`:
+   **27/27 PASS** (Node v24.16.0). Covers: sonnet/opus/fable dispatches
+   stripped via the `aesop-cognition` shim rewrite; haiku and
+   haiku-frontmatter dispatches untouched; blank-model specialist resolution
+   via agent-catalog frontmatter; escape token honored + audited to
+   `state/TIER-POLICY-ESCAPES.log`; legacy `[[ALLOW-NON-HAIKU]]`
+   grandfathered; fork pass-through; call-time deny of Write/Bash under a
+   sonnet transcript with a redirect-to-work-order reason; allow under haiku;
+   fail-open on malformed payloads and missing transcripts.
+2. **Courier round-trip works end-to-end on a real change.** A cognition-
+   authored WORK-ORDER (unified diff + 3 verify steps, DESIGN.md §4) was
+   applied by a **live Haiku executor sub-dispatch** (the existing model
+   policy routed it to Haiku with no special handling — the two policies
+   compose). Result: `status: APPLIED`, all verifies green, byte-exact
+   application (UTF-8 em-dashes and LF endings survived the
+   prompt → Write → git-apply path), zero collateral edits, honest typed
+   brief returned.
+3. **`git apply` is a sufficient fidelity gate.** Because the executor applies
+   the diff mechanically and the diff carries byte-exact context, any drift
+   the courier introduces fails the apply loudly instead of corrupting the
+   file. The verify list then provides positive evidence, not just absence of
+   error.
+
+## Round-trip overhead observed
+
+| Metric | Value |
+|---|---|
+| Wall-clock, dispatch → EXEC-BRIEF | **33.9 s** |
+| Executor tokens (Haiku) | 33,932 |
+| Executor tool uses | 6 (branch check, patch write, apply, 3 verifies) |
+| Cognition-side cost | authoring the work-order (one message) + reading a ~200-word brief |
+
+Interpretation: ~30–60 s and a few-cent Haiku bill per coherent change-set is
+acceptable **iff work-orders stay batched** (whole patch + command plan per
+round trip). At line-by-line granularity the architecture would be unusable —
+batching is a hard rule, not an optimization.
+
+## Fidelity risks / what breaks (honest list)
+
+1. **Hook composition (must fix before activation).** The live
+   `force-haiku-subagents.mjs` and this hook both emit `updatedInput` on the
+   same `Agent|Task` matcher; merge order is undefined. **Condition 1: merge
+   tier policy into the model-policy hook as one file.** Not fixable by
+   ordering config alone — one decision point is the correct design anyway.
+2. **Layer-2 tier detection is transcript-sniffed and unverified in-harness.**
+   The hook payload doesn't name the session model; the prototype infers it
+   from `transcript_path` JSONL (`message.model` of the last assistant
+   entry). This works on fixture transcripts, but sidechain/subagent
+   transcript layout in the current harness build was NOT exercised live
+   (this spike's session is escape-token-exempt, so a live negative test
+   wasn't possible without wiring the hook in — out of spike scope).
+   **Condition 2: validate the sniffer against real subagent transcripts
+   before trusting Layer 2; treat Layer 1 as the primary control.**
+3. **Specialist prompt loss under the shim rewrite.** Rewriting
+   `subagent_type` → `aesop-cognition` drops the specialist's system prompt;
+   the role survives only as a contract-header line. Cognition quality for
+   typed specialists will degrade until per-specialist cognition variants are
+   generated (DESIGN §5.2). **Condition 3 for full fleet rollout; not a
+   blocker for a Fable/Opus-orchestrator-only first phase.**
+4. **Main-thread carve-out undecided.** Uniform Layer-2 denial would break the
+   orchestrator's legitimate short git one-liners. Needs a read-only Bash
+   allowlist or a top-session exemption (DESIGN §2.3). Decide at rollout.
+5. **Fail-open stance.** Every failure path passes (consistent with the model
+   policy hook). A malformed transcript therefore silently disables Layer 2 —
+   same shape as the known `proposals-lock fail-open` issue. Acceptable for a
+   guardrail whose primary layer is dispatch-time, but worth a revisit when
+   Layer 2 is trusted.
+6. **Executor honesty is prompt-enforced, not mechanical.** The brief schema
+   and "verbatim errors" rule live in the dispatch prompt. A lazy executor
+   could still fabricate a green brief; mitigation is the existing
+   owner-verifies rule (the owning tier re-runs/reads the cheap verify
+   evidence, as done in this spike) plus `git apply`'s mechanical honesty.
+7. **Escape-token smuggling** applies to `[[ALLOW-TIER-TOOLS]]` exactly as to
+   the model policy's token: prompts are untrusted text. Same mitigation
+   inherited: never silent, always audited to state log.
+
+## GO / NO-GO
+
+**GO** for wave-12 rollout, phased:
+
+1. **Phase A (cheap, high value):** merge tier policy into
+   `force-haiku-subagents.mjs` (Condition 1); install `aesop-cognition.md` +
+   an `aesop-executor` Haiku agent def embedding the courier honesty rules;
+   teach `/buildsystem` dispatch prompts the WORK-ORDER/EXEC-BRIEF schema.
+   Apply stripping to **opus/fable dispatches only** first (no specialist
+   prompt loss — Condition 3 deferred safely).
+2. **Phase B:** generate per-specialist cognition variants; extend stripping
+   to sonnet specialists; measure fix-item throughput vs. the current
+   Sonnet-hands-on baseline for one wave before making it default.
+3. **Phase C:** wire Layer-2 backstop after validating transcript sniffing on
+   real sidechains (Condition 2) and deciding the main-thread carve-out.
+
+Top risk if rolled out as-is without the conditions: **the dual-hook
+`updatedInput` collision (risk 1)** — it could silently drop the model
+rewrite or the tool strip depending on harness ordering, i.e. a policy hole
+that looks green.
+
+## Spike inventory (all inert)
+
+- `docs/spikes/tiered-cognition/DESIGN.md` — mechanism + schemas + executed worked example
+- `docs/spikes/tiered-cognition/strip-tools-hook.mjs` — prototype hook, self-test 27/27 PASS
+- `docs/spikes/tiered-cognition/aesop-cognition.example.md` — shim agent def (NOT installed)
+- `docs/README.md` — one real change, applied by the Haiku executor round-trip
+- Nothing wired into `~/.claude/settings.json`, live hooks, or `/buildsystem`.

package/docs/spikes/tiered-cognition/README.md

@@ -0,0 +1,29 @@
+# Tiered Cognition/Execution — spike + staged wave-12 artifact
+
+> **STATUS: STAGED, NOT ACTIVATED.** Nothing in this directory is wired into
+> `~/.claude/settings.json` or `~/.claude/hooks/`. The live model-policy hook
+> (`force-haiku-subagents.mjs`) is untouched and still governs the fleet.
+
+## Contents
+
+| File | Status | What |
+|---|---|---|
+| `DESIGN.md` | wave-11 spike | Architecture, hook mechanism, WORK-ORDER/EXEC-BRIEF schemas, executed round-trip |
+| `FINDINGS.md` | wave-11 spike | GO (conditional) verdict, risks, phased rollout plan |
+| `strip-tools-hook.mjs` | wave-11 prototype | Tier policy alone (superseded by the merged file below) |
+| `aesop-cognition.example.md` | example, not installed | Message-only shim agent definition the merged hook rewrites to |
+| **`force-model-policy.merged.mjs`** | **wave-12 STAGED CANDIDATE** | Model policy + tier policy merged into ONE hook — the single `updatedInput` owner for the `Agent\|Task` matcher. Self-test: 51/51 PASS (`node force-model-policy.merged.mjs --self-test`) |
+| `ACTIVATION.md` | wave-12 runbook | Exact swap-in steps (backup, copy, verify, restart) and rollback |
+
+## Why the merged file exists
+
+FINDINGS.md risk 1 (top risk): the live `force-haiku-subagents.mjs` and the
+spike's `strip-tools-hook.mjs` both emit `updatedInput` on the same
+`Agent|Task` matcher, with undefined merge order — either rewrite could be
+silently dropped. `force-model-policy.merged.mjs` resolves this by computing
+the final model (model policy) first, deriving the cognition tier from that
+final model, and emitting BOTH rewrites in a single `updatedInput`.
+
+It is a drop-in replacement candidate for
+`~/.claude/hooks/force-haiku-subagents.mjs`. Activation is a deliberate,
+user-decided step — follow `ACTIVATION.md` when that decision is made.

package/docs/spikes/tiered-cognition/aesop-cognition.example.md

@@ -0,0 +1,32 @@
+---
+name: aesop-cognition
+description: Cognition-tier shim — pure reasoning, no I/O. Receives a COGNITION CONTRACT header naming the role it adopts; emits WORK-ORDER v1 artifacts and dispatches Haiku executors for every real-world action. NOT INSTALLED — wave-11 spike example; copy to ~/.claude/agents/ only at wave-12 rollout.
+tools: Agent, SendMessage, TaskStop, Monitor
+---
+
+You are a cognition-tier agent in Aesop's tiered cognition/execution
+architecture. You reason; Haiku acts. You have NO file, exec, or retrieval
+tools — do not attempt Read/Write/Edit/Bash/Glob/Grep/WebFetch; they are not
+available to you by design, not by accident.
+
+Operating rules:
+
+1. **Adopt the role** named in the `[COGNITION CONTRACT v1]` header of your
+   prompt (e.g. 'typescript-pro'). Apply that expertise to reasoning and
+   design, not to direct action.
+2. **All real-world effects go through WORK-ORDER v1** (schema:
+   docs/spikes/tiered-cognition/DESIGN.md §3). Emit a complete, batched
+   work-order — a unified diff and/or explicit command list plus verify
+   steps — never a vague instruction like "fix the tests".
+3. **Dispatch a Haiku executor** (general-purpose agent; the model policy
+   lands it on Haiku) with the executor contract + your work-order, or return
+   the work-order to your caller if the caller owns execution.
+4. **Need facts?** Dispatch a Haiku courier with precise questions ("return
+   lines 40-80 of X", "run the test suite, return the last 20 lines") and
+   reason over the brief it returns. Never ask for whole-file dumps you
+   don't need.
+5. **Read the EXEC-BRIEF honestly.** status FAILED/PARTIAL means your
+   work-order was wrong or the world differs from your model of it — revise
+   the work-order; never instruct the executor to force it through.
+6. **Batch.** One work-order per coherent change-set; round-trips are the
+   cost center of this architecture.