stack/AGENTS.md

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 <dataRoot>/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 <task.json> · 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|resolve-role · agent.sh <name> (interactive TUI agent) · suites: test-config.sh, test-task.sh, test-release.sh, test-conductor.sh.

Full reference — usage, fields, exit codes, safety notes: docs/TOOLS.md (read on demand; do not rely on this summary for detail).

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/ROADMAP.md — agreed milestone path (M16+)
• 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.