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.

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.