@matt82198/aesop 0.1.0 → 0.3.1

package/skills/fleet/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: fleet
+description: One-shot fleet snapshot (agents, heartbeats, tracker lanes, orchestrator status).
+version: 1.0.0
+---
+
+# Fleet — Snapshot of live fleet state
+
+One-line status summary for aesop fleet operations, showing active agents, daemon health, tracker backlog, and orchestrator phase.
+
+## Procedure
+
+Run the fleet snapshot tool and parse the JSON output:
+
+```bash
+aesop fleet
+```
+
+### Output format
+
+JSON object with:
+
+- **timestamp**: ISO 8601 when snapshot was taken
+- **aesop_root**: Fleet root directory (from AESOP_ROOT env or process.cwd())
+- **heartbeats**: Object with watchdog and monitor pulse status
+  - **watchdog**: age_seconds, status (OK/STALE/MISSING), threshold_seconds
+  - **monitor**: age_seconds, status (OK/STALE/MISSING), threshold_seconds
+- **agents**: Array of active agents OR unavailable message
+  - Each agent: id, project, status, age_s, hint, startedAt, lastActivity, runtimeSeconds, tokensUsed, taskLabel, promptFull
+- **tracker**: Tracker backlog counts by lane OR unavailable message
+  - total_items: sum of all items
+  - by_lane: object mapping lane names to counts
+- **orchestrator**: Current orchestrator status OR unavailable message
+  - activity, phase, timestamp (from state/orchestrator-status.json)
+
+### Graceful degradation
+
+All missing state files produce explicit `unavailable: "<reason>"` entries rather than crashing:
+
+- watchdog heartbeat missing → `unavailable: "MISSING"`
+- monitor heartbeat missing → `unavailable: "MISSING"`
+- dash-extra.mjs not found → `agents: { unavailable: "dash-extra.mjs not found" }`
+- tracker.json missing/malformed → `tracker: { unavailable: "tracker.json not found or malformed" }`
+- orchestrator-status.json missing → `orchestrator: { unavailable: "orchestrator-status.json not found or malformed" }`
+
+### Example output
+
+```json
+{
+  "timestamp": "2024-07-17T14:32:05.123Z",
+  "aesop_root": "/path/to/aesop",
+  "heartbeats": {
+    "watchdog": {
+      "age_seconds": 42,
+      "status": "OK",
+      "threshold_seconds": 300
+    },
+    "monitor": {
+      "age_seconds": 1203,
+      "status": "OK",
+      "threshold_seconds": 3600
+    }
+  },
+  "agents": {
+    "count": 2,
+    "agents": [
+      {
+        "id": "a1b2c3d4e5f6g7h",
+        "project": "aesop",
+        "status": "running",
+        "age_s": 35,
+        "hint": "Implement /fleet CLI feature",
+        "startedAt": "2024-07-17T14:31:30Z",
+        "lastActivity": "2024-07-17T14:32:05Z",
+        "runtimeSeconds": 35,
+        "tokensUsed": 45000,
+        "taskLabel": "FEATURE — fleet skill CLI part",
+        "promptFull": "..."
+      }
+    ]
+  },
+  "tracker": {
+    "total_items": 8,
+    "by_lane": {
+      "ranked": 3,
+      "in-progress": 2,
+      "proposed": 3
+    }
+  },
+  "orchestrator": {
+    "activity": "dispatching",
+    "phase": "wave-14",
+    "timestamp": "2024-07-17T14:32:00Z"
+  }
+}
+```
+
+### Integration with orchestrators
+
+Orchestrators invoke `aesop fleet` (instead of ad-hoc state reads) to stay coupled to this canonical format. All data is read-only; the command never mutates state.
+
+### Machine-readable parsing
+
+Parse the JSON and check for `unavailable` fields at each level:
+
+```javascript
+const fleet = JSON.parse(output);
+if (fleet.heartbeats.watchdog.unavailable) {
+  console.log('Watchdog is', fleet.heartbeats.watchdog.unavailable);
+} else {
+  console.log('Watchdog is', fleet.heartbeats.watchdog.status, 'age', fleet.heartbeats.watchdog.age_seconds + 's');
+}
+```

package/skills/power/SKILL.md

@@ -1,161 +1,276 @@
 ---
 name: power
