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.