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

@@ -0,0 +1,23 @@
---
name: blacksite-build-storage
description: Keep Blacksite Cargo and package build artifacts within a configured disk budget by selecting stable build lanes, measuring target/build directories, pruning only verified disposable caches, and preserving warm development performance. Use before or after heavy builds, when disk use grows, or when compile performance degrades from artifact accumulation.
---
# Blacksite build storage
Read `.codex/workflow.toml` and [the storage policy](references/build-storage-policy.md). Use `scripts/codex/cargo_lane.py` for every Cargo invocation and `scripts/codex/build_storage.py` for measurement or cleanup.
Trigger this Skill for candidate, all-feature, all-target, package, hot-reload, full-debug, cache-growth, low-space, unexplained rebuild, and cleanup requests.
- Keep one persistent `dev` lane. Candidate, hot-reload, full-debug, cross-target, and package lanes are exceptional and disposable.
- Use stable separate `CARGO_BUILD_BUILD_DIR` when supported; otherwise use bounded external `CARGO_TARGET_DIR` lanes.
- Account for repository final targets, external intermediates, package caches, Cargo timings/docs, free space, and an already-enabled `sccache`.
- Run storage preflight/postflight around heavy gates. When configured, pressure may prune only
expired disposable lanes after their complete checked plan is printed and flushed.
- Require valid sentinels, canonical workspace identity, no symlink traversal, and no active Cargo/rustc/linker/packager before deletion.
- Delete whole managed lanes only. Never delete individual Cargo internal files and never install cleanup/cache tools without explicit approval.
- Every apply prints and flushes its complete byte-counted checked plan before deletion begins.
- Preserve candidate binaries/packages and evidence outside the disposable lane, then establish the
generation-bound marker with `build_storage.py mark-candidate-preserved`; an absent, stale, or
hash-mismatched marker blocks candidate deletion.
- Report reclaimed bytes plus expected cold-build impact.
@@ -0,0 +1,27 @@
# Build-storage policy
The tracked limits live in `.codex/workflow.toml`. Defaults are a 55 GiB soft total, 80 GiB hard total, at least 40 GiB or 15% free space, a 40 GiB persistent-lane ceiling, and a 35 GiB ceiling per disposable lane.
The canonical workspace path is hashed so `/home/.../Bevy` and `/mnt/Fedora/.../Bevy` share one cache identity. Managed lanes carry a sentinel with workspace path/hash, lane, toolchain, feature/profile signature, target/build directories, and timestamps.
Enforcement order:
1. Report total/per-lane size and largest children.
2. Under storage pressure, print the checked byte plan and prune expired marked disposable lanes.
3. Prune stale package intermediates after preserving published output.
4. Remove non-evidence Cargo timing/doc output.
5. Block a new heavy gate if the hard limit or free-space floor still fails.
6. Reset the persistent lane only at a safe slice boundary, after a dry run and verification-ledger update.
`enforce --phase pre|post` automatically prunes only when tracked policy enables it, storage pressure
exists, and a disposable lane has expired. Automatic and explicit prune/reset paths first print and
flush the complete byte-counted plan, including sentinel, path, process, and preservation checks,
before deleting any lane. A candidate lane additionally requires
`.codex/session/candidate-prune-safe.json`, created only after preserved evidence and at least one
distinct binary/package file have been hashed with `mark-candidate-preserved`; any later candidate
lane use makes that generation-bound marker stale.
Never prune an active lane, an unmarked directory, a symlink, another workspace, `/`, home, Cargo
home, the workspace root, `.git`, or a parent of any protected path. `cargo clean` is not a routine
operation; the one-time legacy-target migration is the sole exception documented by the workflow
installation record.
@@ -0,0 +1,21 @@
---
name: blacksite-doc-integrity
description: Prevent stale or contradictory Blacksite documentation from becoming design context by enforcing documentation authority, archiving superseded plans, comparing changed behavior with canonical docs and accepted ADRs, and running the documentation audit.
---
# Blacksite documentation integrity
Read `.codex/workflow.toml`, `docs/authority.toml`, and [the authority reference](references/documentation-authority.md) before treating repository prose as design guidance.
Trigger this Skill for user-visible behavior, schema/command/component renames, architectural changes, candidate preparation, documentation requests, or discovered contradictions.
1. Identify the changed public behavior from code and focused tests.
2. Load only the canonical docs for its topic and relevant accepted ADRs.
3. Read the exact Gitea acceptance criteria when tracked.
4. Search historical material only for contradictions, never as authority.
5. Write a bounded `.codex/session/doc-contradictions.md` listing claim, source, current truth, and action.
6. Update the smallest canonical owner at the stable slice boundary, within the same task.
7. Mark completed plans historical and freeze their substantive contents. Add required banners and replacement links.
8. Run `python scripts/codex/docs_audit.py --changed`, then the full audit at a documentation slice gate.
Keep README as an overview. Do not duplicate detailed contracts across guides, plans, ADRs, and tracker bodies. Coordinate a dry-run Gitea scope/status update when tracker truth has drifted.
@@ -0,0 +1,16 @@
# Documentation authority
`docs/authority.toml` is the machine-readable registry. Roles mean:
- `canonical`: current user or developer behavior.
- `architecture`: accepted decisions and constraints.
- `overview`: a high-level entry point linking to canonical owners.
- `active-plan`: approved incomplete work.
- `evidence`: dated acceptance or evaluation, not product specification.
- `historical`: preserved record no longer used as guidance.
- `superseded`: replaced material that links to its replacement.
- `draft`: non-authoritative work.
Code, schemas, tests, and deterministic output define actual behavior. Accepted ADRs define architecture. Gitea defines accepted current scope and work state. Canonical docs describe shipped/current workflows. When they conflict, identify and reconcile the conflict; never silently combine old and new claims.
Historical, evidence, and superseded files require a visible warning and current canonical link. Active plans require an incomplete-work banner and shipped-behavior link. Session state and raw logs are never documentation.
@@ -0,0 +1,14 @@
---
name: blacksite-editor-ux
description: Design and evaluate Blacksite editor UI/UX changes using a production editor interaction rubric, explicit state matrices, existing visual language, and native acceptance criteria. Use for Content Browser, Inspector, viewport, dialogs, material UI, and other interactive editor work.
---
# Blacksite editor UX
Read [the editor UX rubric](references/editor-ux-rubric.md). Before implementing meaningful UI behavior, record a compact interaction-state matrix in session state or the active plan.
Cover only relevant states, but explicitly consider empty, single/multi-selection, narrow/resized, invalid/broken, inherited/read-only/built-in, loading, confirmation, cancel/failure, undo/redo, and restart persistence.
Keep egui rendering thin and reuse established components, spacing, icons, cards, badges, drag/drop feedback, and editor language. Move reusable models and transactions to the lightest owning module/crate. Keep IDs, fingerprints, provenance, and implementation-owned data out of primary editing surfaces.
Create named native scenarios and hand them to `blacksite-native-qa`. Unit tests and screenshots alone are not acceptance; exercise the interaction. If the user says behavior still does not work properly, return to acceptance-in-progress and record a scope delta rather than treating it as unrelated by default.
@@ -0,0 +1,29 @@
# Blacksite editor UX rubric
## Product intent
- What familiar editor or file-manager interaction is being matched?
- What is the primary action and what must be obvious without documentation?
- What happens on invalid input?
## Interaction matrix
Include relevant rows for mouse click, double click, right click, shortcut, drag start/hover/drop, multi-selection, empty-space action, narrow panel, modal/review, cancel, undo/redo, and restart.
## Visual design
- Reuse current typography, spacing, icons, cards, and status badges.
- Provide visible hover, drop, focus, invalid, and disabled states.
- Avoid duplicated controls and competing presentations.
- Hide managed/internal data unless diagnosing a failure.
- Support resizing and narrow layouts.
- Distinguish inherited/default/read-only state from explicit editable state.
## Acceptance
- Focused logic tests in the lightest owning crate.
- Focused UI wiring tests when editor-owned state matters.
- Native interaction against the intended build/profile.
- Targeted screenshot or recording of the relevant state.
- Cancel/failure proof and saved-state restart proof when applicable.
- Canonical documentation update after the behavior stabilizes.
@@ -0,0 +1,20 @@
---
name: blacksite-gitea-sync
description: Read and synchronize exact Blacksite Gitea issues, epics, and milestones with current scope, implementation state, verification evidence, canonical documentation, and release-candidate status while avoiding duplicate issues and noisy updates.
---
# Blacksite Gitea synchronization
Read `.codex/workflow.toml` and [the state model](references/gitea-state-model.md). Use the configured Gitea connector; do not scrape or invent tracker state.
Supported modes are `read`, `plan`, `status`, `scope-delta`, `candidate`, and `close`.
1. Read exact known issue, parent epic, milestone, and recent relevant comments first. Search broadly only to locate an unknown item or prevent a duplicate.
2. Summarize acceptance locally and create a dry-run mutation plan before every write.
3. Follow configured permissions. Creation and scope/milestone changes require explicit authority; closure is candidate-only; delete/reopen is explicit.
4. Add at most one meaningful status comment per completed slice.
5. Distinguish working-tree implementation from engineering-complete, acceptance-in-progress, candidate-ready, and closure evidence.
6. Mark acceptance only when code, focused tests, and required native/package evidence exist and remain valid.
7. On failure, re-read the exact item, detect partial success, and retry only the missing operation.
Never push or close as a side effect. Record remote mutations and their readback in session state.
@@ -0,0 +1,14 @@
# Gitea state model
Gitea owns accepted scope, criteria, priority, dependencies, work state, candidate/evidence links, blockers, and milestone composition. It does not replace code, tests, ADRs, canonical docs, or native evidence.
States:
- `Implementing`: active local work.
- `Engineering-complete`: relevant engineering gates pass; native/product acceptance may remain.
- `Acceptance-in-progress`: native or stakeholder validation is active or exposed a gap.
- `Candidate-ready`: stable scope and a nominated tree are ready for remaining release gates.
- `Blocked`: an external condition prevents progress.
- `Closed`: candidate evidence and every criterion are accepted.
User-discovered UX gaps return an item to acceptance-in-progress and become scope deltas, not automatic new issues. Close children, final signoff, epic, then milestone. Never close a milestone with open assigned issues unless the user explicitly changes its definition.
@@ -0,0 +1,18 @@
---
name: blacksite-native-qa
description: Run deterministic named Blacksite editor or packaged-runtime scenarios on the actual desktop session, target the exact window, capture concise evidence, and restore test fixtures. Use only when visual or interactive acceptance is required.
---
# Blacksite native QA
Use only when the user requests native/visual QA or the active acceptance target explicitly requires it. Read `.codex/workflow.toml` and [the scenario format](references/scenario-format.md), then use `scripts/codex/native_qa.sh`.
- Build through `cargo_lane.py` in the named lane and resolve binary, intermediate `deps`, runtime environment, and PID from lane JSON. Never hard-code `target/debug/deps`.
- Target the exact PID/window/class/workspace. Bring offscreen dialogs on-screen and prefer accessibility or window-relative input over desktop coordinates.
- Capture only the target window or relevant crop under `.codex/evidence/`, with a hash and result record.
- Reuse one editor session while code is unchanged.
- Record fixture mutations and restore/trash them transactionally.
- Close processes spawned by the scenario.
- Keep full compositor/accessibility dumps out of the task unless they explain a failure.
Do not claim acceptance from a screenshot alone. Exercise the named steps, invalid/cancel path, and persistence where required.
@@ -0,0 +1,41 @@
# Named native scenario format
Scenario files use these top-level fields:
```yaml
name:
purpose:
preconditions:
build_lane:
fixture:
steps:
assertions:
evidence:
cleanup:
invalidates:
```
Keep steps deterministic and phrased as user actions. Assertions describe visible behavior, state transitions, persistence, and failure recovery. Evidence names the target window/crop and expected files. Cleanup must identify every spawned process and fixture mutation.
The runner exposes the scenario instead of pretending manual interactions are automated:
```bash
bash scripts/codex/native_qa.sh plan <scenario>
bash scripts/codex/native_qa.sh launch <scenario>
bash scripts/codex/native_qa.sh attach <scenario> <existing-editor-pid>
bash scripts/codex/native_qa.sh capture <scenario> <runner-pid>
bash scripts/codex/native_qa.sh record <scenario> <assertion-index> pass|fail [note]
bash scripts/codex/native_qa.sh status <scenario>
bash scripts/codex/native_qa.sh close <scenario> <runner-pid>
bash scripts/codex/native_qa.sh restore <scenario> --dry-run
bash scripts/codex/native_qa.sh restore <scenario> --apply
```
`launch` snapshots a workspace-contained regular-file fixture before the editor starts; `attach`
does the same while reusing an existing editor and never closes that user-owned process. `restore --apply`
prints and flushes the baseline/current hash plan, refuses to run while the recorded process
is alive, validates the snapshot hash, and restores atomically. A scenario is accepted only when all
named assertions are recorded as passing and the required evidence exists; visual interaction remains
user-controlled unless explicitly delegated.
Recurring scenario families include Content Browser item/empty-space menus, multi-selection, destination-first import, move/reference repair, duplicate/undo/derived cleanup, material-slot assignment/inheritance, DefaultGrid Forward/Solari, and package launch.
@@ -0,0 +1,20 @@
name: content-browser-card-layout
purpose: Verify production-quality grid/list card layout and model-thumbnail identity at wide and narrow browser sizes.
preconditions: The running editor has the project Content Browser available with long asset names and the Poly Haven desk imported.
build_lane: dev
fixture:
steps:
- Open the Content Browser grid and navigate to the Office model folder.
- Inspect long Material, Texture, and model names with clean and dirty status states.
- Resize the Content Browser and Details splitter through narrow and wide layouts.
- Switch to list view and compare status markers and column alignment.
- Inspect the Poly Haven metal office desk card and one mesh-subasset preview.
assertions:
- Grid labels stay inside clipped two-line footers with ellipsis and no status overlap.
- Dirty, processing, and error state use the fixed top-right status rail rather than text over the label.
- List status markers occupy fixed space and do not shift or truncate neighboring columns unpredictably.
- Toolbar, Details splitter, and cards remain usable without clipped controls at narrow sizes.
- The office desk and mesh-subasset thumbnails show rendered geometry, never an albedo texture substitute.
evidence: Target-window captures for grid-wide, grid-narrow, list, and desk geometry states plus hashes.
cleanup: Close only a runner-spawned editor; this scenario does not mutate project fixtures.
invalidates: Asset-card, Content Browser layout, status model, or thumbnail-routing changes.
@@ -0,0 +1,26 @@
name: material-slot-live-edit
purpose: Verify persistent live Material edits, explicit save separation, and the unified responsive slot widget.
preconditions: editor_scene contains a primitive and static mesh using a project Material; no editor process is running.
build_lane: dev
fixture: assets/materials/pebble_bricks.ron
steps:
- Select the primitive using pebble_bricks and expand its material parameters.
- Drag a scalar control, release it, and observe the surface for at least five seconds.
- Switch selection away and back, then compare the scalar value and rendered surface.
- Narrow and widen the Inspector around the responsive threshold.
- Save the active Material document and observe status and processing indicators.
- Select a static mesh material slot and compare its slot presentation.
- Leave the expanded material card idle for five minutes while sampling the editor process GPU memory and terminal diagnostics.
- Close and relaunch the editor, then reopen the same Material slot.
assertions:
- The surface changes continuously, does not flicker back after release, and the editor remains responsive.
- Selection changes preserve the live value and the compact amber dirty indicator without label overlap.
- Scalar save becomes clean without a PROCESSING state or a long-running UI operation.
- Primitive and static-mesh slots use the same compact header and schema-driven parameter layout.
- Narrow and wide layouts contain every control without overlap, clipping, garbled rows, or redundant diagnostics prose.
- No Apply, Revert, Ctrl+S hint, inline Explicit label, or inline Source & Diagnostics section appears.
- GPU memory remains bounded, no repeated egui multipass ID warning appears, and the editor stays alive without a renderer Out of Memory error.
- Relaunch preserves the saved Material value and rendered result.
evidence: Target-window captures for dirty-wide, dirty-narrow, saved, and relaunched states plus hashes.
cleanup: Close the spawned editor and atomically restore pebble_bricks.ron from the runner snapshot.
invalidates: Material UI, material persistence, or slot-resolution code changes.
@@ -0,0 +1,27 @@
name: penpot-material-inspector
purpose: Verify the final Penpot Materials list and material-slot panel at its 640 px and 420 px Inspector reference widths.
preconditions: editor_scene contains primitive, static-mesh, and skinned-mesh material users; no editor process is running.
build_lane: dev
fixture: assets/materials/pebble_bricks.ron
steps:
- Launch the editor on the real desktop and size the Inspector to the 640 px reference width.
- Select a primitive, static mesh, and skinned mesh in turn and expand each material panel.
- Compare Materials ownership, expanded slot header, PARAMETERS spine, Surface, six Inputs rows, UV, and Advanced geometry with the current Penpot reference.
- Narrow the Inspector to the 420 px floor and verify every value, channel, texture, Locate, and Clear control reflows.
- Open the material picker, dismiss it without selection, then assign a valid project Material and inspect inherited and direct states.
- Drop a Texture onto the material assignment target and inspect the invalid state without assigning it.
- Open Base Color and exercise Wheel, Sliders, Presets, Apply, Cancel, Escape, and outside dismissal.
- Edit a scalar and color, release the controls, switch actors, then save and relaunch the editor.
- Inspect imported-source, DefaultGrid, and broken-reference presentations through the available fixture states.
assertions:
- The 640 px Inspector matches the current Penpot palette, Source Sans Pro typography, 32 px Materials heading, 82 px expanded slot header, 592 px parameter sections, six 30 px input rows, spacing, borders, and fixed property geometry without visible drift.
- Primitive, static-mesh, and skinned-mesh slots use the same panel geometry and have no redundant second slot presentation.
- At the 420 px Inspector floor, six 56 px input rows put paired texture controls on the second line with no horizontal scrolling, clipping, compressed labels, or missing actions.
- Direct assignments have no Explicit badge; inherited, dirty, processing, failed, read-only, imported-source, and built-in states retain one header geometry.
- Picker dismissal and invalid Texture drops make no assignment or source save; valid Material or Instance drops use the blue accent state.
- Wheel, Sliders, and Presets preview live; Apply retains the dirty in-memory value and Cancel, Escape, or outside dismissal restores the exact pre-open value.
- Material controls perform no pointer-release write or scalar/color processing job and keep the existing live GPU handle visible across actor selection.
- Save and relaunch preserve the authored value, while broken explicit references retain failed identity and visible DefaultGrid fallback.
evidence: Target-window captures for 640 px primitive/static/skinned, narrow reflow, color modes, invalid drop, dirty state, and relaunch plus hashes.
cleanup: Close the spawned editor and atomically restore pebble_bricks.ron from the runner snapshot.
invalidates: Design tokens, fonts, material panel geometry, material picker, color picker, authored documents, or material resolver changes.
@@ -0,0 +1,17 @@
---
name: blacksite-release-candidate
description: Nominate and verify one Blacksite candidate tree or commit, reuse still-valid selective verification evidence, run the remaining full release gates once, produce an evidence manifest, and hand results to Gitea synchronization.
---
# Blacksite release candidate
Read `.codex/workflow.toml` and [the release gates](references/release-gates.md). Require stable scope, no pending major delta, and `Candidate-ready` session state.
1. Record the candidate SHA or dirty-tree digest.
2. Read the verification ledger and reuse every gate whose relevant input digest and lane signature remain valid.
3. Run only missing/invalid release gates via `verify.py candidate` and managed candidate/package lanes.
4. Preserve final binaries/package output and required native evidence before disposable-lane pruning.
5. Write `.codex/session/candidate-evidence.json` with commands, digests, results, artifacts, screenshots, and documentation status.
6. Run documentation integrity and hand a dry-run/authorized candidate update to `blacksite-gitea-sync`.
Do not push, close, or change tracker scope outside direct or configured authority. Run full workspace/all-feature tests and strict lint only once per candidate code digest.
@@ -0,0 +1,14 @@
# Candidate release gates
A nominated Blacksite candidate requires, when relevant:
- Full workspace/all-feature tests.
- Strict all-target/all-feature Clippy with warnings denied.
- Deterministic content processing and read-only check parity.
- Level/sample/project validators and migration idempotence.
- Packaging, packaged artifact validation, and launch.
- Named native editor/runtime scenarios against candidate binaries.
- Documentation authority/contradiction audit.
- Clean candidate-tree or nominated dirty-tree digest evidence.
Do not precede workspace tests with a redundant workspace check unless a target is otherwise uncovered. Documentation-only changes do not invalidate code gates when recorded inputs are unchanged. Closure additionally requires every issue criterion, epic checklist synchronization, and configured Gitea evidence.
@@ -0,0 +1,18 @@
---
name: blacksite-selective-verify
description: Select and run the smallest valid Blacksite formatting, compile, test, lint, processing, validation, packaging, and native gates based on changed files and the current task state. Use after edits or before slice/candidate completion; do not default to full workspace gates.
---
# Blacksite selective verification
Read `.codex/workflow.toml` and [the verification matrix](references/verification-matrix.md), then invoke `python scripts/codex/verify.py`.
- `plan` explains selected and skipped gates without executing them.
- `fast` runs the smallest useful edit loop.
- `slice` adds affected-package tests, strict Clippy, domain checks, docs integrity, and named native requirements.
- `candidate` is permitted only for a nominated Candidate-ready state and runs missing release gates once.
- `status` reads the digest ledger; `invalidate --reason ...` invalidates only when inputs or acceptance change.
Every Cargo command must go through `cargo_lane.py`. Do not run overlapping Cargo processes. Reuse a PASS when its relevant input digest, command, lane signature, toolchain, features, and environment are unchanged. Store complete output under `.codex/logs/` and show only the compact result or the first bounded actionable failure.
Do not append workspace tests, workspace Clippy, processing, validators, packaging, or native QA to an ordinary fast loop. Prefer focused tests in the lightest crate that owns the invariant.
@@ -0,0 +1,19 @@
# Blacksite verification matrix
| Changed area | Fast loop | Slice gate | Candidate impact |
|---|---|---|---|
| Markdown only | docs audit | docs audit | Rust gates remain valid |
| `AGENTS.md`, Skills, workflow scripts | script self-tests/dry run | docs audit and workflow acceptance | No Rust gate unless Rust changed |
| `crates/content_pipeline/**` | pipeline check and focused tests | pipeline tests and strict Clippy; processing if output changed | Full gate later |
| `crates/shared/**` schemas/types | shared check and focused tests | shared tests, dependent checks, migration dry run if needed | Full gate later |
| `crates/editor/src/ui/**` | editor library check; focused wiring tests | editor tests/Clippy and named native scenario | Full gate later |
| `crates/blacksite_surface/**`, shaders | surface check/tests | surface Clippy and relevant renderer scenarios | Full gate later |
| `xtask/**` packaging | focused xtask/package test | repeat package test and package dry run | Package candidate required |
| Registry/catalog inputs | processing check | validators and deterministic write/check | Package/native as relevant |
| Migration/schema versions | focused migration tests/dry run | fixture apply, idempotence, rollback | Full gate later |
| Gitea only | No Cargo | Tracker readback | No code gate |
| Session/evidence only | No Cargo | Evidence integrity | No code gate |
Fast checks normally use the `dev` lane. Candidate, package, hot-reload, and full-debug work use their named disposable lanes. A docs-only edit never invalidates a code gate whose recorded input digest is unchanged.
Rust gate digests fingerprint the owning package and its local dependency closure, relevant Cargo and workflow configuration, the exact gate/lane, tool versions, and build-affecting environment. Documentation and unrelated packages are excluded, so their edits preserve valid focused Rust evidence; changes to a dependency, relevant configuration, toolchain, or environment invalidate it.
@@ -0,0 +1,19 @@
---
name: blacksite-task-state
description: Maintain resumable Blacksite task state, scope deltas, verification validity, and exact next actions during multi-step implementation, user steering, reconnects, or context compaction. Use for long or multi-subsystem work; do not use for trivial one-file edits.
---
# Blacksite task state
Read `.codex/workflow.toml`, then use `python scripts/codex/state.py` to create or update the ignored `.codex/session/STATE.md`.
Use this Skill for `continue`, `resume`, plan implementation, multi-crate work, material scope changes, native acceptance discoveries, reconnects, and path remapping.
1. Verify the canonical repository path, branch, HEAD, dirty summary, and relevant live processes.
2. Resume an existing valid state instead of rediscovering the repository.
3. Keep the active goal, slice, acceptance target, non-goals, intentional files, decisions, evidence validity, and one exact next action current.
4. Record steering with `state.py scope-delta`. Classify it as an active-slice refinement, newly discovered blocker, added acceptance criterion, or separate follow-up.
5. State which evidence remains valid and invalidate only affected gates with `verify.py invalidate`.
6. Update state after a completed slice, native checkpoint, or remote mutation.
Keep the file below the configured line limit. Never copy logs, issue bodies, large plans, or desktop dumps into it.