-description: Prime the "filesystem brain" — load all operating rules, behaviors, the multi-agent dispatch model, memory, and the current project's semantics from disk. Report a compact primed brief with system health and next steps.
-version: 1.0.0
+description: Initialize Aesop into ANY repo (first-run) or prime the orchestration brain (already-primed). Loads rules, memory, and project state; writes CLAUDE.md layer for unprimed repos.
+version: 2.0.0
 ---
 
-# Power — prime the filesystem brain
+# Power — Initialize or Prime the Orchestration Brain
 
-Everything that governs how I should behave lives on disk. This skill reads it, internalizes it,
-and reports a compact "primed" summary — **without inflating context** (code is read via subagents
-that return briefs, not dumped raw).
+This skill makes Aesop work in ANY repository — either initializing a new codebase for the first time (init-prime) 
+or loading an already-primed project's rules and state.
 
-The principle: **all rules can be abstracted to consistent agent behavior.** Rules are files;
-reading them = becoming the agent the files describe.
+**Core principle**: All orchestration rules live on disk as readable `.md` files. This skill reads them, internalizes them,
+and reports a compact "primed" summary — enabling autonomous dispatch under the loaded rules.
 
-**Scope: this is a priming skill for aesop orchestration itself** — rules, dispatch model, memory,
-machinery health. Running it does NOT imply any particular project is being worked on. Project
-state loads only when the session is actually resuming that project (step 3); deferred projects
-are rolled up to counts, never item-by-item — and their repos/daemons are left untouched.
+**Prerequisites**: Before running `/power`, the Aesop harness must be installed in the repository. Use the CLI to scaffold:
+```bash
+# Scaffold the Aesop harness (daemons, skills, tools, hooks) into your repo
+npx @matt82198/aesop . --name "my-project"
+# or run `npx @matt82198/aesop --help` for more options
+```
+The CLI automatically installs git hooks, copies all necessary directories, and generates initial config files. Then run `/power` to prime the orchestration brain.
 
-## Procedure (run in order)
+---
+
+## Quick Start: Two Paths
+
+### Path 1: First Time? (Init-Prime)
+If the target repository has **no CLAUDE.md layer** (i.e., no project-root `CLAUDE.md`, no domain `CLAUDE.md` units):
+
+1. Run `/power` in the repository root (after CLI setup above)
+2. Aesop will **automatically**:
+   - Fan out read-only Haiku explorers to scan the codebase (briefs only, never raw dumps)
+   - Write a project-root `CLAUDE.md` (purpose, build/run commands, gotchas)
+   - Write smallest self-contained **domain `CLAUDE.md` units** (module layout, key contracts, invariants)
+   - Write a `STATE.md` checkpoint seed if warranted
+   - Commit + push the new `.md` layer (gated by secret-scan)
+3. Every future `/power` run then takes the **fast path** (already-primed).
+
+### Path 2: Already Primed?
+If the repository **already has CLAUDE.md layer** (project-root + domain CLAUDE.md files ± STATE.md):
+
+1. Run `/power` in the repository root
+2. Aesop will **load the persisted semantic memory** from disk (no re-investigation needed)
+3. Report a compact primed brief with health checks and next steps
+4. Proceed under the loaded dispatch model
+
+---
+
+## Procedure (in order)
+
+### 1. Detect priming status
+
+**Check if this codebase has been primed before:**
+- Does a project-root `CLAUDE.md` exist in the target repository root?
+- Do any domain-scoped `CLAUDE.md` files exist (e.g., `src/CLAUDE.md`, `api/CLAUDE.md`)?
+- Does `STATE.md` or similar checkpoint exist?
+
+**If YES** → This codebase is **already primed**. Jump to **Step 2: Already-Primed Fast Path**.
+
+**If NO** → This codebase is **unprimed**. Jump to **Step 2: Init-Prime Path**.
+
+---
+
+### 2A. Already-Primed Fast Path
 
-### 1. Load global rules + dispatch model
+For an already-primed codebase:
+
+#### 2A.1 Load global rules + dispatch model
 Read these directly (they are small and authoritative):
