docs: strengthen agent engineering contract

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.