diff --git a/docs/audits/documentation_inventory.md b/docs/audits/documentation_inventory.md new file mode 100644 index 0000000..cc45d39 --- /dev/null +++ b/docs/audits/documentation_inventory.md @@ -0,0 +1,556 @@ +# Lardon3D — Documentation Inventory Audit + +## Status + +DOCUMENTATION_INVENTORY_AUDIT=IN_PROGRESS + +Audit branch: docs-audit + +Reference checkpoints: + +- global-maintenance-2026-09-01 +- real-a6000-pre-sfm-2026-09-02 + +This audit concerns documentation only. + +It does not reopen scientific contracts, alter executable behavior, redefine FROZEN evidence, or authorize implementation work. + +## Classification vocabulary + +Documents/findings use: CURRENT_AND_COMPLETE, CURRENT_BUT_INCOMPLETE, PARTIALLY_STALE, STALE, HISTORICAL_AND_VALID, DUPLICATED_AUTHORITY, AMBIGUOUS_AUTHORITY, NEEDS_REORGANIZATION. + +Finding severity: BLOCKING_DOC, IMPORTANT, IMPROVEMENT. + +A BLOCKING_DOC finding means documentation could make a future agent work from the wrong project state. It does not mean executable code is known to be incorrect. + +## Current facts + +Current Project DB head: v25. + +Valid historical/additive foundations remain: + +- v22 = selected scientific execution foundation +- v23 = generic optical-context overlay +- v24 = raw.develop.batch persistence +- v25 = features.extract.batch persistence + +Current production inventory: 16 Task kinds. + +Canonical resource policy: + +- MAXIMUM SAFE USEFUL THROUGHPUT +- SERIALISM_REQUIRES_PROOF + +Reference-host evidence: + +- 16 logical CPUs total +- approximately 4 logical CPUs reserved for interactive host use +- approximately 12 logical CPUs available to compute +- approximately 3 GiB MemAvailable hard reserve +- Radeon 780M UMA + +These are observations of the reference host, not portable product constants. + +Real-data checkpoints: + +- REAL_S21_TRACKS=PASS/FROZEN +- REAL_A6000_PRE_SFM=PASS/FROZEN + +A6000 final pre-SfM evidence: + +- Feature Sets: 689 +- Candidate Pairs: 38,420 +- Match Results: 38,420 +- Applicable GVR: 37,805 +- Verified GVR: 10,952 +- Rejected GVR: 26,853 +- Track Sets: 1 +- Tracks: 130,714 +- Track observations: 318,944 +- Sparse SfM: NOT EXECUTED +- Dense/MVS: NOT EXECUTED + +# BLOCKING_DOC findings + +## DOC-B01 — Roadmap contains mutually exclusive current states + +File: docs/roadmap/roadmap.md + +The roadmap contains the acquired REAL_A6000_PRE_SFM=PASS/FROZEN result but also retains obsolete current-next material describing Project DB v24/v25 as validation in progress and instructing a resume from A6000 cursor 259 with 430 RAW representations remaining. + +Those operations have already completed. + +Required correction: + +- preserve useful historical evidence; +- mark the cursor-259 and validation-in-progress material as historical; +- make the final A6000 pre-SfM proof authoritative; +- define one unambiguous CURRENT NEXT state. + +## DOC-B02 — Project Database has competing current heads + +File: docs/architecture/project_database.md + +Different sections present v23, v24 and v25 as current state. + +The actual current schema head is v25. + +v22, v23 and v24 remain valid historical and additive contracts. They must not be erased or rewritten as though they never existed. + +Required correction: + +- state once near the top that current Project DB head is v25; +- preserve v22 selected execution, v23 optics and v24 RAW batch as historical additive foundations; +- update v25 Feature batch lifecycle to match acquired real evidence. + +## DOC-B03 — Persistence advertises v23 as current + +File: docs/architecture/persistence.md + +The document currently states that the current schema is v23. + +Required correction: + +- current schema = v25; +- retain historical v7, v16, v22 and v23 contracts; +- add a concise v24 RAW batch and v25 Feature batch persistence summary. + +## DOC-B04 — Resource-aware pipeline describes superseded serial Features + +File: docs/architecture/resource_aware_pipeline.md + +Current prose still describes Feature Extraction as one durable task per image with batch one and one worker as the complete operational model. + +That description is incomplete after features.extract.batch/1, Project DB v25, bounded cross-image participants, coupled CPU/batch scaling and owner-only ordered publication. + +The document also retains a fourteen-Task current inventory even though production now contains sixteen Task kinds. + +Required correction: + +- preserve per-image Feature scientific atomicity; +- document the v25 cross-image batch path; +- distinguish per-item atomicity from cross-item serialism; +- update current Task count to sixteen. + +## DOC-B05 — Development testing guide uses obsolete API examples + +File: docs/development/testing.md + +The guide contains examples based on old-style names including task_estimate_t, task_t, task_create, TASK_STATE_IDLE and g_test_*. + +These examples do not represent the current repository API and test style. + +Because this is a developer instruction document rather than historical evidence, stale examples are dangerous. + +It also retains repeated wipe-build and fixed -j8 assumptions that conflict with current delta-validation and host-aware parallelism policy. + +Required correction: + +- rewrite examples against actual current repository tests and public APIs; +- use current Meson targets and validation discipline; +- preserve exact sanitizer qualifications; +- avoid mandatory repeated full rebuilds when the delta does not justify them. + +## DOC-B06 — Sparse SfM opening lifecycle is historical but presented as current + +File: docs/architecture/sparse_sfm.md + +The opening still describes numerical Sparse SfM as deferred to Gate C and later gates. + +Later sections and other canonical documents establish Gates C, D, E, F and G as acquired. + +Required correction: + +- retain Gate A and Gate B history; +- label early lifecycle wording as historical; +- add a concise current lifecycle summary; +- distinguish implemented Sparse SfM capability from real Sparse SfM execution on current historical campaigns, which remains unexecuted because known calibration data is unavailable. + +## DOC-B07 — README presents obsolete current DB state + +File: README.md + +README still presents Project DB v23 as the effective current head. + +Required correction: + +- current Project DB = v25; +- mention RAW batch v24 and Feature batch v25; +- register REAL_S21_TRACKS=PASS/FROZEN; +- register REAL_A6000_PRE_SFM=PASS/FROZEN; +- state clearly that Sparse SfM and Dense/MVS were not executed in the A6000 real pre-SfM proof. + +# IMPORTANT findings + +## DOC-I01 — AGENTS.md still describes v25 proof as unfinished + +File: AGENTS.md + +The resource policy and Source Comment Contract are strong and current. + +However, lifecycle prose still describes the v25 Feature-batch tranche as not yet eligible for final closure. + +Required correction: + +- update the v25 lifecycle wording to match acquired evidence; +- register REAL_A6000_PRE_SFM=PASS/FROZEN; +- retain global-maintenance-2026-09-01 as valid historical review evidence; +- document the later A6000 checkpoint without erasing the maintenance checkpoint. + +## DOC-I02 — Resource Boundary contains stale current schema and Task count + +File: docs/architecture/resource_boundary.md + +Present-tense material still contains combinations of current schema v24, Project Database v23 as current identity owner, fourteen current Task kinds and migrations only through v23. + +The no-generic-Resource-System decision remains valid and must remain historical authority. + +Required correction: + +- update only stale present-tense current-state claims; +- current schema = v25; +- current production inventory = 16 Task kinds; +- preserve the original Gate G and no-new-subsystem decisions. + +## DOC-I03 — Architecture overview weakens the canonical resource policy + +File: docs/architecture/overview.md + +The overview states that host stability and TUI responsiveness have priority over maximum throughput without the qualification introduced by the current canonical policy. + +The current rule is to preserve the defined interactive host reserve and then maximize safe useful throughput. + +Leaving additional safe and useful resources idle is not a stability strategy. + +Required correction: + +- align the overview with MAXIMUM SAFE USEFUL THROUGHPUT; +- preserve the interactive host reserve as the safety boundary; +- summarize v24 and v25 operational overlays without making reference-host values portable constants. + +## DOC-I04 — Candidate resource sections contradict each other + +File: docs/architecture/candidate_pair.md + +The current Task section describes approximately 256 KiB fixed memory, 8 MiB per admitted item, batch 1..64 and coupled CPU/batch scaling. + +A later resource section still describes historical values around a 24-source window and 64 KiB per item. + +Required correction: + +- reconcile the later resource section with the current validated Task capability; +- preserve Candidate scientific identity, scoring, ordering and persistence; +- keep historical estimates only when explicitly labelled historical. + +## DOC-I05 — Feature Store omits the v25 selected-execution batch path + +File: docs/architecture/feature_store.md + +The scientific Feature File contract is strong, but operational prose still describes only the historical single-image features.extract/1 path as the production model. + +Required correction: + +- preserve features.extract/1; +- document features.extract.batch/1 as an additional current operational path; +- distinguish per-image scientific atomicity from cross-image execution concurrency; +- keep general DAG planning separately deferred. + +## DOC-I06 — Task Kind Registry uses an obsolete 15-kind anchor + +File: docs/architecture/task_kind_registry.md + +The document correctly states that production contains 16 Task kinds but links to resource_governor.md#audit-des-15-kinds-de-production. + +Required correction: + +- synchronize the Resource Governor heading and Registry link around the current 16-kind inventory; +- do not alter historical audit counts that were correct at their checkpoint. + +## DOC-I07 — Generic Task adaptation prose conflicts with coupled CPU/batch kinds + +File: docs/architecture/task_system.md + +Generic Compute Governor prose says CPU and batch are never tried together. + +Feature Batch and Candidate now have legitimate coupled CPU/batch rungs because additional CPU cannot exercise additional independent work while the admitted item window remains one. + +Required correction: + +- retain independent-dimension adaptation as the generic rule; +- document explicit coupled cross-item exceptions where the dimensions are operationally inseparable for measurement; +- do not make coupled scaling universal. + +## DOC-I08 — Build guide retains historical fixed -j8 examples + +File: docs/development/build.md + +Build examples repeatedly use -j8 while current engineering policy requires safe host-aware parallelism. + +Required correction: + +- describe build parallelism as host-derived; +- a reference-host example may use approximately -j12 when clearly labelled as reference-host evidence; +- no fixed job count becomes a portable product constant. + +## DOC-I09 — Concurrency guide retains historical build-policy examples + +File: docs/development/concurrency.md + +The concurrency, lifetime and TSan qualification rules are valuable and mostly current, but the build example still uses fixed -j8 and some illustrative snippets do not represent exact current public API names. + +Required correction: + +- align build parallelism with host-aware policy; +- identify illustrative pseudo-code as illustrative when it is not exact repository API; +- preserve the external OpenCV and TBB TSan qualification; +- preserve the separate Vulkan validation boundary. + +## DOC-I10 — Visual Index describes implemented downstream work as future + +File: docs/architecture/visual_index.md + +The final future section still describes Candidate Pair Generator and Matcher as future consumers. + +Both are implemented. + +Required correction: + +- replace the stale future wording with the actual current downstream relationship or explicitly mark it as historical design context; +- do not change Visual Index scientific identity or capacity contracts. + +## DOC-I11 — Track Model contains stale production selector and pipeline wording + +File: docs/architecture/tracks.md + +The Track Model scientific contract remains valid, but some prose still presents Geometric Verifier v1 as the production selector and Sparse SfM as future. + +Current real Track evidence uses Geometric Verifier v3. Sparse SfM Gates C through G are implemented, while real known-calibration Sparse SfM on the historical real campaigns remains unexecuted. + +Required correction: + +- preserve Track Model v1 identity and persistence semantics; +- distinguish historical verifier-v1 examples from the current v3 production lineage; +- distinguish implemented Sparse SfM capability from real campaign execution. + +# Document classification + +## CURRENT_AND_COMPLETE + +The following documents are currently strong enough that no major contract rewrite is justified by this audit: + +- docs/architecture/calibration_science_v1.md +- docs/architecture/calibration_bootstrap.md +- docs/architecture/calibration_solver_preflight_v1.md +- docs/architecture/photo_quality_triage.md +- docs/architecture/task_queue.md +- docs/architecture/matcher.md +- docs/architecture/track_builder.md +- docs/performance/target_hardware.md + +Small consistency edits may still be appropriate later. + +## CURRENT_BUT_INCOMPLETE + +The following documents have strong core contracts but need limited current-state reconciliation: + +- docs/architecture/internal_parallelism.md +- docs/architecture/runtime.md +- docs/architecture/geometric_verification.md +- docs/architecture/geometric_verifier.md + +## HISTORICAL_AND_VALID + +The following documents must remain historical evidence and must not be mass-modernized: + +- docs/architecture/global_maintenance_audit.md +- docs/architecture/foundation_review.md +- docs/concepts/matching_and_tracks.md +- docs/concepts/reconstruction_layers.md + +Older Task counts, schema versions, measurements and decisions may be exactly correct for the checkpoint described by those documents. + +An old version number is stale only when the prose claims that it is the current state. + +# Documentation authority findings + +## AUTH-01 — Current Project DB authority is ambiguous + +Current-version claims are distributed across: + +- README.md +- docs/architecture/project_database.md +- docs/architecture/persistence.md +- docs/architecture/resource_boundary.md +- docs/roadmap/roadmap.md + +They must converge on one current-state fact: + +Project DB current schema = v25 + +Detailed v22, v23, v24 and v25 contracts remain owned by the specialized architecture documents. + +## AUTH-02 — Resource policy is duplicated across too many authorities + +Resource policy currently appears in AGENTS, Governor, Resource Boundary, Resource Aware Pipeline, Internal Parallelism, Overview, Target Hardware, Build and Concurrency documentation. + +Desired authority split: + +- docs/architecture/resource_governor.md owns runtime resource policy; +- AGENTS.md owns engineering and agent obligations; +- docs/performance/target_hardware.md owns reference-host measurements; +- other documents summarize and link instead of redefining policy. + +## AUTH-03 — Latest real checkpoint needs first-class documentation + +The repository now contains the real checkpoint real-a6000-pre-sfm-2026-09-02. + +Documentation must explain its relationship to global-maintenance-2026-09-01. + +The newer checkpoint does not erase the maintenance checkpoint. The maintenance checkpoint remains historical review authority for unchanged frozen systems; the A6000 checkpoint adds later operational and real-data evidence. + +## LINK-01 — Task Kind Registry anchor is stale + +docs/architecture/task_kind_registry.md states sixteen kinds but points to a Resource Governor anchor named for fifteen kinds. + +The heading and cross-link must be synchronized without altering historical fourteen-kind audit evidence. + +# Product documentation intentionally deferred + +This documentation cleanup must not invent final contracts for: + +- Viewer behavior; +- Sony A6000 live acquisition; +- Samsung S21 live acquisition; +- Coverage Analysis; +- Capture Guidance; +- suggested viewpoints; +- video and keyframe ingestion; +- final optics onboarding UX; +- optics profile import and export; +- final mesh, texture and export UX. + +Those areas will be defined explicitly by the human during the PRODUCT_DEFINITION phase before the final prompt/ execution contract is frozen. + +Already established human product intent includes: + +- NEW_CAMERA_REQUIRES_CODE_CHANGE=NO +- NEW_LENS_REQUIRES_CODE_CHANGE=NO +- ELECTRONIC_LENS_WITH_METADATA=SUPPORTED +- MANUAL_LENS_WITHOUT_EXIF=SUPPORTED +- MULTIPLE_LENSES_PER_CAMERA=SUPPORTED +- ZOOM_MULTIPLE_FOCALS=SUPPORTED +- MULTIPLE_OPTICAL_CONFIGURATIONS_PER_PROJECT=SUPPORTED +- SILENT_CALIBRATION_SUBSTITUTION=FORBIDDEN +- SILENT_LENS_IDENTITY_INFERENCE=FORBIDDEN +- OPTICS_TUI_WORKFLOW=REQUIRED +- PROFILE_IMPORT_EXPORT=REQUIRED + +These statements describe product intent only. They do not authorize implementation during this documentation audit. + +# Documentation remediation order + +## D1 — Current-state authority + +Correct first: + +- README.md +- AGENTS.md +- docs/roadmap/roadmap.md +- docs/architecture/project_database.md +- docs/architecture/persistence.md + +Goal: one coherent current lifecycle and one explicit Project DB v25 head. + +## D2 — Resource and runtime consistency + +Then correct: + +- docs/architecture/resource_boundary.md +- docs/architecture/resource_aware_pipeline.md +- docs/architecture/overview.md +- docs/architecture/candidate_pair.md +- docs/architecture/feature_store.md +- docs/architecture/task_kind_registry.md +- docs/architecture/task_system.md + +Goal: current operational descriptions obey MAXIMUM SAFE USEFUL THROUGHPUT and SERIALISM_REQUIRES_PROOF without rewriting frozen science. + +## D3 — Developer instructions + +Then correct: + +- docs/development/testing.md +- docs/development/build.md +- docs/development/concurrency.md + +Goal: developer instructions match current APIs, build policy and validation discipline. + +## D4 — Targeted scientific and current-state wording cleanup + +Then inspect and correct only stale lifecycle wording in: + +- docs/architecture/sparse_sfm.md +- docs/architecture/tracks.md +- docs/architecture/visual_index.md +- docs/architecture/geometric_verification.md +- docs/architecture/geometric_verifier.md +- docs/architecture/runtime.md + +This phase must not reopen FROZEN science. + +## D5 — Documentation index and links + +Finally reconcile README navigation, historical/current labels and cross-document anchors. + +# Finding summary + +BLOCKING_DOC = 7 + +IMPORTANT = 11 + +Highest-priority files: + +1. docs/roadmap/roadmap.md +2. docs/architecture/project_database.md +3. docs/architecture/persistence.md +4. docs/architecture/resource_aware_pipeline.md +5. docs/development/testing.md +6. docs/architecture/sparse_sfm.md +7. README.md + +# Audit boundary + +This report does not authorize: + +- scientific threshold changes; +- new schema versions; +- new Task kinds; +- resource-policy redesign; +- Viewer implementation; +- live-capture implementation; +- Sparse SfM execution; +- Dense/MVS execution. + +The next separate audit is SOURCE_COMMENT_AUDIT over include/lardon3d/** and src/**. + +Source comments will later be classified as: + +- EXCELLENT +- GOOD +- ACCEPTABLE +- UNDER_COMMENTED +- SEVERELY_UNDER_COMMENTED +- STALE_COMMENT +- MISLEADING_CONTRACT_COMMENT + +The comment audit will focus on WHY, CONTRACT, INVARIANT, OWNERSHIP, IDENTITY, persistence ordering, restart, cancellation, concurrency, resource accounting and FROZEN boundaries. + +No mass source-comment editing is authorized by this inventory. + +# Phase state + +- DOCUMENTATION_INVENTORY_AUDIT=PASS_WITH_FINDINGS +- DOCUMENTATION_REMEDIATION=NOT_STARTED +- SOURCE_COMMENT_AUDIT=NOT_STARTED +- PRODUCT_DEFINITION=NOT_STARTED +- PROMPT_TREE=NOT_STARTED