From 673097f6592d92a2106400754f6ccc5da680a4f7 Mon Sep 17 00:00:00 2001 From: fy59 Date: Fri, 28 Aug 2026 06:58:34 +0200 Subject: [PATCH] docs: strengthen agent engineering contract --- AGENTS.md | 705 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 616 insertions(+), 89 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 50d40bd..73619d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,149 +4,614 @@ - The root `README.md` is the index of project documentation. - Canonical documents under `docs/**` define scientific contracts, architecture, - FROZEN invariants, and roadmap ordering. -- Before changing an architectural or scientific area, identify and read the - relevant canonical document and its applicable invariants. + FROZEN invariants, persistence semantics, lifecycle state, and roadmap + ordering. +- Before changing an architectural, scientific, persistence, runtime, or + resource-sensitive area, identify and read the relevant canonical document + and its applicable invariants. - FROZEN documentation and contracts must never be changed silently to fit an - implementation. A lower-level convenience never overrides a higher-level + implementation. +- A lower-level implementation convenience never overrides a higher-level canonical contract. -- If requested work, code, and a FROZEN contract genuinely conflict: stop the - affected change, report the contradiction, and require an explicit human - decision. Do not choose a new policy implicitly. +- Lifecycle markers such as `PLANNED`, `IMPLEMENTED`, + `VALIDATION PENDING`, and `PASS/FROZEN` describe repository state and must + match actual implementation and validation evidence. +- If requested work, current code, and a FROZEN contract genuinely conflict: + stop the affected change, report the contradiction, and require an explicit + human decision. Do not choose a new policy implicitly. +- Do not manufacture a human decision from an ordinary implementation defect. + Resolve locally determinable engineering problems from the existing code and + canonical documentation. ## 2. FROZEN integrity -The following historical foundation is protected and may change only through -an explicitly authorized, explicitly scoped human ticket: +The following current project foundation is protected and may change only +through an explicitly authorized, explicitly scoped human ticket: - Gates A–G — PASS/FROZEN - Track Model — PASS/FROZEN -- Builder — PASS/FROZEN +- Track Builder — PASS/FROZEN - F0 — PASS/FROZEN - Phase H v1 — PASS/FROZEN - MVS-M1 — PASS/FROZEN -- Project DB v18 +- Project DB v20 — PASS/FROZEN +- S1 Capture / Asset Provenance — PASS/FROZEN +- S2 Capture-safe Standard Ingestion — PASS/FROZEN +- S3 Capture / Acquisition Ingestion — PASS/FROZEN +- Durable Acquisition-Campaign Execution — PASS/FROZEN -When a ticket declares `NO_NEW_SUBSYSTEM`, do not introduce Task Runtime, -Queue, Governor, scheduler, pools, persistence, viewer, mesh, texturing, -scratch/SSD, or another deferred subsystem. This file states invariants and -working rules; it does not duplicate a roadmap snapshot or claim that a -deferred subsystem can never exist. +Detailed subcontracts remain defined by their canonical documents. This file +does not duplicate every S3 substage, scientific threshold, migration detail, +or persistence format. + +Historical references to older Project DB versions remain valid when they +describe the actual historical contract or migration path. Do not rewrite +legitimate v16/v17/v18/v19 history merely because v20 is current. + +When a ticket declares `NO_NEW_SUBSYSTEM`, do not introduce an unrelated: + +- Task Runtime; +- Queue; +- Scheduler; +- Resource Governor; +- worker pool; +- persistence subsystem; +- viewer; +- mesh/texturing subsystem; +- scratch/SSD manager; +- generic backend framework; +- message bus; +- daemon. + +This restriction is ticket-scoped. It does not mean that a subsystem already +present in the canonical architecture can never be used by later authorized +work. + +Never reopen a FROZEN scientific or architectural decision merely to simplify +an implementation. ## 3. Scope and Git discipline -- Inspect `git status` before editing. +- Inspect `git status --short` before editing. - Preserve unrelated user and worktree changes. -- Modify only files explicitly authorized by the ticket. +- Modify only files authorized by the current ticket. - Never modify or add anything under `scan3d/`, especially - `scan3d/tri_photos.py`. + `scan3d/tri_photos.py`, unless a future human ticket explicitly removes that + protection. - Never use `git add -A` against the real repository index. -- Without explicit human authorization, never commit, push, reset, restore, - checkout files, stash, clean, or perform another destructive Git operation. +- Without explicit human authorization, never: + - stage; + - commit; + - push; + - reset; + - restore; + - checkout files or another branch; + - stash; + - clean; + - rebase; + - merge; + - amend; + - force any Git operation. - Never discard unrelated modifications. - At delivery, list the exact files modified by the ticket. For review of untracked files, a temporary `GIT_INDEX_FILE` may be used when -necessary. Add paths explicitly; do not use `git add -A`; keep the real index -untouched; remove the temporary index afterward. Do not use this machinery when -a normal diff is sufficient. +necessary. Add paths explicitly, keep the real index untouched, and remove the +temporary index afterward. + +Do not use temporary-index machinery when a normal diff or `--no-index` check +is sufficient. + +A dirty worktree may be legitimate during an implementation tranche. Do not +require a clean worktree unless the ticket explicitly requires one. ## 4. Language / API / ABI rules - Public C APIs must remain valid C17. -- C++ must remain within the standard configured by Meson; the repository is - intentionally mixed-language and must not be treated as C-only. -- Preserve public API and ABI unless the ticket explicitly authorizes change. +- C++ must remain within the standard configured by Meson. +- The repository is intentionally mixed-language and must not be treated as + C-only. +- Preserve public API and ABI unless the ticket explicitly authorizes a change. - No C++ exception may cross an `extern "C"` or other public C ABI boundary. - Keep ownership and lifetime rules explicit. -- Do not introduce undefined behavior, unchecked narrowing, or unchecked - integer overflow. +- Do not introduce undefined behavior. +- Reject unchecked narrowing where the destination cannot represent the full + accepted input domain. +- Reject unchecked integer overflow. - Reject silent path truncation. -- Deterministic serialization must use explicit fixed widths and byte order; - never depend on native struct padding or native endianness. +- Deterministic serialization must use explicit fixed widths and byte order. +- Never serialize native structs or depend on native struct padding or native + endianness. +- Do not expose C++ standard-library types through public C17 headers. +- Public buffers and fixed-capacity strings must have explicit bounds and + termination semantics. +- If a public function may be retried, its idempotency or conflict behavior + must be explicit where non-obvious. -## 5. Architecture and resources +Compiler success alone is not proof of API, ABI, persistence, or scientific +contract correctness. + +## 5. Identity discipline + +Identity boundaries are architectural contracts. + +Never silently equate: + +- Capture and file; +- Capture and asset; +- Capture and `image_id`; +- Capture and SHA-256; +- Capture and path; +- Capture and filename/basename; +- Capture and Task ID; +- Capture and campaign group ID; +- Task ID and scientific acquisition identity; +- campaign group ID and scientific Capture identity. + +Operational identifiers may legitimately reference scientific objects, but +they do not redefine their identity. + +In particular: + +- SHA-256 identifies immutable asset bytes. +- `capture_id` identifies a physical acquisition representation in Project DB. +- `image_id` identifies a scientific image representation. +- Task ID identifies durable execution work. +- campaign group ID identifies a stable operational group within a campaign + request. + +Never recover a Capture by guessing from path, SHA, basename, timestamp, +metadata, asset, image, Task ID, or group ID unless a future FROZEN contract +explicitly defines such an identity. + +## 6. Architecture and resources - Keep TUI/ncurses ownership separate from business logic and layout according to canonical architecture. - Keep ncurses on its designated/main thread wherever the canonical contract requires it. - Extend validated abstractions rather than rewriting validated modules. +- Reuse the existing Task / Queue / Scheduler / Resource Governor ownership + model rather than creating parallel runtime infrastructure. - System stability and responsiveness take priority over throughput. -- Bound memory, buffers, files, descriptors, processes, threads, and captured - output reasonably for the operation. +- Bound memory, buffers, files, descriptors, processes, threads, captured + output, parser work, temporary storage, and staging reasonably for the + operation. - Memory shared with an iGPU counts against host RAM. - zram and swap are pressure/safety mechanisms, not normal working-memory budgets. -- Do not invent a global resource subsystem inside a ticket that defers it. -- Contractually atomic outputs must remain atomic; failure paths must clean all - resources owned by the current operation without deleting unrelated data. +- An operational hardware/resource bound must not accidentally become a + scientific dataset-size limit. +- Do not invent a new global resource subsystem inside a ticket that defers it. +- Contractually atomic outputs must remain atomic. +- Failure paths must clean all resources owned by the current operation without + deleting unrelated or shared data. +- Shared immutable assets must never be deleted merely because one operation + fails. -## 6. Code quality and readability +Resource-sensitive work must identify, where relevant: -- Clang and Meson are the reference build tools. -- Do not add global mutable state unless an established historical contract - explicitly permits it. -- Clean allocations, file descriptors, processes, mutexes, conditions, and - threads explicitly. +- resource owner; +- admission point; +- bound or budget; +- reservation lifetime; +- release point; +- failure cleanup; +- cancellation cleanup; +- whether the bound is operational or scientific. + +External USB SSD scratch/swap support remains a planned resource-management +capability. Do not implement ad-hoc mounting, formatting, `swapon`, scratch +ownership, or device cleanup outside an explicitly authorized ticket. + +## 7. Code quality and readability + +- Clang and Meson are the reference build tools unless a ticket explicitly + requires another supported compiler for validation. +- Do not add global mutable state unless an established contract explicitly + permits it. +- Clean allocations, file descriptors, process handles, mutexes, conditions, + reservations, and threads explicitly. - Do not use `system()` or `popen()` in production where direct process execution is required. -- Do not leave TODOs, dead code, or accidental dependencies in a completed - ticket. +- Do not leave accidental TODOs, dead code, debug paths, or dependencies in a + completed ticket. - Prefer minimal evolution to rewrites. - Target approximately 100 columns; normally do not exceed 120 without local justification. -- Do not use code golf or compress multiple logical operations onto a line. -- Split complex code when that materially improves auditability. +- Do not use code golf. +- Do not compress several logical operations onto one line merely to reduce + line count. +- Split complex code when doing so materially improves auditability. - Temporary probes, benchmarks, diagnostics, C/C++/GLSL files, and scripts - under `/tmp` must also be readable and auditable. -- Comments should explain non-obvious invariants, not paraphrase code. + under `/tmp` must also remain readable and auditable. - Formatting-only changes must not alter behavior. +- Do not run a whole-repository formatting sweep inside an unrelated ticket. +- Do not reorder includes, rename symbols, or normalize whitespace without a + technical reason in scope. -## 7. External processes and filesystem +Required source comments and canonical documentation are part of the +implementation, not optional cleanup work. + +## 8. Source Comment Contract — MANDATORY + +All new or materially modified production code MUST include the comments +required to make its non-obvious contracts understandable from the source. + +This requirement is part of the Definition of Done. + +Comments MUST document the relevant WHY / CONTRACT / INVARIANT when code +introduces or materially modifies any of the following: + +- public C17 API semantics; +- ownership or lifetime; +- persistence or transaction boundaries; +- serialization formats; +- deterministic or scientific behavior; +- coordinate or pose conventions; +- identity semantics; +- idempotency or retry behavior; +- Task / Queue / Scheduler / Resource Governor ownership; +- resource admission, reservation, and release; +- RAM / CPU / GPU / I/O / temporary-storage bounds; +- concurrency or synchronization; +- C/C++ ABI and exception-containment boundaries; +- malformed-input or corruption handling; +- non-obvious algorithmic assumptions; +- crash/restart ordering; +- FROZEN scientific or architectural invariants. + +Comments MUST explain WHY a rule exists or WHAT CONTRACT must remain true. + +Do NOT add comments that merely narrate obvious code. + +Bad: + +```c +// Increment index. +index++; +``` + +Good: + +```c +// Advance progress only after the group_id -> capture_id mapping is durable. +// Recovery must never observe a completed group without a retained Capture ID. +``` + +Another good example: + +```c +// SHA-256 identifies immutable asset bytes only. It must never be used as +// physical Capture identity. +``` + +### Public APIs + +New or materially modified public declarations under `include/lardon3d/` MUST +document the relevant subset of: + +- purpose; +- valid inputs; +- nullable arguments; +- output semantics; +- ownership; +- lifetime; +- bounded capacities; +- deterministic behavior; +- idempotency; +- error/result semantics; +- runtime or thread assumptions; +- persistence implications where relevant. + +Public comments must remain valid C17 documentation and must not expose C++ +implementation details unnecessarily. + +Use the repository's existing documentation-comment style consistently. Do not +introduce verbose Doxygen ceremony where the repository does not need it. + +### Persistence and serialization + +Every new or materially modified persistent format MUST have a concise format +contract documenting the relevant subset of: + +- magic; +- serialization version; +- byte order; +- fixed-width field semantics; +- string representation; +- count bounds; +- maximum encoded size; +- malformed/truncated rejection; +- compatibility/migration behavior; +- checksums/fingerprints where applicable. + +Never serialize native structs or rely on native padding or endianness unless +an existing FROZEN contract explicitly requires it. + +Document a format contract once at the correct abstraction boundary. Do not +comment every individual `encode_u32()` or equivalent call. + +### Scientific code + +Scientific comments MUST preserve the distinction between: + +- scientific identity; +- operational identity; +- resource policy; +- implementation detail. + +Where relevant, comments should make explicit non-obvious conventions such as: + +- coordinate frame direction; +- camera/world pose convention; +- reprojection units; +- calibration assumptions; +- deterministic RNG behavior; +- cheirality/parallax constraints; +- gauge handling; +- threshold provenance; +- strong vs weak evidence; +- `CALLER_EXPLICIT` vs scientifically `STRONG`. + +Do not silently strengthen or weaken a FROZEN scientific rule through a +comment. + +### RAW / JPEG / MPF + +Where relevant, comments must preserve the established distinction between: + +- immutable SOURCE RAW; +- deterministic DERIVED representation; +- RAW Policy v1; +- L3DRAWD1 identity; +- metadata-only acquisition processing; +- structural JPEG validation; +- JPEG marker payload boundaries; +- entropy/stuffing/restart behavior; +- structural outer EOI; +- primary MPF APP2 evidence; +- bounded secondary JPEG validation; +- zero-only permitted MPF gaps/trailer. + +Do not imply that metadata validation performs pixel decoding when it does not. + +### Task / Queue / Scheduler / Governor + +Where non-obvious, comments must make runtime ownership explicit. + +In particular: + +- Task owns execution state. +- Queue owns bounded dispatch/backpressure. +- Scheduler responsibilities are represented by the established runtime/Queue + architecture; do not invent a second scheduler. +- Resource Governor owns admission and hardware-resource budgets. +- Resource Reservation belongs to the currently admitted bounded execution. +- `sequence_break` is an execution boundary that releases/re-establishes + admission according to runtime semantics. + +Do not imply that a long campaign reserves resources for its entire lifetime +when execution is group-bounded. + +### Resource-sensitive code + +Any new or materially modified resource-sensitive path MUST make the relevant +resource ownership understandable from source. + +Where applicable document: + +- RAM ownership/bound; +- CPU admission; +- GPU admission; +- I/O ownership; +- process/thread count; +- file-descriptor lifetime; +- temporary/scratch storage ownership; +- reservation lifetime; +- release point; +- failure cleanup; +- cancellation cleanup. + +An operational hardware/resource bound MUST NOT accidentally become a +scientific dataset-size limit. + +### Crash / restart / idempotency + +Where restart ordering matters, document the durable invariant. + +For durable campaign execution, the current ordering is conceptually: + +```text +S3-E returns capture_id + ↓ +group_id -> capture_id mapping + durable cursor commit + ↓ +generic Task progress/checkpoint advances + ↓ +next group may execute +``` + +Do not document a guarantee stronger than production provides. + +The residual pre-return S3-E crash window remains intentional and documented: +if S3-E creates a Capture internally and the process dies before S3-E returns +the `capture_id`, campaign execution must not guess that Capture identity. + +### C / C++ ABI boundaries + +Where C++ implements a public C interface or C Task callback, comments should +make exception containment understandable when non-obvious. + +No C++ exception may escape a C ABI boundary. + +Do not duplicate the same statement above every trivial wrapper when one local +contract comment clearly governs a set of wrappers. + +### Tests + +Tests should comment only non-obvious fixtures or failure scenarios. + +Comments should state WHAT CONTRACT the fixture proves, for example: + +- intentional malformed input; +- crash window; +- rollback injection; +- ambiguity; +- scientific identity conflict; +- cross-ScanSet rejection; +- resource-pressure/admission condition. + +Do not narrate ordinary test mechanics. + +### Documentation synchronization + +Source comments do NOT replace canonical architecture documentation. + +Canonical FROZEN documentation remains authoritative. + +If code, source comments, and canonical documentation disagree: + +1. do not silently change a FROZEN contract; +2. identify the contradiction; +3. correct stale comments/documentation only when actual behavior and authority + are already established; +4. report an implementation defect if code violates the canonical contract. + +### Mandatory implementation workflow + +For every future implementation tranche: + +1. implement the bounded production change; +2. add/update targeted tests; +3. add/update required source comments in the SAME tranche; +4. update canonical documentation when behavior/contracts changed; +5. validate every modified public C17 header; +6. validate relevant C++ syntax/build integration; +7. validate resource ownership and bounds; +8. run applicable build/tests/sanitizers; +9. perform the required review; +10. only then claim completion. + +The normalized future implementation standard is: + +```text +CODE ++ TESTS ++ REQUIRED SOURCE COMMENTS ++ CANONICAL DOCUMENTATION ++ C17/C++ SYNTAX ++ RESOURCE OWNERSHIP ++ VALIDATION ++ REVIEW +``` + +A tranche is NOT complete merely because code compiles and tests pass when +required contract/invariant comments or canonical documentation are missing. + +There should be no future project-wide comment-cleanup pass for newly written +code: comment debt must be handled when the code is introduced. + +## 9. External processes and filesystem - Prefer direct process execution over shell command strings. - Explicitly own, monitor, and reap child processes. - Use process groups when required and prevent orphaned children. -- Bound retained stdout/stderr where applicable and drain output when required - to avoid deadlocks. -- Clean owned resources on every success and failure path. -- Do not assume a CLI flag exists without evidence. +- Bound retained stdout/stderr where applicable. +- Drain child output when required to prevent pipe deadlocks. +- Clean operation-owned resources on every success and failure path. +- Do not assume an external CLI flag exists without evidence. - Authoritative upstream documentation or source may be inspected for external dependencies. - Temporary probes, clones, and builds under `/tmp` are allowed when useful. -- Do not use `sudo`, modify the host persistently, install system packages - without explicit authorization, or add a permanent repository dependency - without explicit authorization. +- Reuse valid temporary upstream evidence instead of repeatedly downloading or + rebuilding the same dependency. +- Do not use `sudo`. +- Do not modify the host persistently. +- Do not install system packages without explicit authorization. +- Do not add a permanent repository dependency without explicit authorization. +- A missing local executable alone is not proof that a required capability is + unavailable. -## 8. Documentation discipline +## 10. Persistence and transaction discipline + +Persistence changes require explicit attention to: + +- atomic creation; +- rollback; +- idempotency; +- retry convergence; +- migration ordering; +- durable publication; +- cross-object consistency; +- restart state; +- corruption/malformed-input handling. + +For Project DB: + +- preserve current v20 semantics unless a ticket explicitly authorizes a schema + change; +- schema-version changes require explicit human authorization; +- migrations must be additive unless a different migration is explicitly + authorized; +- existing projects must remain recoverable; +- do not silently reinterpret historical rows; +- typed Task business payload must not be confused with generic Task runtime + state; +- transaction boundaries must preserve the documented crash/restart invariant. + +Where a strict API returns a constraint and bounded exact reconciliation is +part of a FROZEN higher-level operation, do not weaken the strict API merely to +make retries convenient. + +## 11. Documentation discipline - Do not create duplicate canonical documents for one contract. - Link every new canonical document under `docs/**` from the root `README.md`. - For changes to API, architecture, ownership, concurrency, persistence, - pipeline, or limits, check whether canonical documentation must be updated. + pipeline, resources, limits, or scientific semantics, check whether + canonical documentation must be updated. - Documentation must describe proven implementation, not desired future behavior. -- Statuses such as PLANNED, IMPLEMENTED, VALIDATION PENDING, and PASS/FROZEN - are authoritative lifecycle statements: update them only when the required - implementation, validation, and review evidence supports the state. -- Never mark work PASS/FROZEN without the required validation and review. +- Roadmap documents may describe future behavior, but future capabilities must + be clearly marked as planned/later/exploratory. +- Never describe future viewer, Capture Guidance, video/keyframe, SSD scratch, + or camera-control capabilities as implemented before they are actually + validated. +- Statuses such as `PLANNED`, `IMPLEMENTED`, `VALIDATION PENDING`, and + `PASS/FROZEN` are authoritative lifecycle statements. +- Update lifecycle state only when implementation, validation, and review + evidence support the transition. +- Never mark work `PASS/FROZEN` without the required validation and review. +- Preserve legitimate historical DB/version references where they describe + frozen history. -## 9. Required validation +## 12. Required validation For ordinary implementation tickets, before claiming completion, actually run -the applicable commands: +the applicable commands. + +Normal build: ```sh +meson setup --reconfigure build meson compile -C build -j8 +``` + +Normal tests: + +```sh meson test -C build --num-processes 1 --print-errorlogs +``` + +Diff validation: + +```sh git diff --check ``` -If build configuration must be regenerated, follow the documented Clang/Meson -setup and do not blindly wipe a valid build tree. - -For a new or modified public C header, also run a C17 syntax check, for example: +For every new or modified public C header, also run a C17 syntax check, for +example: ```sh cc -x c -std=c17 -fsyntax-only -Iinclude \ @@ -154,37 +619,99 @@ cc -x c -std=c17 -fsyntax-only -Iinclude \ ``` For memory/lifetime-sensitive changes, use a separate ASan/UBSan build and do -not overwrite the normal build. For relevant concurrency changes, run TSan -when supported. If a sanitizer is unavailable or invalid because of the -environment/toolchain, report that explicitly rather than claiming PASS. +not overwrite the normal build. -Run expensive or stress validation only when relevant, one heavy validation at -a time. Investigate a timeout; do not rerun it until it happens to pass. -Distinguish third-party sanitizer noise from repository defects using concrete -stack and failure evidence. Never claim a command, test, sanitizer, or review -that was not actually performed. +For relevant concurrency changes, run TSan when supported and meaningful. -## 10. Delivery report / STOP conditions +If a sanitizer is unavailable or invalid because of the environment/toolchain, +report that explicitly rather than claiming PASS. + +Run expensive/stress validation only when relevant. + +Run heavy validation serially when required to preserve machine stability. + +Investigate a timeout or sanitizer failure. Do not repeatedly rerun a failing +test until it happens to pass. + +Distinguish third-party sanitizer/environment noise from repository defects +using concrete stack/failure evidence. + +Never claim a command, test, sanitizer, review, or real-data validation that +was not actually performed. + +For documentation/comment-only changes, do not invent unnecessary sanitizer +work, but still run enough build/syntax/diff validation to prove that the +non-functional boundary was preserved. + +## 13. Review discipline + +A normal review should verify the bounded current delta and direct regressions. + +Do not turn every review into a redesign of the repository. + +Review findings must distinguish: + +- blocking defect; +- non-blocking issue; +- future scope; +- unrelated pre-existing observation. + +A reviewer request does not automatically define new policy. + +Compare findings against: + +1. canonical FROZEN documentation; +2. explicit human decisions; +3. established tranche semantics; +4. documented future-scope boundaries. + +Do not invoke an expensive implementation agent merely to satisfy speculative +hardening that is outside the current contract. + +Comments and documentation are reviewable implementation artifacts. A +misleading contract comment is a defect even if compiled behavior is unchanged. + +## 14. Delivery report / STOP conditions Every completed ticket report must include: +- baseline branch/HEAD where relevant; - exact files modified; - concise implementation description; +- source-comment/documentation changes where required; - validations actually executed and exact results; -- tests or checks not executed; +- tests/checks not executed; - known blockers; - non-blocking findings; - deliberately deferred/future-scope items; -- confirmation that unrelated and FROZEN areas were preserved. +- resource impact where relevant; +- confirmation that unrelated and FROZEN areas were preserved; +- Git state; +- confirmation that `scan3d/` remained untouched when protected. -STOP and request a human decision if: +STOP and request a human decision only when resolution requires: -- requested work contradicts a FROZEN contract; -- satisfying it requires files outside the authorized scope; -- a scientific contract or identity must change without authorization; -- a new subsystem or dependency is required contrary to scope; -- destructive Git action is required; -- incompatible policies remain unsettled by canonical documentation. +- changing a FROZEN contract; +- changing Project DB schema/version without prior authorization; +- introducing a genuinely new subsystem outside authorized scope; +- files outside the authorized scope; +- destructive Git action; +- `sudo`/root/system-wide installation; +- credentials/secrets; +- a materially different scientific policy not determined by canonical + documentation; +- an infrastructure failure that prevents required work after the configured + retry/fallback policy is exhausted. -Do not stop merely because an ordinary local implementation detail can be -resolved safely from existing code and documentation. +Do NOT stop merely because: + +- compilation fails; +- a normal test fails; +- an ordinary implementation bug exists; +- a reviewer identifies a bounded repairable defect; +- a dependency needs factual investigation; +- documentation status is stale; +- an implementation detail can be resolved safely from existing code and + contracts. + +Advance the project while preserving the contracts.