Blacksite/AGENTS.md

# Blacksite Codex operating rules

## Sources of truth

For desired scope and acceptance:

1. The user's latest instruction.
2. The current Gitea issue, epic, and milestone scope, including newer explicit scope-change comments.
3. The active implementation plan, when one exists.

For actual implemented behavior:

1. Current source code and schemas.
2. Current tests and deterministic generated outputs.
3. Current native acceptance evidence.
4. Canonical current documentation.

For architecture:

1. Accepted ADRs.
2. Current public types and dependency boundaries.
3. Canonical architecture documentation.

Before using repository documentation as design guidance, read `docs/authority.toml`. Historical
plans, evaluations, session logs, archived docs, and superseded docs are not current implementation
guidance. When sources conflict, do not silently blend them. Reconcile current code, canonical docs,
active tracker scope, and the user's latest direction.

## Work modes and remote authority

- "Plan", "audit", "investigate", "review", and "propose" are read-only unless the user explicitly
  authorizes mutation.
- "Implement", "fix", "apply", and equivalent wording authorize local repository edits.
- Do not push, force-push, close tracker items, create tracker items, or change milestone scope without
  authority from `.codex/workflow.toml` or a direct user instruction.
- Routine Gitea comments and checklist synchronization may occur only through
  `blacksite-gitea-sync` and within its configured permissions.

## Start of task

1. Read `.codex/session/STATE.md` when it exists.
2. Verify repository root, canonical real path, branch, HEAD, dirty state, and relevant active
   processes.
3. Read the closest applicable `AGENTS.md` files.
4. Read only canonical docs for the affected topic as classified by `docs/authority.toml`.
5. Read exact linked Gitea items when the task is tracked.
6. Establish the goal, acceptance criteria, non-goals, affected subsystem, and verification tier.

Do not repeat broad repository discovery when valid session state already exists.

## User steering and scope deltas

User steering is authoritative. When the target changes materially:

1. Record a scope delta in `.codex/session/STATE.md`.
2. Classify it as an active-slice refinement, discovered blocker, added acceptance criterion, or
   separate follow-up.
3. Record which evidence remains valid and which gates are invalidated.
4. Synchronize active tracker scope/status through the configured workflow when appropriate.
5. Continue without rerunning unrelated gates or rediscovering the repository.

A missing product behavior found during native acceptance is not unrelated merely because it was
absent from the first prompt.

## Token and context discipline

- Search before reading large files; use targeted ranges and do not reread unchanged files.
- Keep raw command output in `.codex/logs/`; report concise results and bounded actionable excerpts.
- Never dump full issue lists, accessibility trees, desktop state, or build logs when exact queries
  are available.
- Keep `.codex/session/STATE.md` current for compaction, reconnects, and path remapping.
- Use subagents only for narrow independent work that does not duplicate repository context.

## Architecture for fast iteration

- Minimize technical debt at the point of change. New behavior belongs in the smallest owning
  domain module; an already-large file is not permission to grow it.
- Keep Inspector and Content Browser panel shells thin and dispatch through registered/domain
  extension seams. Run `python scripts/codex/architecture_audit.py check` for production changes.
- Architecture-audit exceptions must name a tracker issue, rationale, hard cap, extraction target,
  and expiry milestone; passing with an exception is not completion evidence.
- Keep UI-independent logic out of the heavy editor UI crate when practical.
- Prefer `shared`, `content_pipeline`, or another lightweight core crate for schemas, transactions,
  classification, import planning, validation, and deterministic processing.
- The editor renders state and dispatches operations; it should not own reusable headless logic.
- `xtask` and headless processors must not depend on the editor crate.
- Put non-rendering tests in the lightest crate that owns the invariant.
- Do not add Bevy rendering dependencies to headless code without a proven requirement.

## Verification

Use `blacksite-selective-verify` and its verification matrix.

