@matt82198/aesop 0.1.0 → 0.3.1

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

@@ -1,113 +0,0 @@
-# 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/archive/spikes/tiered-cognition/README.md

@@ -1,27 +0,0 @@
-# Tiered Cognition/Execution — spike + staged wave-12 artifact
-
-> **STATUS: CANCELLED 2026-07-14** after A/B testing measured 4.6x weighted cost for identical quality (see MEMORY.md wave-11 entry). Kept for reference; do not activate. 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/archive/spikes/tiered-cognition/aesop-cognition.example.md

@@ -1,32 +0,0 @@
----
-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.