-- `~/.claude/CLAUDE.md` — the **cardinal rules** (autonomous continuation, dispatch model, 
-  durable checkpointing, build env). These override defaults.
-- Any project-local `CLAUDE.md` in the current working directory and its parents.
-
-Then run the **brain integrity check**: `~/.claude` should be a git repo (if you version it). 
-Check `git -C ~/.claude status --porcelain` and ahead/behind vs origin:
-- Deliberate uncommitted rule/hook/skill/memory changes → commit + push now (gated by 
-  `python <project-root>/tools/secret_scan.py --staged`);
-- **Unexpected** modifications or deletions → report as alert — stop, diff against remote, restore 
-  before continuing (core defense: don't let tooling shadow your rules).
-
-Also check for unactioned entries in `~/.claude/PROPOSALS.md` or similar and surface a 
-one-line summary of each in the primed report.
-
-Internalize the **dispatch model** and apply it for the rest of the session. Document
-the dispatch model's key invariants locally (in your private repo's `CLAUDE.md`, 
-if you version `~/.claude`), for example:
-- **Subagents model** (Haiku vs specialists vs orchestrator tier)
-- **Parallelism defaults** (e.g., fan out 6–8 Haikus per domain)
-- **TDD-first discipline** and checkpointing (STATE.md, BUILDLOG.md)
-- **Observable machinery**: every action logged, every cost tracked
-
-### 2. Load memory
-- Read `~/.claude/memory/MEMORY.md` (the index, or use your configured path).
-- For any memory entry whose one-line hook is relevant to the current task/project, 
-  read that memory file.
-- Treat recalled memories as background context that reflects when they were written — 
-  **verify any file/flag/path they name still exists before relying on it.**
-
-### 3. Load the active project's state
-If working inside (or resuming) a known project, read its durable checkpoint first:
-- Look for a `STATE.md` and `BUILDLOG.md` in the project root or a handoff folder.
-- `STATE.md` is the source of truth for intent, locked decisions, contracts, and **NEXT STEPS**.
-- Re-sync from disk (git log, file state) — never trust stale assumptions.
-
-### 4. Codebase semantics — already-primed vs first-time init
-**First check whether this codebase has been primed before**: does it already carry its scoped
-`.md` layer (a project-root `CLAUDE.md`, domain `CLAUDE.md` units, a `STATE.md`)?
-
-- **Already primed** (has `CLAUDE.md`s and optionally `STATE.md`): do NOT re-investigate the code. 
-  The `.md` layer IS the persisted semantic memory — the project `CLAUDE.md`s are sufficient; 
-  the codebase is simply **ready to work**. Only re-scan a specific domain if its `CLAUDE.md` 
-  is contradicted by on-disk reality (then fix the `.md`, which is the bug).
-- **First time / not primed** (no scoped `.md`s found): run **init-prime** — fan out Haiku 
-  subagents to read the whole codebase (briefs only, never raw dumps) and **autonomously write 
-  the scoped `.md` layer it needs**:
-  - a project-root `CLAUDE.md`: purpose, build/run commands + toolchain, top gotchas
-  - smallest self-contained **domain `CLAUDE.md` units** (minimal, never lossy) — module layout, 
-    key contracts, domain logic, non-obvious invariants
-  - a `STATE.md` checkpoint seed if the work warrants it
-  
-  Commit + push the new `.md`s (secret-scan gated). Every future `/power` on that codebase 
-  then takes the already-primed fast path.
+- `~/.claude/CLAUDE.md` — the **cardinal rules** (autonomous continuation, dispatch model, durable checkpointing, build env)
+- Project-root `CLAUDE.md` in the current working directory
+
+Then run the **brain integrity check**: if you version `~/.claude` as a git repo, check:
+```bash
+git -C ~/.claude status --porcelain
+```
+and ahead/behind vs origin. If there are:
+- **Deliberate uncommitted rule/hook/skill/memory changes** → commit + push now (gated by `python <project-root>/tools/secret_scan.py --staged`)
+- **Unexpected** modifications or deletions → report as alert, stop, diff against remote, restore before continuing
+
+**Internalize the dispatch model** — document its key invariants locally in your session context (do not modify `.md` files during this step).
 
