@matt82198/aesop 0.1.0-beta.1

package/docs/DISPATCH-MODEL.md

@@ -0,0 +1,180 @@
+# Aesop Dispatch Model — Cost & Orchestration Patterns
+
+## The fable conceit
+
+In Aesop's Fables, Aesop (the narrator) directs the characters (tortoise, hare, fox, etc.) through moral tales. Here, **Aesop (the orchestrator)** directs a fleet of **Fables (the subagents)** toward reliable task completion.
+
+The tortoise represents deliberate, resourceful thinking; the hare, quick speed. Together (slow orchestrator + fast subagents), they're unbeatable.
+
+## Cost model
+
+### Baseline: all-Opus fleet
+
+```
+5 tasks × 10 min each × Opus cost (~60 tokens/min for reasoning)
+= 5 × 10 × 60 = 3,000 tokens/session
+```
+
+### Aesop dispatch: Opus + 5 Haiku
+
+```
+1 orchestrator (Opus, 5 min thinking)  = 5 × 60 = 300 tokens
+5 subagents (Haiku, 2 min each)        = 5 × 2 × 20 = 200 tokens
+Total                                   = 500 tokens/session
+= **83% savings** vs all-Opus
+```
+
+### Scaling to 10 parallel domains
+
+```
+1 orchestrator (Opus, 8 min)       = 480 tokens
+10 subagents (Haiku, 3 min each)   = 600 tokens
+Total                              = 1,080 tokens
+= **90% savings** vs 10 Opus tasks
+```
+
+## Dispatch patterns
+
+### Pattern 1: Fan-out (wide parallelism)
+
+**Use case**: 10 independent tasks with no dependencies.
+
+```
+Orchestrator
+├─ Haiku-1: Test domain (write test, red → green)
+├─ Haiku-2: Build domain (compile, package)
+├─ Haiku-3: Docs domain (README, examples)
+├─ Haiku-4: Security domain (audit, review)
+└─ Haiku-5: Deployment domain (stage, verify)
+
+Total cost: 1 Opus + 5 Haiku ≈ $0.003 per session
+```
+
+### Pattern 2: Sequential with handoff
+
+**Use case**: Feature across 3 layers (API → DB → UI) with dependencies.
+
+```
+Orchestrator → Phase 1
+├─ Haiku-1: API spec + tests
+└─ (wait for Haiku-1 to complete)
+    → Phase 2
+    ├─ Haiku-2: DB schema (reads Haiku-1 output)
+    └─ (wait)
+        → Phase 3
+        ├─ Haiku-3: UI (reads both outputs)
+        └─ Haiku-4: Integration test
+        
+Orchestrator reassembles + QA
+Total cost: still 1 Opus + 4 Haiku = **90% savings**
+```
+
+### Pattern 3: Hierarchical (supervisor + workers)
+
+**Use case**: Complex codebase review (split into modules, each reviewed in parallel).
+
+```
+Orchestrator
+├─ Review-Supervisor (Sonnet, splits codebase into 5 modules)
+│  ├─ Haiku-1: auth module
+│  ├─ Haiku-2: api module
+│  ├─ Haiku-3: db module
+│  ├─ Haiku-4: ui module
+│  └─ Haiku-5: config module
+└─ (Sonnet synthesizes reviews into final report)
+
+Cost: 1 Opus + 1 Sonnet + 5 Haiku = ~$0.015 (still 75% savings)
+```
+
+## Decision flowchart
+
+When you have a new task, ask:
+
+```
+Is this task scoped to <5 min reasoning?
+├─ YES → Use Haiku subagent (cost: ~$0.0002)
+├─ NO → Can I decompose it into smaller tasks?
+│   ├─ YES → Fan-out to multiple Haiku (cost: $0.001–0.003)
+│   └─ NO → Use Opus (cost: ~$0.004)
+└─ Does this need final review/synthesis?
+    ├─ YES → Opus orchestrator does it (cost: ~$0.002)
+    └─ NO → Done (subagent output is final)
+```
+
+## Anti-patterns
+
+### ❌ All-Opus fleet
+
+**Cost**: 10× baseline. **Why**: throws CPU power at problems that are scoped.
+
+**Fix**: Decompose into Haiku-sized tasks.
+
+### ❌ Giant orchestrator context
+
+**Cost**: token waste, slower decisions. **Why**: reads full logs, commits, code diffs.
+
+**Fix**: Orchestrator reads STATE.md + BUILDLOG.md + git one-liners only. Delegate research to Haiku.
+
+### ❌ Silent hangs
+
+**Cost**: invisible waste (subagent stalls, orchestrator waits). **Why**: no heartbeat, no timeout.
+
+**Fix**: Heartbeat every 60s min. Watchdog respawns >200s stale. Orchestrator never waits>60s (spawn next task).
+
+### ❌ Cloud Python execution
+
+**Cost**: latency + complexity. **Why**: cloud runners add overhead, partial failure risk.
+
+**Fix**: All Python runs locally. Cloud agents spawn only for distributed compute (rare).
+
+## Token spend tracking
+
+### Log format (FLEET-LEDGER.md)
+
+```
+| timestamp           | domain   | subagent    | tokens | result      |
+|--|--|--|--|--|
+| 2024-01-15T10:30:00 | auth     | haiku       | 1200   | SUCCESS     |
+| 2024-01-15T10:35:00 | ui       | haiku       | 950    | SUCCESS     |
+| 2024-01-15T10:40:00 | test     | haiku       | 1100   | FAILED (1r) |
+| 2024-01-15T10:45:00 | test     | haiku       | 1050   | SUCCESS     |
+```
+
+### Cost signals to watch
+
+1. **Spend spike** (+20% baseline): investigate domain; may need larger model.
+2. **Respawn loop** (same domain 3+ times): subagent repeatedly failing; escalate to Sonnet or orchestrator review.
+3. **Serial bottleneck** (orchestrator >500 tokens): parallelism breaking down; split smaller or delegate.
+
+### Optimization levers
+
+- **Fan-out more tasks**: go from 2 Haiku to 5.
+- **Shift to Sonnet**: if 3 Haiku respawns in a row, use Sonnet once for harder task.
+- **Reduce orchestrator context**: read fewer files, shorter CLAUDE.md.
+- **Cache cardinal rules**: use prompt caching on base CLAUDE.md (reused every session).
+
+## Orchestrator role (the slow tortoise)
+
+- **Reading**: STATE.md (phase + next steps), BUILDLOG.md (latest 10 entries), git one-liners.
+- **Deciding**: which 3–5 Haiku to spawn, what task each gets, how to reassemble results.
+- **Waiting**: while subagents run in parallel, orchestrator uses time to:
+  - Brief user on progress.
+  - Spot-check one Haiku output.
+  - Plan next phase.
+- **Synthesizing**: reads Haiku results, updates STATE.md, decides next phase or declares done.
+
+**Golden rule**: Orchestrator thinks 5–10 min per hour of wallclock time (while agents run). Never blocks; never waits idle.
+
+## Subagent role (the swift fables)
+
+- **Scoped task**: <5 min pure reasoning per task.
+- **Clear acceptance criteria**: from orchestrator brief.
+- **Output**: append to BUILDLOG.md, return result to orchestrator.
+- **Failure**: log reason, don't retry (orchestrator decides retry).
+- **Speed**: finish in <2 min if possible; alert orchestrator if >5 min (break task smaller).
+
+**Golden rule**: Subagents stay cheap and fast. If a Haiku takes >10 min, you've scoped too large.
+
+---
+
+**Summary**: Aesop's dispatch model trades a small amount of orchestration complexity for **10× cost savings** and **4× speed** (via parallelism). It works by keeping subagents small, orchestrator lean, and feedback constant.