- **Fast loop:** formatting as needed, affected-package check, and focused tests.
- **Slice gate:** affected-package tests and Clippy plus relevant domain checks.
- **Candidate gate:** full workspace/all-feature tests and lint, deterministic content checks,
  validators, packaging, and named native scenarios.

Do not run the candidate gate during ordinary iteration. Do not run a full workspace check directly
before a full workspace test unless it covers an otherwise-uncompiled target. Do not rerun a passed
gate when its inputs are unchanged. Never use unscoped `cargo clean`; scoped lane deletion is allowed
only through the build-storage workflow. Keep toolchain, features, profile, target, build directory,
and `RUSTFLAGS` stable within a lane.

## Build artifacts and disk budget

- Every Codex Cargo invocation runs through `scripts/codex/verify.py` or
  `scripts/codex/cargo_lane.py`.
- Do not invent ad hoc target directories.
- Use one persistent ordinary-development cache. Candidate, all-feature/hot-reload, full-debug,
  cross-target, and package caches are exceptional lanes with explicit retention limits.
- Run `scripts/codex/build_storage.py enforce --phase pre` before a heavy build and `--phase post`
  afterward.
- Do not contaminate the persistent lane with a different feature set, profile, target, wrapper,
  linker configuration, or `RUSTFLAGS`.
- Preserve required binaries/evidence before pruning a disposable lane.
- Never delete individual files from Cargo's `deps`, `.fingerprint`, `build`, or `incremental`
  layouts by age. Delete only a complete verified workflow-managed lane.
- At the hard limit or free-space floor, stop starting heavy builds, prune safe expired lanes, and
  schedule a persistent-lane reset at a safe slice boundary if still required.

## Documentation maintenance

Update documentation in the same task when behavior, architecture, or user workflows change, but
publish canonical updates at a stable slice boundary rather than after every tiny edit. Use
`blacksite-doc-integrity`; classify every document in `docs/authority.toml`; and treat historical
plans and evidence as records, not current requirements.

| Change type | Canonical home |
|-------------|----------------|
| Architecture or crate boundary | Accepted ADR in `docs/adr/` |
| Editor framework intent or non-goals | `docs/mission.md` |
| Editor feature workflow | `docs/editor/` |
| User controls, commands, troubleshooting | Root `README.md` |
| Shipped feature completion | Root README implementation checklist |
| Bevy upgrade policy | ADR 0002 and its migration notes |
| Milestone scope before implementation | An active `.cursor/plans/` plan |

Keep one home per fact. Link instead of copying contracts across README, guides, plans, ADRs, and
tracker bodies. New subsystems must be indexed in `docs/README.md` and, when editor-facing,
`docs/editor/README.md`. Record deliberate gaps as future work in the owning canonical doc or an ADR
Consequences section.

## Gitea

- Read exact linked issues, epics, and milestones; avoid broad unfiltered listing.
- Distinguish Implementing, Engineering-complete, Acceptance-in-progress, Candidate-ready, and
  Closed.
- Add at most one meaningful tracker update per completed slice or material scope change.
- Do not mark criteria complete without code/test/native evidence, and do not call an issue complete
  from a dirty worktree.
- Closure requires a nominated commit and configured release evidence.
- Keep epic checklists and milestone composition aligned with material child-scope changes.

## Native editor quality

Use `blacksite-editor-ux` for editor UX changes and `blacksite-native-qa` for interactive evidence.
Automated tests are not user acceptance. For UI work, exercise the rendered interaction flow and
relevant empty, selection, invalid, read-only, narrow-layout, cancel, undo, and restart states. Honor
an explicit user instruction that they will perform visual QA.

## Completion states

Use these states precisely:

- Implementing
- Engineering-complete
- Acceptance-in-progress
- Candidate-ready
- Accepted/closed

Do not say "complete" when only engineering checks pass. Once the current acceptance target is met,
stop broad adjacent auditing unless a shared invariant requires a bounded sibling audit or the user
asks for more.