lardon3d/AGENTS.md

Lardon3D — Agent Engineering Contract

1. Authority and priority

• The root README.md is the index of project documentation.
• Canonical documents under docs/** define scientific contracts, architecture, 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 implementation convenience never overrides a higher-level canonical contract.
• 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 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
• Track Builder — PASS/FROZEN
• F0 — PASS/FROZEN
• Phase H v1 — PASS/FROZEN
• MVS-M1 — PASS/FROZEN
• Project DB v22 — PASS/FROZEN
• Calibration Bootstrap v1 — PASS/FROZEN
• Selected Scientific Execution — PASS/FROZEN
• Photo Quality Triage / Acquisition Selection — 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

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 v22 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 --short before editing.
• Preserve unrelated user and worktree changes.
• Modify only files authorized by the current ticket.
• Never modify or add anything under scan3d/, especially 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:
  • 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, 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 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.
• 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 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.

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, 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.
• 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.

Resource-sensitive work must identify, where relevant:

• 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 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.
• 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 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.

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:

// Increment index.
index++;

Good:

// 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:

// 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:

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:

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.
• 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.
• 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.

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 v22 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, resources, limits, or scientific semantics, check whether canonical documentation must be updated.
• Documentation must describe proven implementation, not desired future behavior.
• 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.

12. Required validation

For ordinary implementation tickets, before claiming completion, actually run the applicable commands.

Normal build:

meson setup --reconfigure build
meson compile -C build -j8

Normal tests:

meson test -C build --num-processes 1 --print-errorlogs

Diff validation:

git diff --check

For every new or modified public C header, also run a C17 syntax check, for example:

cc -x c -std=c17 -fsyntax-only -Iinclude \
  -include lardon3d/<header>.h /dev/null

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 and meaningful.

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/checks not executed;
• known blockers;
• non-blocking findings;
• deliberately deferred/future-scope items;
• 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 only when resolution requires:

• 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:

• 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.