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.