stack/AGENTS.md

AGENTS.md — Mosaic Stack rebuild (mosaicstack/stack, branch refactor)

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

Canonical checkout: /mnt/storage/src/mosaic-stack, origin mosaicstack/stack, working branch refactor (Jason-authorized conversion, issue #1495). The new foundation is at the root. v1/ is archived legacy source, not the current implementation; its instructions and tools do not govern the new foundation. ~/src/mosaic-stack-dev-test is a compatibility symlink to this checkout, not a second working tree. Both original Git histories are retained. Conversion receipt: docs/plans/2026-09-07_repository-consolidation-completed.md.

A 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 applicable suites are green. Work on the owner-authorized refactor branch; never force-push. Push remains an explicit act. Do not merge into next or main without separate authorization. scripts/conductor-apply.sh commits locally; it does not authorize a push.
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/QUEUE.md first; your next piece is the first row you own that is briefed, in progress or in review, nothing else. Open only the brief that row links to. Execute it fully (implement → test → verify against acceptance criteria → commit → push → close issue) → move your QUEUE.md row → 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 · auth.sh status|accounts · 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, test-auth.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/QUEUE.md — THE task list (one row per piece; read first)
• docs/plans/CURRENT.md — narrative log behind the queue rows
• 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.