-### 5. Report "primed" (compact)
+#### 2A.2 Load memory
+- Read `~/.claude/MEMORY.md` (index) and cross-reference any entries relevant to the active project or session task
+- For each recalled memory entry, read its full file
+- **Verify any file/flag/path they name still exists before relying on it**
+
+#### 2A.3 Load the active project's state
+- Look for `STATE.md` or `BUILDLOG.md` in the project root
+- `STATE.md` is the source of truth for intent, locked decisions, contracts, and **NEXT STEPS**
+- Re-sync from disk (`git log`, file state) — never trust stale assumptions
+
+#### 2A.4 Report "primed" (compact)
 Output a short brief, not a wall of text:
 
-- **Drain the UI inbox first** (if configured in `aesop.config.json`): run 
-  `python <project-root>/tools/inbox_drain.py pending`. If items exist, surface each under 
-  a **"QUEUED FROM DASHBOARD"** heading as `[ISO-ts] text` one-liners. Mark them processed 
-  (`python <project-root>/tools/inbox_drain.py mark-all`) after actioning.
-- **Health line first**: run `python <project-root>/tools/power_selftest.py` and lead with its 
-  `POWER-SELFTEST:` line (hooks, brain push state, heartbeats, decisions, scanner state).
-  Bullet anything non-OK.
-- **Open decisions**: surface each ACTIVE line of any decisions/proposals file and any 
-  unactioned inbox entries as one-liners (rolled-up counts for deferred items, never item-by-item).
-- **Rules loaded**: dispatch model + any project-specific overrides in one or two lines.
-- **Project**: name, purpose, status, repo, key paths.
-- **Semantics**: the domain model + main flow in a few bullets.
-- **Gotchas**: the verified ones that change how I act.
-- **Next steps**: from `STATE.md`, ready to execute (autonomously, per the dispatch model).
-
-### 6. Project app launch (if applicable)
+- **Drain the UI inbox first** (if configured in `aesop.config.json`): run `python <project-root>/tools/inbox_drain.py pending` and surface each item as a one-liner under a **"QUEUED FROM DASHBOARD"** heading
+- **Health line first**: run `python <project-root>/tools/power_selftest.py` and lead with its `POWER-SELFTEST:` line (hooks, brain push state, heartbeats, decisions, scanner state). Bullet anything non-OK.
+- **Open decisions**: surface each ACTIVE line from any decisions/proposals file and unactioned inbox entries as one-liners
+- **Rules loaded**: dispatch model + any project-specific overrides in one or two lines
+- **Project**: name, purpose, status, repo, key paths
+- **Semantics**: the domain model + main flow in a few bullets
+- **Gotchas**: the verified ones that change how you act
+- **Next steps**: from `STATE.md`, ready to execute (autonomously, per the dispatch model)
+
+#### 2A.5 Project app launch (if applicable)
 After reporting primed, bring the active project's runnable app up in the BACKGROUND if it has one.
