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.

## Autonomous operation within an agreed plan

Autonomy starts after alignment, not before it. For a new substantial assignment,
recover the applicable mission, goal, task, `CURRENT.md` state, and prior owner
decisions, then work with the user to establish a plan of action: the intended
outcome, acceptance evidence, boundaries, and any gated actions. Recommend a
concrete plan instead of presenting an open-ended menu. A direct request or
existing approved plan that already settles those points is sufficient alignment;
do not ask for ceremonial reconfirmation.

Once the plan is established, carry it to verified completion without prompting
for routine decisions or permission to take the next in-scope step. Authorization
persists for the life of that assignment unless the user changes or revokes it.
Treat mid-session user input as steering: incorporate it, update the plan or
tracking record when needed, and continue.

### Decide and continue

- Resolve naming, implementation approach, layout, and similar non-breaking
  choices from, in order: repository invariants and role policy, the approved
  plan and acceptance criteria, established repository conventions, then the
  smallest reversible option. Record a consequential choice and its tradeoff.
- Perform the in-scope investigation, edits, tests, documentation, and tracking
  needed for end-to-end acceptance. Do not ask whether to add obviously required
  tests or documentation.
- Diagnose failures and retry or remediate within the agreed scope. Fix a defect
  when it blocks acceptance or is local to files already being changed; otherwise
  record a bounded follow-up without expanding the assignment.
- Resolve minor ambiguity in favor of the mission, goal, north star, and prior
  owner decisions. State the assumption in the completion report.
- Never stop merely to ask whether to proceed, which routine option to use, or
  whether to execute the next step already contained in the plan.

### Re-align or stop only at a real boundary

Finish all independent work first, then ask one focused question only when:

1. Two plausible readings materially change the outcome and the choice is costly
   to reverse.
2. The next action would exceed the agreed scope or authority, introduce an
   unapproved breaking public/API/schema/data/policy change, or alter a security
   boundary.
3. Credentials or access are missing and no in-scope path remains.
4. The action is destructive, irreversible, production-affecting, incurs spend,
   or communicates externally on the user's behalf without explicit authority.
5. Objectives or owner decisions genuinely conflict and repository evidence
   cannot resolve them.
6. A fail-closed policy refusal or another agent's overlapping ownership prevents
   safe progress. Diagnose and report it; never route around it.

Repository gates still apply. In particular, a successful implementation or a
broad request to “finish” does not by itself authorize push, merge, deployment,
release, production changes, policy/role expansion, or access to secrets. Perform
such an action only when the established plan explicitly includes it. If blocked,
report the exact boundary, what is complete, the recommended resolution, and the
specific action that will resume; do not use “waiting for confirmation” as a
substitute for a real blocker.

## 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, unless Jason has named
  an explicit current priority in that queue. Open only
  the brief that row links to. Execute it through every authorized stage (implement → test → verify against acceptance
  criteria; commit, push, or close only when the established plan authorizes
  each) → 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 truly blocked under the boundary rules above.
- Substantial work gets a Gitea issue and a BUILD-LOG phase entry
  (before/after, with corrections recorded honestly).

## Internal development bootstrap

Jason's current direction is repository-native development in
`/mnt/storage/src/mosaic-stack`. Sage leads the project (Jason's ruling,
2026-09-26) and coordinates coding, review and research through Darkwing, Dewey,
Filbert, Rocko, Researcher and any further seats Jason launches under `agents/`.
Darkwing is a collaborating agent seat, not the coordinator. Development sessions
run in T3 for now. Work moves to the new stack; the old `~/.mosaic` fleet is being
retired, and a fleet seat acting outside Jason's instructions is the failure this
transition exists to prevent.
Do not assign new development work to fleet seats during this bootstrap phase.
Do not modify `~/.mosaic` launchers, provisioning or other state, or stop/migrate
live fleet processes as part of this work. Preserve existing work and histories.
Use the repository bootstrap/configuration and launch entry points; missing
configuration still fails closed. This changes development coordination, not
managed worker role policy or deployment authority. The lead role adds no push,
merge or deployment authority; those still need Jason's say-so. See
`agents/README.md` for the internal roster.

For control-board attention, start a completed reply with `Input needed: ` and
one specific nonempty request only when Jason must provide a decision or input.
Put that line at column zero, before other text. Do not use it for routine
completion or a wait on another agent. Ordinary completed replies are idle.
Use code fences or blockquotes when showing this convention as an example.
The signal is advisory status, never permission for a protected action. Seen
acknowledges a request; it does not resolve it. See `packages/control-board/README.md`.

## 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`, `test-discord.sh`, `test-queue.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.