feat: complete M2 content workspace and inspector
This commit is contained in:
1 parent
931f561e7f
commit
cf6eaba534
438 files changed
+59749
-19043
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user