-Make it **idempotent**: if the port is already serving a healthy instance, skip the start and 
-just report the URL.
-
-**Pattern** (project adopters fill in their own):
-- Define a `run` skill or script in your project (or use an existing `start`/`run` command).
-- Detect if the service is already healthy (e.g., `curl -s -o /dev/null -w '%{http_code}' http://localhost:PORT/`).
-- If healthy (200), skip startup and just report the URL.
-- If not healthy, start the service in the background via Bash with `run_in_background: true`.
-- Poll readiness WITHOUT blocking sleep: use curl retries or a cheap probe loop.
-- Report the URL + background task ID so it can be stopped on request.
-
-**DO NOT** hardcode personal app paths (e.g., Spring Boot repos, IDEs, personal tools). 
-Instead, document in your project's `CLAUDE.md` how to launch the app, and reference that 
-in your local version of this skill or a project-specific override.
-
-### 6b. Machinery health — orchestration monitor (optional)
+Make it **idempotent**: if the port is already serving a healthy instance, skip the start and just report the URL.
+
+**Pattern** (documented in your project's `CLAUDE.md`):
+- Detect if the service is already healthy (e.g., `curl -s -o /dev/null -w '%{http_code}' http://localhost:PORT/`)
+- If healthy (200), skip startup and just report the URL
+- If not healthy, start the service in the background via Bash with `run_in_background: true`
+- Poll readiness WITHOUT blocking sleep: use curl retries or a cheap probe loop
+- Report the URL + background task ID so it can be stopped on request
+
+**DO NOT** hardcode paths. Instead, document in the project's `CLAUDE.md` how to launch the app and reference that in this skill or a project-specific override.
+
+#### 2A.6 Machinery health (optional)
 If your project uses an orchestration monitor, spin up a **background Haiku agent** that:
 1. Collects health signals (cheap, deterministic)
-2. Reads only that brief and acts per a charter — AUTO-applies safe refinements and stages 
-   rule/behavior changes to a `PROPOSALS.md` for review
+2. Reads the brief and acts per a charter — AUTO-applies safe refinements and stages rule/behavior changes to `PROPOSALS.md` for review
 3. Self-paces via ScheduleWakeup and beats a heartbeat
 
 Skip if `.monitor-heartbeat` is already <300s old. Announce its task id so it can be paused/stopped.
 
-### 7. Standing dev loops (optional; only when actively developing)
-If the session is doing active development (writing/changing code — not just answering questions),
-keep these background loops running continuously. They are the "tail": cheap, persistent, 
-append-only, and never inflate the main context.
+#### 2A.7 Standing dev loops (optional; only during active development)
+If the session is actively developing (writing/changing code — not just answering questions),
+keep these background loops running continuously. They are the "tail": cheap, persistent, append-only.
 
-**Patterns** (project adopters fill in their own):
+**Patterns** (documented in your project's `CLAUDE.md`):
 
-1. **Build/status + backup watchdog** (background bash loop) — appends timestamped git/test/build
-   snapshots. For example, if your project has a `daemons/` folder with a `run-watchdog.sh`, 
-   launch that via Bash with `run_in_background: true` and let it beat a heartbeat so you know 
-   it is live. Stop with TaskStop when development pauses.
+1. **Build/status + backup watchdog** (background bash loop) — appends timestamped git/test/build snapshots. For example, if your project has a `daemons/` folder with a `run-watchdog.sh`, launch that via Bash with `run_in_background: true` and let it beat a heartbeat
+2. **Memory keeper** (Haiku, background) — as new decisions, contracts, or gotchas emerge, updates relevant memory files compactly
+3. **Continuous QA loop** — after each feature reaches a checkpoint: Haiku reviews → Haiku bugfixes → Haiku lint/format, looping until build is green and review is clean, with Opus orchestrator final-catch before merge
+4. **Tail-drift alignment** (Haiku, background) — periodically checks in-flight agents' output against their domain `CLAUDE.md` contract, realigns if drifting
+5. **Hung-Haiku watchdog** (orchestrator's main thread, NOT a subagent) — keep watching every spawned Haiku for stalls; on hang: TaskStop it and relaunch from checkpoint
 
-2. **Memory keeper** (Haiku, background) — as new decisions, contracts, or gotchas emerge, 
-   updates the relevant memory files compactly (one fact per memory; never bloat). Re-invoke 
-   via SendMessage to keep context.
+Launch any that aren't already running; **stop them with TaskStop when development pauses**.
 
-3. **Continuous QA loop** — after each feature reaches a checkpoint: **Haiku reviews → 
-   Haiku bugfixes → Haiku lint/format**, looping until the build is green and review is clean, 
-   with **Opus orchestrator final-catch** before merge. TDD-first: failing tests before code.
+---
 
-4. **Tail-drift alignment** (Haiku, background) — periodically checks in-flight agents' output 
-   against their domain `CLAUDE.md` contract, and realigns anything drifting.
+### 2B. Init-Prime Path
 
-5. **Hung-Haiku watchdog** (orchestrator's main thread, NOT a subagent) — keep watching every 
-   spawned Haiku for stalls. On hang: TaskStop it and relaunch from checkpoint or respawn.
+For an unprimed codebase, run the following steps **in order**:
 
-Launch any that aren't already running; **stop them with TaskStop when development pauses**.
+#### 2B.1 Scan the target repository
+
+Fan out read-only Haiku subagents to explore the codebase structure:
+- **Haiku A** (30s): Repository structure, build system, entry points, main languages
+- **Haiku B** (30s): Key libraries, frameworks, external dependencies
+- **Haiku C** (30s): Testing strategy, CI/CD configuration, deployment targets
+- **Haiku D** (30s): Known gotchas, non-obvious invariants, anti-patterns in the codebase
+
+Each Haiku returns a **1-page brief** (never raw code dumps). Collect all four briefs.
 
-Mechanism: use background `Agent` (run_in_background) for keeper/drift loops, `Monitor` for 
-the watchdog, and self-pace longer cycles with `/loop` skill or `ScheduleWakeup`. 
-Always announce which loops were started (and their task IDs) so they can be paused/stopped.
+#### 2B.2 Synthesize project-root CLAUDE.md
+
+Using the four exploration briefs, **write a project-root `CLAUDE.md`** in the target repository. 
+Include:
+
+- **What**: 1-line project purpose + primary domain/stack
+- **Key commands**: build, test, run, deploy (exactly as documented in the project)
+- **Gotchas**: verified non-obvious facts that affect how you work
+  - "Tests must run in isolation (no shared DB state)"
+  - "Deploy requires manual approval in Slack"
+  - "Docker build takes 5 minutes; cache aggressively"
+- **Domain map**: 2-4 self-contained scopes, each mapping to one potential Haiku (keep it minimal; don't over-partition)
+- **See Also**: pointers to ARCHITECTURE.md, CONTRIBUTING.md, etc. if they exist in the repo
+
+**Keep the project-root CLAUDE.md small** (under 50 lines). It's a navigation map, not a textbook.
+
+#### 2B.3 Synthesize domain CLAUDE.md units
+
+For each domain identified in 2B.2, **write a scoped domain `CLAUDE.md`** in that module's root directory.
+
+**Example structure**:
+```
+my-repo/
+  CLAUDE.md              <- project-root (what, commands, gotchas, domain map)
+  src/
+    CLAUDE.md            <- domain 1 (API layer: contracts, invariants, entry points)
+    api/
+      ...
+    core/
+      CLAUDE.md          <- domain 2 (core logic: key abstractions, state machine)
+      ...
+  tests/
+    CLAUDE.md            <- domain 3 (test infrastructure: harness, fixtures)
+    ...
+```
+
+**Each domain CLAUDE.md includes**:
+- **Module layout**: directory tree, what lives where
+- **Key contracts**: public interfaces, APIs, data model
+- **Domain logic**: state machine, algorithm, non-obvious invariants
+- **Dependencies**: external libraries, internal cross-domain calls
+- **Anti-patterns**: what NOT to do in this domain
+- **Testing**: how to run tests, fixtures, mocks
+
+**Keep each domain CLAUDE.md focused and minimal** (10-20 lines; longer ones should split further).
+
+#### 2B.4 Write STATE.md checkpoint seed
+
+Create a `STATE.md` in the repository root. This is the **durable checkpoint** that survives wipes and outages:
+
+```markdown
+# {{PROJECT_NAME}} — State & Next Steps
+
+**Phase**: init-prime (first CLAUDE.md layer written)
+
+**Intent**: {{PROJECT_NAME}} is now initialized with aesop orchestration semantics. 
+All domain rules live in scoped CLAUDE.md files. Ready to dispatch first work.
+
+**Locked decisions**:
+- (none yet; updated as decisions are made)
+
+**NEXT STEPS**:
+- [ ] Review + approve the written CLAUDE.md layer
+- [ ] Run `/buildsystem` to execute one example orchestration wave
+- [ ] Iterate domain CLAUDE.md files as you discover invariants
+```
+
+#### 2B.5 Commit + Push
+
+Stage all newly written files:
+```bash
+git add CLAUDE.md STATE.md src/CLAUDE.md core/CLAUDE.md tests/CLAUDE.md
+```
+
+Commit with a clear message:
+```bash
+git commit -m "init: initialize aesop orchestration semantics — project CLAUDE.md + domain units + STATE.md seed
+
+Aesop init-prime: generated project-root CLAUDE.md (purpose, commands, gotchas), 
+minimal domain CLAUDE.md units (contracts, invariants), and STATE.md checkpoint seed.
+
+Co-Authored-By: Aesop Orchestrator <aesop@example.com>"
+```
+
+Run the **secret-scan gate**:
+```bash
+python <project-root>/tools/secret_scan.py --staged
+```
+
+**If gate fails** → fix the leaky files and re-commit (never override the gate).
+
+**If gate passes** → push to the feature branch:
+```bash
+git push origin feat/aesop-init-prime
+```
+
+(Or to `main` if you have override permissions, but best practice: feature branch → PR → review → merge.)
+
+#### 2B.6 Report init completion
+
+After a successful push, report:
+```
+✓ Aesop init-prime complete
+  - Project-root CLAUDE.md written (60 lines; purpose, commands, gotchas, 3 domains)
+  - Domain CLAUDE.md units: src/, core/, tests/
+  - STATE.md checkpoint seed created
+  - Pushed to origin feat/aesop-init-prime (gated by secret-scan, all clear)
+  
+NEXT: Review the generated `.md` layer, iterate on domains, then run /buildsystem for your first orchestration wave.
+```
+
+---
 
 ## Notes
-- If no project context exists yet, steps 1–2 still apply; skip 3–4 and say so.
-- Steps 1–5 always run on `/power`; **step 6 (launch app) runs only if the active project has one**;
-  **step 6b (monitor) runs only if configured**; step 7 (dev loops) runs only during active development.
-- Prefer subagents for anything large; the goal is a *brain*, not a *dump*.
-- After priming, proceed under the dispatch model (continue approved work autonomously; stop only 
-  for genuine decisions or unauthorized outward/destructive actions).
+
+- **If no project context exists yet** (e.g., you're answering a general question about rules): Steps 1 loads global rules; skip 2 and say so.
+- **Steps 1-5 always run on `/power`**; **step 6 (launch app) runs only if the active project has one**; **step 6b (monitor) runs only if configured**; **step 7 (dev loops) runs only during active development**.
+- **Init-prime** writes `.md` files to the target repository (never personal/system paths). All state lives under the target repo root or configured `state_root` (see `aesop.config.json`).
+- **Prefer subagents for anything large**; the goal is a *brain*, not a *dump*.
+- **After priming** (either path), proceed under the loaded dispatch model (continue approved work autonomously; stop only for genuine decisions or unauthorized outward/destructive actions).
+- **Portability**: all file paths are relative to the target repository or configurable via environment variables / `aesop.config.json` (never hardcoded personal paths). Use `~` notation for home-directory paths (e.g., `~/.claude`, `~/scripts`) for cross-platform compatibility (Windows, macOS, Linux). Config loaders automatically expand `~` at runtime.

package/state_store/__init__.py

@@ -12,13 +12,15 @@ in state_store/CLAUDE.md.
 from .api import StateAPI
 from .export import export_tracker
 from .ingest import ingest_tracker_json
-from .projections import project_tracker
-from .store import EventStore
+from .projections import project_tracker, project_agent_lifecycle
+from .store import EventStore, ConcurrencyConflict
 
 __all__ = [
     "EventStore",
     "StateAPI",
+    "ConcurrencyConflict",
     "project_tracker",
+    "project_agent_lifecycle",
     "export_tracker",
     "ingest_tracker_json",
 ]

package/state_store/api.py

@@ -7,7 +7,7 @@ stream and folds it through the registered projector.
 from __future__ import annotations
 
 from .projections import project_tracker
-from .store import EventStore
+from .store import EventStore, ConcurrencyConflict
 
 _PROJECTORS = {"tracker": project_tracker}
 
@@ -18,9 +18,24 @@ class StateAPI:
     def __init__(self, db_path: str):
         self._store = EventStore(db_path)
 
-    def append(self, stream: str, event_type: str, payload: dict, actor: str = "system") -> int:
-        """Append one event; return its new per-stream version."""
-        return self._store.append(stream, event_type, payload, actor)
+    def append(
+        self,
+        stream: str,
+        event_type: str,
+        payload: dict,
+        actor: str = "system",
+        expected_version: int | None = None,
+    ) -> int:
+        """Append one event; return its new per-stream version.
+
+        Supports optimistic concurrency control via expected_version. See
+        EventStore.append for full semantics.
+
+        Raises:
+            ConcurrencyConflict: If expected_version is provided and does not
+                               match the stream's current max version.
+        """
+        return self._store.append(stream, event_type, payload, actor, expected_version)
 
     def get(self, stream: str) -> list:
         """Return all events in ``stream`` ascending by version."""