Files

T

jason.woltje 0273a84549 docs: AGENTS.md - session recovery shim, invariants canon, session registry

- AGENTS.md at root: pi loads it automatically at every session start
  (conductor-level sessions; workers deliberately exclude it via
  --no-context-files). Deliberately short: invariants, session protocol,
  role model, command surface, data map, pointers - depth stays in docs/.
- docs/SESSIONS.md: append-only session registry, mandatory per session.
- Recovery rule encoded: compaction/restart loses nothing - AGENTS.md +
  CURRENT.md + git log + suites reconstruct state; never guess.

2026-09-03 11:02:19 -05:00

5.5 KiB

Raw Blame History

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)

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.
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).
Secrets never enter the repository or container images; auth is runtime-only (read-only mount or environment variable).
Contracts (contracts/) are immutable and image-baked. Missions and tasks are declarative JSON with strict schemas.
Run records under <dataRoot>/runs/ are write-once evidence — never rewritten, only pruned via prune with a receipt.
Fail closed: missing or invalid config/policy refuses the operation. Never improvise around a refusal; diagnose it.
Policy: missions govern tasks (least-privilege intersection — a task narrows, never widens). Role authority is declared in roles/ and changes only via reviewed commits.
Git: commit only after suites are green; push only main; never force-push. scripts/conductor-apply.sh commits locally — push stays an explicit act.
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

Data map (canon)

~/.config/mosaic-dev/config.json — system config (user-authored; never auto-written).
<dataRoot> (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.

5.5 KiB Raw Blame History

AGENTS.md — Mosaic Stack rebuild (mosaicstack/stack-v2)