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` ·
`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/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.