feat: complete M2 content workspace and inspector

This commit is contained in:
Rbanh committed 2026-07-17 23:40:49 -04:00
1 parent 931f561e7f
commit cf6eaba534
438 files changed
+59749 -19043

No files matched your search

+32
View File
@@ -0,0 +1,32 @@
# Build Storage Policy
Blacksite uses one persistent ordinary-development lane and creates exceptional candidate,
hot-reload, full-debug, cross-target, or package lanes only when their distinct signature is needed.
Lane identity includes the canonical workspace, toolchain, target, profile, features, linker and
compiler flags.
On the current checkout, intermediates live in a canonical-workspace partition beneath
`<workspace-parent>/.blacksite-build-cache`; this keeps the cache on the workspace volume because
Cargo home does not satisfy the configured free-space floor. Set `BLACKSITE_BUILD_CACHE_ROOT` to an
approved cache volume when the checkout moves. Final ordinary artifacts retain predictable paths
under repository `target/`, while exceptional final artifacts live under `target/lanes/<lane>`.
Use `scripts/codex/build_storage.py` for measurement, dry-run pruning, and policy enforcement. Under
budget or free-space pressure, pre/post enforcement may automatically remove only expired disposable
lanes after printing and flushing their complete byte-counted safety plan. A managed lane must carry
a sentinel identifying its workspace and signature before it is eligible for
deletion. Never run an unscoped `cargo clean` as a troubleshooting reflex, and never delete individual
files from Cargo's `deps`, `.fingerprint`, `build`, or `incremental` layouts by age. Pruning removes
only a complete verified disposable lane.
Before a heavy gate, enforce the configured total budget and free-space floor; remaining hard-limit
or free-space violations block the gate. Afterward, record lane size and last use. Every automatic or
explicit prune/reset prints and flushes its complete byte-counted, checked plan before deletion starts.
Before removing a candidate lane, copy the nominated binaries or
packages and evidence outside the lane, then run:
`python scripts/codex/build_storage.py mark-candidate-preserved --evidence <manifest> --artifact <binary-or-package>`
The generation-bound marker becomes stale if that candidate lane is used again. The persistent
development lane is reset only at a safe slice boundary when signature drift or the hard budget makes
that necessary.
+30
View File
@@ -0,0 +1,30 @@
# Codex Workflow
Blacksite uses a repository-local workflow to keep implementation fast without weakening acceptance.
The compact operating rules live in `AGENTS.md`; procedural details live in repository Skills and the
policies indexed here.
## Task lifecycle
1. Confirm the canonical repository path, branch, HEAD, dirty state, and active processes.
2. Resume `.codex/session/STATE.md` when valid instead of rediscovering the repository.
3. Read `docs/authority.toml`, the smallest relevant current docs, and exact linked tracker items.
4. Define one bounded slice with acceptance criteria, non-goals, and a verification tier.
5. Record material user steering as a scope delta, including which evidence remains valid.
6. Run selective verification, then update canonical docs at the slice boundary.
7. Treat native acceptance and release-candidate gates as separate states from engineering checks.
Ignored `.codex/session/`, `.codex/logs/`, `.codex/cache/`, and `.codex/evidence/` data is working
state, not documentation. It exists to make reconnects and compaction cheap and must not become a
second source of product truth.
## Policies
- [Documentation authority](documentation-policy.md)
- [Selective verification](verification-policy.md)
- [Build storage](build-storage-policy.md)
- [Gitea tracking](gitea-tracking-policy.md)
The workflow distinguishes Implementing, Engineering-complete, Acceptance-in-progress,
Candidate-ready, and Accepted/closed. “Complete” is reserved for the acceptance state actually
proven; a dirty worktree or source-only check is not closure evidence.
+52
View File
@@ -0,0 +1,52 @@
# Documentation Authority Policy
`docs/authority.toml` classifies every root README, repository documentation page, and Cursor plan
before it may be used as guidance. Run `python scripts/codex/docs_audit.py` after changing behavior,
schemas, commands, component names, workflows, plans, or evidence records.
## Authority order
For desired scope and acceptance, use the latest user direction, exact current Gitea scope, and then
an active plan. For implemented behavior, use source and tests, then current native evidence and
canonical current documentation. Accepted ADRs own architecture decisions. Do not merge conflicting
sources silently; report and reconcile the conflict at the smallest owning surface.
## Classifications
Each authority rule has a lifecycle classification and a role. Lifecycle controls whether a page
may guide current work; roles distinguish overview, canonical behavior, architecture, active plan,
evidence, historical record, and superseded record. Accepted ADRs use the architecture role and are
authoritative only for their surviving decision scope.
| Class | Meaning | May define current behavior? |
|-------|---------|------------------------------|
| `current` | Canonical workflow, architecture, intent, or user guidance | Yes, within its stated role |
| `active-plan` | Unaccepted desired scope and acceptance work | No; source and current docs describe what exists |
| `evidence` | Dated automated or native observations | No |
| `historical` | Preserved context from completed work | No |
| `superseded` | Replaced contract retained for provenance | No |
Historical and superseded documents carry an obvious banner linking current guidance. Evidence
records carry an evidence-only banner. Active plans identify themselves and must become historical
when their acceptance target is complete.
## One home per fact
- Root `README.md`: user commands, controls, troubleshooting, and shipped checklist.
- `docs/mission.md`: product intent and non-goals.
- `docs/adr/`: accepted decisions and durable constraints.
- `docs/editor/`: current editor workflows and subsystem contracts.
- `.cursor/plans/`: active or historical implementation roadmaps, never implementation truth.
- `docs/editor/evaluations/`: dated evidence, never product requirements.
- `docs/archive/`: preserved records that no longer belong in a live topic tree.
Update canonical documentation when behavior stabilizes at a slice boundary. Tiny intermediate edits
do not require repeated narrative churn, but the slice cannot become engineering-complete while its
canonical docs contradict the implementation.
## Audit contract
The audit discovers `README.md`, every `docs/**/*.md`, and every `.cursor/plans/**/*.md`. The
highest-priority matching authority rule wins; equal-priority disagreement fails. It also verifies
lifecycle banners and configured replacement links. New documents fail until a deterministic rule
classifies them.
+17
View File
@@ -0,0 +1,17 @@
# Gitea Tracking Policy
Read exact issue, epic, and milestone records rather than broad tracker dumps. Current tracker scope
is desired behavior; source and accepted evidence determine implementation state.
Use these states precisely: Implementing, Engineering-complete, Acceptance-in-progress,
Candidate-ready, and Accepted/closed. Do not check an acceptance criterion without corresponding
code, automated, native, or candidate evidence. A dirty working tree cannot close an issue, and
closure requires the nominated commit plus configured release evidence.
Post at most one useful status update per completed slice or material scope delta. Keep epic
checklists, child issues, and milestone scope aligned, but do not create, close, reopen, delete, or
rewrite tracker scope without direct authority. Workflow installation and audits produce dry-run
recommendations only.
Tracker comments summarize outcomes and link durable repository evidence; they do not receive raw
build logs, entire issue listings, or speculative completion claims.
+25
View File
@@ -0,0 +1,25 @@
# Selective Verification Policy
Verification is proportional to the changed dependency surface and is reused while its inputs,
toolchain, features, environment, and command remain unchanged.
| Tier | Use | Typical scope |
|------|-----|---------------|
| Fast loop | Ordinary implementation edits | Formatting as needed, affected package check, focused tests |
| Slice gate | A bounded behavior slice is stable | Affected package tests and lint plus relevant domain validators |
| Candidate gate | An exact release candidate is nominated | Full workspace/all-feature gates, deterministic content checks, packaging, and named native scenarios |
Codex Cargo commands run through `scripts/codex/verify.py` or `scripts/codex/cargo_lane.py`; complete
output belongs in `.codex/logs/`. Do not run a candidate gate during ordinary iteration, duplicate a
workspace check immediately before a compiling workspace test without a distinct target reason, or
rerun a valid gate after unrelated documentation changes.
User steering invalidates only gates whose inputs or acceptance claim changed. Record that boundary
in session state. Automated tests are not native editor acceptance, and screenshots alone do not
prove an interaction.
When native acceptance is explicitly delegated, `scripts/codex/native_qa.sh plan <scenario>` prints
the named steps and assertions before anything launches. The runner snapshots a declared fixture,
records each manual assertion and target-window capture, closes only its recorded PID, and exposes a
hash-checked `restore --dry-run` / `restore --apply` pair. Planning a scenario never launches the
editor, and Codex does not take over user-owned visual QA merely because a scenario exists.