package/docs/PUBLISHING.md

@@ -0,0 +1,150 @@
+# Publishing Aesop to npm
+
+This guide explains how to publish new releases of Aesop to npm using GitHub Actions with OIDC trusted publishing (zero tokens, zero OTP prompts).
+
+## Overview
+
+The publish workflow (`.github/workflows/publish.yml`) is triggered automatically when you **publish a GitHub Release**. It uses npm's OIDC trusted publishing feature to authenticate with npm — no tokens, no 2FA/passkey prompts, no OTP required.
+
+## One-Time Setup on npmjs.com
+
+### Step 1: Add a Trusted Publisher
+
+You must configure GitHub as a trusted publisher for `@matt82198/aesop` on npmjs.com. This tells npm to allow publishes from the GitHub Actions workflow without a token.
+
+**Steps:**
+
+1. Go to **[npmjs.com/package/@matt82198/aesop/settings](https://www.npmjs.com/package/@matt82198/aesop/settings)** (substitute your actual username/package name).
+   - If the package doesn't exist yet, you'll need to create it first (see bootstrap caveat below).
+
+2. Click **Settings** → **Access** (or **Publishing** on newer UI).
+
+3. Scroll to **Trusted Publishers** (or **Publishing from CI/CD**).
+
+4. Click **Add a Trusted Publisher** → Select **GitHub Actions**.
+
+5. Enter these values:
+   - **Organization:** `matt82198` (your GitHub username or org)
+   - **Repository:** `aesop`
+   - **Workflow:** `publish.yml`
+
+6. Click **Save** or **Add**.
+
+npm will now allow publishes from the `publish.yml` workflow in the `aesop` repo without a token.
+
+### Step 2: Verify npm Version
+
+The workflow automatically ensures npm >= 11.5.1 (OIDC requirement). If you're publishing locally (not recommended), confirm:
+
+```bash
+npm --version  # Should be 11.5.1 or higher
+```
+
+## Publishing a Release
+
+### Via GitHub Web UI (Recommended)
+
+1. Go to your repo's **Releases** page.
+2. Click **Draft a new release**.
+3. **Tag version:** Enter a version (e.g., `0.1.0`, `0.1.0-beta.1`).
+4. **Release title:** E.g., "Aesop 0.1.0".
+5. **Description:** Add release notes (optional).
+6. Click **Publish release**.
+
+The workflow will automatically trigger and:
+- Check out your code.
+- Run secret scanning to ensure no credentials are accidentally published.
+- Determine the dist-tag:
+  - If version contains a hyphen (prerelease, e.g., `0.1.0-beta.1`): `npm publish --tag beta`
+  - Otherwise (stable): `npm publish --tag latest`
+- Publish to npm with no token or passkey prompt.
+
+### Via Git CLI
+
+```bash
+git tag 0.1.0 -a -m "Release Aesop 0.1.0"
+git push origin 0.1.0
+# Then go to GitHub Releases and click "Create release from tag"
+# (Or use gh CLI: gh release create 0.1.0 --generate-notes)
+```
+
+## Dist-Tag Logic
+
+The workflow automatically selects a dist-tag based on the version in `package.json`:
+
+- **Prerelease versions** (contain hyphen):
+  - `0.1.0-beta.1` → `npm publish --tag beta`
+  - `0.1.0-rc.1` → `npm publish --tag beta`
+  - `1.0.0-alpha` → `npm publish --tag beta`
+
+- **Stable versions** (no hyphen):
+  - `0.1.0` → `npm publish --tag latest`
+  - `1.0.0` → `npm publish --tag latest`
+
+Users installing with `npm install @matt82198/aesop` will get the latest stable version by default. Beta versions can be installed with `npm install @matt82198/aesop@beta`.
+
+## Secret Scanning
+
+Before every publish, the workflow runs:
+
+```bash
+python3 tools/secret_scan.py .
+```
+
+This scans the entire package tree for credentials (API keys, tokens, PEM files, etc.). **If any are found, the publish will fail.** This is a safety gate — credentials should never appear in published npm packages.
+
+If a false positive occurs (e.g., pattern documentation), add the pragma to the file's first 10 lines:
+
+```python
+# secretscan: allow-pattern-docs
+```
+
+See `tools/secret_scan.py` for full pragma documentation.
+
+## Bootstrap Caveat: First Publish
+
+**Important:** npm trusted publishing requires the package to already exist on npmjs.com before you can attach a trusted publisher.
+
+- **If the package does NOT yet exist:** You'll need a **one-time bootstrap publish** using either:
+  1. An npm **Automation token** (kept in a personal CI/CD secret, used once, then deleted).
+  2. The npm web flow (manual login with passkey, generate temporary token).
+
+  After the first publish, the package exists and the trusted publisher is active for all future releases.
+
+- **If the package already exists:** Skip this step. The workflow will publish directly with no token or passkey.
+
+**To bootstrap (one-time only):**
+
+1. Generate an npm Automation token at [npmjs.com/settings/tokens](https://npmjs.com/settings/tokens) (API type, pub access).
+2. Add it as a GitHub secret (e.g., `NPM_TOKEN`).
+3. Update the workflow `env` section to use it:
+   ```yaml
+   env:
+     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+   ```
+4. After the first publish succeeds, **remove the secret from the workflow** (revert to `NODE_AUTH_TOKEN: ${{ secrets.npm_token || '' }}`).
+5. The trusted publisher is now active for future releases.
+
+## Troubleshooting
+
+### Publish fails: "No permission to publish"
+
+→ **Trusted publisher not configured.** Go to npmjs.com settings and add it (step 1 above).
+
+### Publish fails: "npm: command not found"
+
+→ Shouldn't happen (actions/setup-node handles this). Check Node 22 is installed.
+
+### Publish fails: "Secret scan found credentials"
+
+→ Run `python3 tools/secret_scan.py .` locally to identify the leak. Remove or redact it, re-commit, then re-release.
+
+### I'm using a passkey-only account and get OTP prompts
+
+→ That's exactly why we use OIDC. Trusted publishing bypasses passkey+OTP entirely. Ensure the workflow and trusted publisher are correctly configured.
+
+## References
+
+- [npm OIDC Trusted Publishing](https://docs.npmjs.com/generating-and-authenticating-with-deploy-tokens#authenticating-with-oidc)
+- [GitHub Actions: Setting up Node.js](https://github.com/actions/setup-node)
+- [Secret Scanning Tool](../tools/secret_scan.py)

package/docs/av-resilience.md

@@ -0,0 +1,246 @@
+# Antivirus (AV) Resilience & Behavioral Engine Design Patterns
+
+## Problem Statement
+
+Antivirus and behavioral-analysis engines (SentinelOne, Windows Defender, etc.) may:
+- **Delete tool binaries mid-session** when they trigger heuristic alerts (Claude Code, git-bash, node, python)
+- **Suspend processes** during scanning, causing temporary hangs or failed tool invocations
+- **Block file writes** to protected directories, silently failing git operations or log appends
+- **Trigger false positives** on legitimate automation workflows (agent dispatch, secret scanning, process spawning)
+
+This is not a security breach—it's a *compatibility* problem with legitimate automation tools. Aesop must survive these disruptions gracefully.
+
+---
+
+## Design Principles
+
+### 1. **Continuous Push Discipline**
+- **Every cycle completes a push**, not just a stash or backup. If one file blocks due to AV, push the rest.
+- **Philosophy**: A partially-pushed state (some repos synced, some stalled) is **better** than no push at all.
+- **Implementation**:
+  - `daemons/backup-fleet.sh` processes repos independently; one BLOCKED repo doesn't stall others.
+  - `state/FLEET-BACKUP.log` logs each outcome (CLEAN, PUSHED, SNAPSHOTTED, BLOCKED) per repo.
+  - Watchdog cycle completes successfully even if 1 of 10 repos fails.
+
+### 2. **Surgical Single-File Recovery**
+- **Minimize scope of recovery**. If a binary is deleted, re-fetch only that one binary, not the whole toolchain.
+- **Pattern**:
+  - Monitor tool invocation failures: `python: command not found`, `git: not found`.
+  - Trigger minimal reinstall: `apt-get install python`, `git clone <tool>`.
+  - Resume immediately without waiting for manual intervention.
+- **Why**: Batch slowdowns (full OS update, system restart) are much worse than targeted tool recovery.
+
+### 3. **Avoid Mass Process Kills**
+- **Anti-pattern**: Restarting the orchestrator, killing all agents, wiping state when one process hangs.
+- **Pattern**: 
+  - Use tight heartbeat timeouts (300s for watchdog, 3600s for monitor).
+  - Kill **only** the stalled agent by its PID; main orchestrator stays alive.
+  - Log the kill and its reason (e.g., "heartbeat age 450s > threshold 300s").
+  - Resume the agent or defer to next cycle.
+
+### 4. **Idempotent Push Refs**
+- **Backup refs are date-stamped, not timestamped**: `backup/wip-20260711`, not `backup/wip-20260711-134521`.
+- **Why**: Multiple backup attempts on the same day write to the same ref, so git naturally deduplicates them.
+- **Recovery**: If a push partially fails and the process dies, the next cycle tries again to the same ref and succeeds without creating orphaned branches.
+
+### 5. **Tracked-Files-Only Secret Scanning**
+- **Scan only modified files**, not the entire repo (which includes .gitignored binaries, node_modules, build artifacts).
+- **Pattern**:
+  ```bash
+  git diff --name-only HEAD | xargs secret_scan.py
+  git ls-files -m | xargs secret_scan.py
+  ```
+- **Why**: 
+  - AV engines sometimes block access to large binary files during scanning. Scanning a 500MB node_modules triggers false-positive rate.
+  - Scanning only tracked changes is **faster** and **more reliable** than full-directory scans.
+  - Mirrors what a push gate would actually check (`git diff` before commit).
+
+---
+
+## Failure Modes & Recovery
+
+### Scenario 1: Binary Deletion Mid-Cycle
+
+**What happens:**
+```bash
+$ bash /path/to/aesop/daemons/backup-fleet.sh
+[2026-07-11 10:30:15] === cycle start ===
+[2026-07-11 10:30:16] SentinelOne deletes git.exe (false positive on automation)
+$ git fetch -q
+bash: git: command not found
+[2026-07-11 10:30:17] BLOCKED: my-project-repo
+```
+
+**Recovery:**
+1. Watchdog detects BLOCKED outcome → logs to FLEET-BACKUP.log.
+2. Next cycle (150s later) detects repo is touched (uncommitted files remain).
+3. Retry `is_touched()` → re-fetch → get `command not found` again.
+4. **Manual intervention path**: User or admin runs:
+   ```bash
+   # Re-install git (OS-specific)
+   winget install Git.Git  # Windows
+   apt-get install git      # Linux
+   ```
+5. Next watchdog cycle succeeds (binary is back).
+
+**Design choice**: Watchdog logs but doesn't auto-repair missing binaries (policy: fail safely, log clearly, resume on next cycle).
+
+---
+
+### Scenario 2: Process Suspension During Secret Scan
+
+**What happens:**
+```bash
+$ python secret_scan.py file1.py file2.py file3.py
+# AV engine suspends python.exe during scan of large file
+[waiting indefinitely or timing out after 30s]
+```
+
+**Recovery:**
+1. `scan_tracked_files()` runs with implicit timeout (scan completes or fails).
+2. If timeout, `scan_tracked_files` returns non-zero exit code → BLOCKED outcome.
+3. Files remain uncommitted (no push attempt).
+4. **Recommendation**: Tune secret-scan to scan **only staged files** (via `git diff --cached`), reducing scope.
+
+---
+
+### Scenario 3: Orchestrator Heartbeat Stale
+
+**What happens:**
+```bash
+# Watchdog daemon hung (AV locked python.exe; backup-fleet.sh stalled)
+# Heartbeat timestamp = 1720680915 (5 minutes ago)
+$ cat state/.watchdog-heartbeat
+1720680915
+$ date +%s
+1720681215  # Current time, 300s later
+# Dashboard threshold = 300s for watchdog
+# Status: STALE
+```
+
+**Recovery:**
+1. Dashboard shows `STALE (age: 300s+)` in red.
+2. User checks logs (`state/FLEET-BACKUP.log`) to diagnose why daemon stalled.
+3. Options:
+   - **If binary is missing**: Reinstall and restart watchdog.
+   - **If process is hung**: Kill it (`pkill -f run-watchdog.sh`) and restart.
+   - **If it's a false stall**: Wait for next cycle (watchdog usually recovers).
+4. Restart watchdog:
+   ```bash
+   bash $AESOP_ROOT/daemons/run-watchdog.sh
+   ```
+
+---
+
+## Best Practices
+
+### For Aesop Operators
+
+1. **Monitor the dashboard**. STALE heartbeats are your canary in the coal mine.
+2. **Review FLEET-BACKUP.log** weekly for BLOCKED outcomes. Investigate patterns.
+3. **Keep security scanner narrow**: Scan only staged files (`--staged`), not entire repos.
+4. **Whitelist Aesop tools in your AV**:
+   - `C:\Program Files\Git\bin\bash.exe`
+   - `python.exe` (if Python is on PATH)
+   - Node.js (if using orchestration monitor)
+   - The Aesop root directory itself (read-only, no execution harm)
+
+### For Aesop Developers
+
+1. **Test against real AV**. Spin up a test VM with SentinelOne or similar and deliberately trigger false positives.
+2. **Log all process invocations**. Include PID, command, exit code, stderr (first 100 chars).
+3. **Use tight timeouts** (30s for secret scans, 5s for git commands). Fail fast, don't hang.
+4. **Implement single-instance guards** via heartbeat files. Don't spawn multiple instances of the same daemon.
+5. **Design for recovery**: Every log entry should make it obvious to a human or script *why* something failed and *what to do next*.
+
+---
+
+## Configuration & Tuning
+
+### Heartbeat Thresholds (seconds)
+
+Tune these based on your infrastructure speed:
+
+```bash
+get_hb_threshold() {
+  local name="$1"
+  case "$name" in
+    *monitor*)  echo 3600 ;;   # Orchestration monitor: 1 hour (low-frequency signal collection)
+    *watchdog*) echo 300  ;;   # Watchdog daemon: 5 minutes (tight, frequent backup cycles)
+    *backup*)   echo 300  ;;   # Backup script: 5 minutes (same cadence as watchdog)
+    *)          echo 300  ;;   # Default: 5 minutes
+  esac
+}
+```
+
+- **Increase thresholds** if your infrastructure is slow (slow disks, high load, slow network).
+- **Decrease thresholds** if you want faster failure detection (but risk false STALE alerts during heavy AV scans).
+
+### Secret Scanning Scope
+
+Change `scan_tracked_files()` to scan only staged files instead of modified files:
+
+```bash
+scan_tracked_files() {
+  local repo="$1"
+  # Alternative: scan only files staged for commit
+  git diff --cached --name-only 2>/dev/null | xargs -r secret_scan.py
+}
+```
+
+### Logging Detail
+
+Increase logging verbosity to diagnose AV conflicts:
+
+```bash
+log "git fetch returned $?: $(cd $repo && git fetch -q origin 2>&1 | head -c 100)"
+```
+
+---
+
+## Testing & Validation
+
+### Test Case: Simulate Binary Deletion
+
+```bash
+# 1. Start watchdog in background
+bash $AESOP_ROOT/daemons/run-watchdog.sh &
+WATCHDOG_PID=$!
+
+# 2. Simulate git deletion
+mv /c/Program\ Files/Git/bin/git.exe /tmp/git.exe.bak
+
+# 3. Wait for next cycle
+sleep 160
+
+# 4. Check logs
+tail -20 $AESOP_ROOT/state/FLEET-BACKUP.log
+
+# 5. Restore git
+mv /tmp/git.exe.bak /c/Program\ Files/Git/bin/git.exe
+
+# 6. Next cycle should recover
+sleep 160
+tail -10 $AESOP_ROOT/state/FLEET-BACKUP.log
+```
+
+### Expected Output
+
+```
+[2026-07-11 10:30:15] === cycle start ===
+[2026-07-11 10:30:16] BLOCKED: my-repo
+[2026-07-11 10:30:16] === cycle end ===
+[2026-07-11 10:32:16] === cycle start ===
+[2026-07-11 10:32:17] CLEAN: my-repo   # (or PUSHED if changes made during downtime)
+[2026-07-11 10:32:17] === cycle end ===
+```
+
+---
+
+## References
+
+- [SentinelOne Behavioral Engine False Positives](https://community.sentinelone.com/)
+- [Windows Defender ASR Rules](https://learn.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/attack-surface-reduction)
+- [Git Best Practices for Automation](https://git-scm.com/docs/git-var)
+- Aesop docs/STATE-MACHINE.md — Durable checkpointing recovery
+- Cardinal Rule 3 (main CLAUDE.md) — "Reliability core: Inputs ALWAYS produce outputs"

package/monitor/CHARTER.md

@@ -0,0 +1,66 @@
+# Aesop Orchestration Monitor — Charter
+
+A standing background monitor (Haiku subagent) that watches how the multi-agent system operates and acts on points of refinement. It improves the *machinery*, never the *mission*.
+
+## FIXED GOAL (never changes)
+
+> Maintain your projects correctly, cheaply, and autonomously under your cardinal rules.
+> The monitor's job is to make that machine run better — it must NOT redirect, re-scope,
+> or invent new project goals. If it ever thinks the goal should change, it writes a note
+> in `PROPOSALS.md` and stops there.
+
+## What it watches
+
+1. **Heartbeat health** — are loop daemons alive? (watchdog ~300s, monitor ~3600s)
+2. **Security alerts** — any high/medium severity issues in the fleet?
+3. **Log rotation** — do append-only logs need archiving?
+4. **Memory staleness** — are project notes up to date?
+5. **Orchestration drift** — are agents following the cardinal rules?
+
+## Action tiers
+
+- **AUTO (apply immediately, then log to `ACTIONS.log`):**
+  - Heartbeat freshness checks (read-only).
+  - Log rotation (invoke `rotate_logs.py` if available).
+  - Persist project memory updates (if applicable).
+  - Quarantine defunct scripts (if a quarantine directory exists).
+
+- **PROPOSE (write to `PROPOSALS.md`, do NOT apply — needs user approval):**
+  - Changes to cardinal rules or agent configuration.
+  - Alterations to agent behavior or model choice.
+  - Deletions of anything outside the monitor's own quarantine.
+  - Any change to orchestration policy.
+
+## Hard guardrails (inviolable)
+
+- Preserve the FIXED GOAL. Improve rules; never rewrite intent.
+- **Subagents are ALWAYS Haiku** (cost optimization). Orchestrator on main thread only.
+- NEVER push destructively or to restricted remotes as an AUTO action.
+- Idempotent + additive: safe to run repeatedly; prefer append over overwrite.
+- Stay cheap: read the signal brief, not raw logs. One tight cycle, then sleep.
+
+## Outputs
+
+- `BRIEF.md` — human-readable status snapshot.
+- `SIGNALS.json` — machine-readable metrics and findings.
+- `ACTIONS.log` — append-only record of AUTO actions taken (timestamped).
+- `PROPOSALS.md` — staged changes awaiting user approval.
+- `quarantine/` (optional) — parked suspect scripts + manifest.
+
+## Operating it
+
+1. **Deploy the monitor** under `/power` or as a continuous background task.
+2. **Arm the charter**: customize this file with your project names, repos, and thresholds.
+3. **Review PROPOSALS.md** periodically; approve changes or reject them.
+4. **Check ACTIONS.log** to see what was automated.
+5. **Archive BRIEF.md snapshots** if you want a historical record.
+
+## Customization
+
+Edit `collect-signals.mjs` to:
+- Add your own repo paths and project names.
+- Define custom signal collectors (e.g., junk-script detection).
+- Set heartbeat thresholds appropriate to your workflow.
+- Integrate security scanners or compliance checks.
+
+See comments in `collect-signals.mjs` for extension points.