diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..17260c63 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,110 @@ +# AGENTS.md — Mosaic Stack rebuild (`mosaicstack/stack-v2`) + +Operational context for any agent session working in this repository. +Read top to bottom; it is deliberately short — depth lives in the files it +points to, not here. + +## What this repository is + +A standalone rebuild of Mosaic Stack: a file-based, fail-closed +orchestration foundation that dispatches sandboxed headless pi workers to do +real work, with immutable run records as evidence. Thirteen-plus tagged +milestones (`git tag -l`) from `poc-container-hello-v0` to today; suites +green at every step. Not production software — a proven foundation. + +## Non-negotiable invariants (the canon) + +1. **Root is bootstrap-only.** First-class system configuration lives at the + repository root; everything else gets a dedicated directory (`roles/`, + `contracts/`, `missions/`, `tasks/`, `docs/`). Do not add new files to root. +2. **Configuration**: `~/.config/mosaic-dev/config.json` is the sole system + config — created only by `scripts/bootstrap.sh`, never overwritten, + fail-closed on any problem. Repo-scoped role authority lives in + `roles/*.json` (versioned, reviewed commits only). +3. **Secrets** never enter the repository or container images; auth is + runtime-only (read-only mount or environment variable). +4. **Contracts** (`contracts/`) are immutable and image-baked. Missions and + tasks are declarative JSON with strict schemas. +5. **Run records** under `/runs/` are write-once evidence — never + rewritten, only pruned via `prune` with a receipt. +6. **Fail closed**: missing or invalid config/policy refuses the operation. + Never improvise around a refusal; diagnose it. +7. **Policy**: missions govern tasks (least-privilege intersection — a task + narrows, never widens). Role authority is declared in `roles/` and changes + only via reviewed commits. +8. **Git**: commit only after suites are green; push only `main`; never + force-push. `scripts/conductor-apply.sh` commits locally — push stays an + explicit act. +9. **Append-only logs**: BUILD-LOG.md (phases), `activation-log.jsonl`, + `.pruned.log`, docs/SESSIONS.md. Corrections are new entries, never edits. + +## Session protocol (mandatory) + +- **Register** your session in `docs/SESSIONS.md` — one append-only line + (date, actor, scope, outcome). Never rewrite or remove entries. +- **Cadence**: read `docs/plans/CURRENT.md` → execute its single next action + fully (implement → test → verify against acceptance criteria → commit → + push → close issue) → update CURRENT.md → register in SESSIONS.md. +- "next" means one action. A batch mandate ("run the queue") repeats the + loop until green or blocked. Blocked means stop and report, never improvise. +- Substantial work gets a Gitea issue and a BUILD-LOG phase entry + (before/after, with corrections recorded honestly). + +## Role model + +- **Conductor**: a system-scoped role — not an agent, not a daemon. Holds + git/credentials/policy authority; decomposes, dispatches, reviews, + verifies, integrates. Protocol: `docs/plans/CONDUCTOR.md`. Exists only + when invoked; push is never automatic. +- **Workers**: headless pi via `scripts/run-task.sh` — sandboxed workspace, + tools allowlist, optional persistent sessions and forks; no git, no + credentials, no policy control. +- Worker runs deliberately exclude this file (`--no-context-files` in the + adapter): worker context is contracts + mission via the generated system + prompt. This file is for conductor-level sessions. + +## Command surface + +`scripts/bootstrap.sh` (idempotent) · `build.sh` · `hello.sh` · +`verify.sh` · `run-task.sh run ` · `release.sh +package|activate|rollback|status` · `reset.sh` (**danger**: wipes the data +root; triple-safety-checked) · `mosaic-task.mjs validate|run|show|list|retry|prune` · +suites: `test-config.sh`, `test-task.sh`, `test-release.sh`, +`test-conductor.sh`. + +## Data map (canon) + +- `~/.config/mosaic-dev/config.json` — system config (user-authored; never + auto-written). +- `` (from config; default `~/.mosaic-dev`): + - `runs/` — write-once run evidence (`result.json`, snapshots, `stderr.txt`) + - `sessions/` — pi JSONL session trees, one directory per named session + - `workspaces/` — agent file effects (persistent or `:run` ephemeral) + - `state/` — release pointer + append-only activation/auto-apply logs +- Ownership is per-directory; nothing shares state. Directory map and + lifecycle rules: README.md "Data map" section. + +## Pointers (depth lives here) + +- `docs/plans/CURRENT.md` — THE next action (single source of "what now") +- `docs/plans/CONDUCTOR.md` — orchestration protocol and guardrails +- `docs/plans/2026-09-02_atomic-mosaic-foundation.md` — architecture, invariants +- `docs/plans/2026-09-03_autonomous-run.md` — batch-run tracker +- `BUILD-LOG.md` — append-only build/verification history with corrections +- `LAYERS.md` — implemented vs deferred layers +- `docs/SESSIONS.md` — session registry +- `adapters/README.md` — the harness adapter contract +- `roles/` — role contracts (conductor, future agent/coder/reviewer) + +## Recovery rule + +Compacted, restarted, or new? Nothing that matters is lost: this file + +`docs/plans/CURRENT.md` + `git log --oneline -10` + the suites reconstruct +the full state. **Never guess** — verify with the suites; the run records +and logs hold the receipts. + +## Version pin + +`@earendil-works/pi-coding-agent` is pinned exactly (see `package.json` / +`RELEASE`); never install unversioned. Release identity: `RELEASE` file +(0.0.X until declared stable); image tags derive from it. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..eef4bd20 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md \ No newline at end of file diff --git a/docs/SESSIONS.md b/docs/SESSIONS.md new file mode 100644 index 00000000..3fa9ddb6 --- /dev/null +++ b/docs/SESSIONS.md @@ -0,0 +1,9 @@ +# Session registry — append-only + +Every agent session (assistant, worker-cycle conductor, or owner-directed +automation) that works in this repository registers one line here. Entries +are never rewritten or removed; corrections are new entries. + +| Date (UTC) | Actor | Scope | Outcome / artifacts | +|---|---|---|---| +| 2026-09-03 | assistant (conductor + worker) | POC through M12: containerized pi proof, config layer, missions/tasks, release model, adapter seam, workspaces/capabilities, named sessions, retention, session forking, conductor auto-apply, roles/ convention | 13 tags; suites 24/58/14 + 17 conductor + verify green; releases 0.0.1–0.0.7; issues #1–#34 closed | diff --git a/docs/plans/CURRENT.md b/docs/plans/CURRENT.md index 6224d68c..d914ade8 100644 --- a/docs/plans/CURRENT.md +++ b/docs/plans/CURRENT.md @@ -28,6 +28,13 @@ Owner review of M12 (conductor auto-apply policy) — then name the next target. ## Completed log +- 2026-09-03 — M9 mission capability policy (#30) — merged, least-privilege intersection +- 2026-09-03 — test UX: green OK/red FAIL status colors (#31 adjacent) — terminal-only, pipe-safe +- 2026-09-03 — M10 run-record retention (#32) — merged, prune keep-N/dry-run/receipt, 49/24/14 + verify green +- 2026-09-03 — M11 session forking (#33) — merged, child recalls ancestor context, ancestor untouched, 58/24/14 + verify green; release 0.0.7 activated +- 2026-09-03 — M12 conductor auto-apply policy (#34) — committed on main, 17/24/58/14 + verify green; push stays explicit +- 2026-09-03 — repository convention: role contracts move to roles/ (root = bootstrap-only, per owner direction) + - 2026-09-03 — M9 mission capability policy (#30) — merged, least-privilege intersection - 2026-09-03 — test UX: green OK/red FAIL status colors (#31 adjacent) — terminal-only, pipe-safe - 2026-09-03 — M10 run-record retention (#32) — merged, prune keep-N/dry-run/receipt, 49/24/14 + verify green