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

package/docs/case-study-portfolio.md

@@ -0,0 +1,61 @@
+# Case Study: Portfolio Site Build with Aesop
+
+## What Happened (Timeline)
+
+| Time | Event | Duration |
+|------|-------|----------|
+| 17:09 | User prompt: "build me a portfolio site" | — |
+| 17:09–17:20 | 6 discovery scouts (GitHub API, Medium, LinkedIn, Reddit ×2, Playwright fallback, repo deep-dive) run in parallel; 4 ranked decision points surfaced | 11 min |
+| 17:20–17:24 | User answers 4 prioritization questions | 4 min |
+| 17:24–17:36 | 10 Haiku agents (scaffold + 8 section builders on file-disjoint Astro components + integrator) execute | 12 min |
+| 17:36–17:37 | 9th section added from late Reddit data; Astro build green in 914ms | 1 min |
+| 17:37–17:40 | Playwright screenshot proof round 1: CSS 404 detected (styles linked as `/src/` instead of `/dist/`) | 3 min |
+| 17:40–17:42 | Repair agent fixes CSS paths; proof round 2 validates fix | 2 min |
+| 17:42–17:48 | GitHub agent: secret-scan (10,066 files clean), create public repo, merge PR #1 | 6 min |
+| 18:04 | GitHub Pages deployed and live at https://matt82198.github.io/ (verified 200 status) | **55 min total** |
+
+## The Architecture
+
+**Parallel discovery with verified facts only**: Six independent scouts (HTTP fallback to Playwright for bot-blocked sites) collected portfolio inspiration, ranked by relevance; each returned structured data on a single contract. No hallucination—every section claim traces to a source.
+
+**File-disjoint fan-out**: 8 section agents each owned one `.astro` component with zero file overlap; no merge conflicts, no serialization bottleneck. Integrator assembled in 12 minutes.
+
+**Proof-driven QA**: Screenshot verification caught a real ship-blocker—styles in dist/ referenced `/src/` paths that vanished at build time. No visual inspection could have found this; Playwright proved it was broken, repair proved it was fixed.
+
+**Gated ship**: Secret-scan gate (10,066 files) ran before public repo creation; zero credentials leaked. PR merged, Pages deploy triggered, liveness confirmed.
+
+**Orchestrator final-catch**: Fable verified theme coherence across 9 sections after assembly; caught one color inconsistency and one missing accent variant before ship.
+
+## What Failed (and Was Caught)
+
+The site rendered unstyled in production. Astro build succeeded locally (914ms), but the distributed `.astro` component agents—writing styles inline—used `import` statements pointing to source paths. After minification and bundling into `/dist/`, those paths no longer existed. The site shipped with no CSS.
+
+Playwright screenshot automation caught this in production-like conditions (rendering against the compiled bundle). A repair agent updated path resolution, regenerated the build, and Playwright proved the fix before merge. This is not a testing infrastructure story—this is proof automation as a first-class gate.
+
+## Numbers
+
+- **Wall-clock time**: 55 minutes (first prompt to live site)
+- **Total agents used**: ~30 (6 scouts, 10 builders, 1 repair, 1 GitHub ops, 3 proof/integration, 9 audits)
+- **Build fleet**: 10 Haiku agents (scaffold + 8 section builders + integrator)
+- **Build time**: 12 minutes (including inter-agent coordination)
+- **Sections delivered**: 9
+- **Proof rounds**: 2 (CSS 404 caught in round 1; fix validated in round 2)
+- **Ship-blockers caught**: 1 (CSS 404)
+- **Files secret-scanned**: 10,066 (0 issues)
+- **Subagent tokens**: ~328K
+- **PR**: #1, merged
+- **Deploy**: GitHub Pages, live 200 status
+
+## How to Reproduce
+
+1. Fork this repo or set up Aesop in your environment.
+2. Run the [buildsystem skill](/skills/CLAUDE.md) for a portfolio project.
+3. Provide 4–6 source URLs or inspiration topics; Aesop will dispatch 6 discovery scouts.
+4. Approve the ranked backlog (user decision round).
+5. Aesop dispatches the 10-agent build workflow in parallel on Astro or your framework.
+6. Screenshot proof runs automatically; Aesop fixes any visual defects and re-proves.
+7. Secret-scan gate runs; if clean, Aesop creates the public repo and merges the PR.
+8. Pages (or your host) deploys automatically.
+
+The 55-minute bound is achievable when discovery sources are web-accessible (not gated PDFs) and the component schema is well-defined (Astro's `.astro` files are ideal; monolithic templates require serialization).
+

package/docs/self-stats-data.json

@@ -0,0 +1,11 @@
+{
+  "_source": "Populated by orchestrator at wave close via fleet telemetry aggregation",
+  "_updated": "Awaiting orchestrator population",
+  "total_sessions": null,
+  "total_turns": null,
+  "total_user_prompts": null,
+  "max_tokens_single_turn": null,
+  "cumulative_agent_runs": null,
+  "cumulative_tokens": null,
+  "total_coding_hours": null
+}

package/docs/templates/FLEET-OPS-ANALYSIS.example.md

@@ -0,0 +1,27 @@
+# Fleet-Ops Analysis Summary — Cycle N
+
+**Generated:** YYYY-MM-DDTHH:MM:SSZ
+
+## Top Failure Modes (cumulative this session)
+
+| Category | Count | Severity | Notes |
+|----------|-------|----------|-------|
+| [FAILURE_MODE_NAME] | 0 | [HIGH/MED/LOW] | Brief description of failure pattern, root cause hypothesis, and reference to any related recommendations or PRs. |
+| | | | |
+| | | | |
+
+## Token Spend Summary
+
+Brief summary of session token spend patterns:
+- [Agent/component type]: ~XXXk tokens — brief observation
+- Heavy [category]: XXXk — specific tasks or drivers
+- Typical [operation type]: XXk-XXXk; [context or pattern]
+
+Include observations about:
+- Which domains consumed the most tokens
+- Whether spend is aligned with task scope
+- Any unexpected patterns or efficiency issues
+
+## Notes
+
+(Optional section for additional context, anomalies, or deferred investigations)

package/docs/templates/FLEET-OPS-RECOMMENDATIONS.example.md

@@ -0,0 +1,24 @@
+# Fleet-Ops Recommendations — machinery fixes for wave open
+
+Rolling, append-only list maintained by the orchestration/fleet-ops monitor.
+The buildsystem skill reads this at every wave open (Phase 0.3). Mark items
+ADOPTED/REJECTED/IN-PROGRESS with wave number when actioned; do not delete rows.
+
+| # | Date | Source | Severity | Recommendation | Status |
+|---|------|--------|----------|----------------|--------|
+| 1 | YYYY-MM-DD | [source/agent/session phase] | [HIGH/MED/LOW] | Clear, actionable recommendation describing the problem, suggested fix, and rationale. Include specific file paths or component names where applicable. | OPEN |
+| 2 | YYYY-MM-DD | [source/agent/session phase] | [HIGH/MED/LOW] | Second example recommendation with similar detail level. Link to related findings if applicable. | OPEN |
+| | | | | | |
+
+## How to Use This Template
+
+1. **Record findings at wave close:** The orchestration monitor appends new rows for every machinery issue or systemic improvement identified.
+2. **Mark status transitions:** When a recommendation is adopted (wave-N or PR reference), update Status to `ADOPTED wave-N`. For rejected items, mark `REJECTED wave-N` with brief rationale.
+3. **Track implementation:** Use Status column to indicate OPEN (unactioned), IN-PROGRESS (wave-X, assigned to agent/owner), ADOPTED (implemented, wave-Y), or REJECTED (not pursued, wave-Y).
+4. **Preserve history:** Never delete rows — the log is append-only. This creates an auditable trail for machinery decisions.
+
+## Notes
+
+- **Source field:** Where did this insight come from? (session coordinator, CI failure, agent forensics, monitor signal, PR review, etc.)
+- **Severity:** HIGH = blocks reliable operation or impacts multiple waves; MED = worth addressing in near term; LOW = nice-to-have optimization.
+- **Implementation scope:** Recommendations should be specific enough for a developer to act on, but can span multiple waves if complex.

package/docs/templates/PROPOSALS-LOG.example.md

@@ -0,0 +1,64 @@
+# Orchestration Refinement Proposals — Action Log
+
+Actioned proposals moved from PROPOSALS.md (grounded in signals from YYYY-MM-DD). Per standing order, move decided entries here with date and outcome.
+
+---
+
+## ACCEPTED-IMPLEMENTED — YYYY-MM-DD
+
+### 1. [Proposal Title]
+
+**Outcome:** [Brief description of what was implemented, where code/docs changed, wave number if applicable, and verification of completion.]
+
+---
+
+## IN-PROGRESS — YYYY-MM-DD
+
+### 1. [Proposal Title]
+
+**Status:** IN-PROGRESS (wave-N, [assigned-agent or owner])  
+**Rationale:** [Why this proposal was accepted and what timeline/dependencies exist.]
+
+---
+
+## DEFERRED — YYYY-MM-DD
+
+### 1. [Proposal Title]
+
+**Status:** DEFERRED ([reason: blocked-by/low-priority/waiting-for-data])  
+**Rationale:** [Why this proposal was deferred, under what conditions it might be reconsidered.]
+
+---
+
+## REJECTED — YYYY-MM-DD
+
+### 1. [Proposal Title]
+
+**Status:** REJECTED (wave-N, [reason])  
+**Rationale:** [Explanation of rejection, any alternatives considered, and future implications.]
+
+---
+
+## No further action required (MONITORING ONGOING)
+
+### 1. [Proposal Title]
+
+**Status:** MONITORING  
+[Brief note on what is being tracked and how the team will know if action becomes necessary.]
+
+---
+
+## How to Use This Template
+
+1. **Capture proposals:** When orchestration/monitor/coordinator identifies a potential process or machinery improvement, record it in a staging PROPOSALS.md file with date, source, and rationale.
+2. **Move to log on decision:** Once a proposal is decided (ACCEPTED/REJECTED/DEFERRED), move the entry here with date and outcome.
+3. **Track implementation:** Use status sections (ACCEPTED-IMPLEMENTED, IN-PROGRESS, DEFERRED, REJECTED) to organize proposals by lifecycle stage.
+4. **Preserve history:** Keep all entries, do not delete. This creates an auditable trail of organizational decisions and learning.
+5. **Link to execution:** When implemented, reference the wave number or PR. When in-progress, name the owner.
+
+## Key Fields
+
+- **Proposal Title:** Concise statement of the proposed change or investigation.
+- **Outcome/Status:** What happened as a result (implemented, rejected, deferred, monitoring).
+- **Rationale:** Why this decision was made, dependencies, or conditions for change.
+- **Wave/PR/Agent:** Link to the work that carried out the decision (if applicable).

package/hooks/CLAUDE.md

@@ -30,6 +30,29 @@ Runs on `git push` via `.git/hooks/pre-push` symlink or copy.
 - See `docs/HOOK-INSTALL.md` for symlink (Linux/macOS/Git Bash) and copy (Windows) methods
 - Test with `bash hooks/pre-push-policy.sh --test` before org distribution
 
+## Hook: hooks/claude/force-model-policy.mjs
+
+Claude Code hook enforcing subagent Haiku dispatch (cost optimization).
+
+**Trigger**: On skill invocation or task delegation from main orchestrator thread. Examines Claude API request and enforces model constraint.
+
+**Policy**:
+- **Main orchestrator** (Fable/Opus on primary): no override (uses native model)
+- **Subagent dispatch** (fleet workers): **enforce Haiku** (claude-haiku-4-5-*). Exit 1 on non-Haiku model request.
+- **Specialists** (typed dispatches): Pin model to Haiku in the dispatch call; hook validates + blocks if violated.
+
+**Logging**:
+- On policy violation: log to `state/SECURITY-ALERTS.log` with timestamp, model-name, worker-id, and reason.
+- No alerts on compliant requests.
+
+**Self-Test**:
+- `node hooks/claude/force-model-policy.mjs --test` validates:
+  1. Haiku model allowed on subagents
+  2. Non-Haiku (e.g., Opus) blocked on subagents
+  3. Orchestrator not subject to policy
+  4. JSON logging format is valid
+- Exit 0 = all pass; exit 1 = any fail
+
 ## Invariants
 
 - POSIX sh compatible, CRLF-safe (no line continuations)

package/mcp/CLAUDE.md

@@ -0,0 +1,213 @@
+# mcp/ — Read-Only Fleet State MCP Server
+
+**Purpose**: Expose Aesop fleet operational status as a Model Context Protocol (MCP) server for Claude Code and other MCP clients.
+
+## Server
+
+**File**: `server.mjs` — Stdio-transport MCP server implementing the JSON-RPC 2.0 protocol.
+
+**Configuration**:
+- `AESOP_ROOT` environment variable or `--root <path>` command-line flag (no hardcoded paths)
+- `AESOP_STATE_ROOT` environment variable for state directory override (default: `AESOP_ROOT/state`)
+- `AESOP_TRANSCRIPTS_ROOT` environment variable for transcript directory override (default: `~/.claude/projects`)
+- Reads `aesop.config.json` from AESOP_ROOT for optional config file overrides
+
+**Launch**:
+```bash
+node mcp/server.mjs [--root /path/to/aesop]
+```
+
+The server reads from stdin, writes JSON-RPC responses to stdout. Suitable for direct MCP integration or debugging via manual JSON-RPC frames.
+
+## Tools
+
+All tools are **strictly read-only**: no state mutations, no file writes, no shell-outs except the minimal dash-extra.mjs passthrough for fleet_agents.
+
+### fleet_status
+
+**Description**: Get fleet operational status — daemon heartbeats, monitor heartbeat, orchestrator activity, alert count.
+
+**Input**: No arguments.
+
+**Output** (JSON):
+```json
+{
+  "watchdog": {
+    "alive": "ALIVE" | "STALE",
+    "age_seconds": <bucketed>,
+    "threshold_seconds": 300
+  },
+  "monitor": {
+    "alive": "ALIVE" | "STALE",
+    "age_seconds": <bucketed>,
+    "threshold_seconds": 3600
+  },
+  "orchestrator": <parsed orchestrator-status.json> or null,
+  "alerts": {
+    "count": <int>,
+    "sample_lines": [<last 3 unreviewed lines>]
+  }
+}
+```
+
+**Missing files**: If a file doesn't exist, the corresponding field is `null`. The response never crashes; missing state files are reported gracefully with `absent` markers where applicable.
+
+### fleet_agents
+
+**Description**: List active Claude agents from transcript directory. Invokes `dash-extra.mjs --json` with environment variables for path portability.
+
+**Input**: No arguments.
+
+**Output** (JSON):
+```json
+{
+  "absent": <bool>,
+  "agents": [
+    {
+      "project": <string>,
+      "taskLabel": <string>,
+      "promptFull": <string>,
+      "runtimeSeconds": <int>,
+      "tokensUsed": <int>,
+      "startedAt": <ISO string>,
+      "lastActivity": <ISO string>
+    },
+    ...
+  ]
+}
+```
+
+**Design notes**:
+- Passes through `dash-extra.mjs --json` output (no reimplementation).
+- Timeout: 5 seconds. On timeout or error, returns empty agents list.
+- Environment variables (`AESOP_ROOT`, `AESOP_STATE_ROOT`, `AESOP_TRANSCRIPTS_ROOT`) are set before invoking dash-extra to ensure portable transcript discovery.
+
+### fleet_tracker
+
+**Description**: Get fleet work items from `tracker.json`, grouped by lane.
+
+**Input**: No arguments.
+
+**Output** (JSON):
+```json
+{
+  "absent": <bool>,
+  "by_lane": {
+    "ranked": [
+      {
+        "id": <string>,
+        "title": <string>,
+        "priority": "P0" | "P1" | "P2",
+        "status": "todo" | "in-progress" | "done",
+        "tags": [<string>, ...]
+      },
+      ...
+    ],
+    "in-progress": [ ... ],
+    "done": [ ... ],
+    ...
+  }
+}
+```
+
+**Lanes**: Each lane is optional and present only if items exist in it. Common lanes: `ranked`, `proposed`, `in-progress`, `done`.
+
+### fleet_cost
+
+**Description**: Get per-model token usage totals from the fleet outcomes ledger (`state/ledger/OUTCOMES-LEDGER.md`).
+
+**Input**: No arguments.
+
+**Output** (JSON):
+```json
+{
+  "absent": <bool>,
+  "by_model": {
+    "claude-haiku-4": {
+      "tokens_in": <int>,
+      "tokens_out": <int>,
+      "total_tokens": <int>,
+      "count": <int>
+    },
+    "claude-opus": { ... },
+    ...
+  },
+  "total_tokens_in": <int>,
+  "total_tokens_out": <int>
+}
+```
+
+**Design notes**:
+- Parses markdown table rows from the ledger file.
+- Reports **token counts only** — no invented dollar figures.
+- Gracefully handles missing or malformed lines (skips with no error).
+
+## MCP Integration
+
+### Claude Code (claude.json)
+
+To register the server in Claude Code:
+
+```json
+{
+  "mcp": {
+    "aesop-fleet": {
+      "command": "node",
+      "args": [
+        "/path/to/aesop/mcp/server.mjs",
+        "--root",
+        "/path/to/aesop"
+      ],
+      "env": {
+        "AESOP_ROOT": "/path/to/aesop"
+      }
+    }
+  }
+}
+```
+
+### Portable Setup
+
+For portable configuration (no hardcoded user paths), use environment variables:
+
+```bash
+export AESOP_ROOT=/path/to/aesop
+export AESOP_STATE_ROOT=/path/to/state  # optional override
+export AESOP_TRANSCRIPTS_ROOT=/path/to/transcripts  # optional override
+node /path/to/aesop/mcp/server.mjs
+```
+
+Or use the `--root` flag:
+
+```bash
+node /path/to/aesop/mcp/server.mjs --root /path/to/aesop
+```
+
+## Invariants & Guarantees
+
+1. **Strictly read-only**: All tools are read-only. Zero state mutations, zero file writes.
+2. **No shell execution** (except dash-extra.mjs invocation with timeout): Minimizes surface area for injection or performance issues.
+3. **Graceful degradation**: Missing state files → empty results with `absent: true` markers, never a crash.
+4. **No external dependencies**: Plain Node.js (no npm packages). Server.mjs uses only stdlib modules: `fs`, `path`, `os`, `child_process`, `readline`.
+5. **JSON-RPC 2.0 compliant**: Standard request/response format with proper error codes.
+6. **Portable paths**: All paths resolved from AESOP_ROOT, AESOP_STATE_ROOT, AESOP_TRANSCRIPTS_ROOT env vars or config file. No hardcoded paths like `/home/user/aesop`.
+
+## Testing
+
+See `tests/mcp-fleet.test.mjs` for end-to-end tests:
+- Spawn server over stdio
+- Drive JSON-RPC initialize + tools/list + tools/call round-trips
+- Validate read-only behavior (no state mutations after calls)
+- Verify fixture isolation (temp state root)
+
+Run:
+```bash
+npm test  # or
+node tests/mcp-fleet.test.mjs
+```
+
+## Files
+
+- **server.mjs** — Main MCP server implementation (stdio, JSON-RPC 2.0)
+- **package.json** — Minimal metadata; no external dependencies
+- **CLAUDE.md** — This file

package/mcp/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "aesop-fleet-mcp",
+  "version": "1.0.0",
+  "description": "Read-only MCP server for Aesop fleet state (heartbeats, agents, tracker, costs)",
+  "type": "module",
+  "main": "server.mjs",
+  "bin": {
+    "aesop-fleet": "server.mjs"
+  },
+  "scripts": {
+    "start": "node server.mjs",
+    "start:root": "node server.mjs --root .."
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "orchestration",
+    "aesop"
+  ],
+  "author": "Anthropic",
+  "license": "MIT",
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}