From 356cfd125c99ca16b5725bb0d103786fc579816f Mon Sep 17 00:00:00 2001 From: fy59 Date: Wed, 2 Sep 2026 22:41:29 +0200 Subject: [PATCH] docs: close documentation finding remediation --- README.md | 2 + docs/README.md | 253 +++++++++++++++++++++++++ docs/audits/documentation_inventory.md | 57 +++++- 3 files changed, 309 insertions(+), 3 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index 599d223..f71090a 100644 --- a/README.md +++ b/README.md @@ -305,6 +305,8 @@ The final product contracts for these areas are being defined separately before ## Documentation +- [Documentation index](docs/README.md) + ### Architecture - [Architecture overview](docs/architecture/overview.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7ad105f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,253 @@ +# Lardon3D Documentation Index + +## Status + +```text +DOCUMENTATION_INDEX=CURRENT +CURRENT_PROJECT_DB_SCHEMA=v25 +CURRENT_PRODUCTION_TASK_KINDS=16 + +REAL_S21_TRACKS=PASS/FROZEN +REAL_A6000_PRE_SFM=PASS/FROZEN +``` + +This index separates current authority, historical evidence and future product-definition work. + +Repository documentation is read in context: an older schema number, Task count or resource measurement +inside a historical checkpoint is not stale merely because the current repository has moved forward. + +## Authority order + +When current-state prose disagrees, use this order: + +1. `AGENTS.md` for repository-wide engineering/agent obligations and protected boundaries. +2. Specialized architecture documents for the subsystem contract they own. +3. `docs/roadmap/roadmap.md` for current lifecycle / next work. +4. `README.md` and architecture overview for concise summaries. +5. Historical audits only for the checkpoint they explicitly record. + +Executable source and schema implementation remain authoritative when a documentation excerpt claims to +quote an exact API, DDL or constant. + +## Current repository state + +```text +Project DB head v25 +Production Task kinds 16 + +v22 selected scientific execution foundation +v23 generic optical-context overlay +v24 raw.develop.batch/1 persistence +v25 features.extract.batch/1 persistence +``` + +Canonical resource objective: + +```text +MAXIMUM_SAFE_USEFUL_THROUGHPUT +SERIALISM_REQUIRES_PROOF +``` + +Reference-host values are measurements, not portable constants. + +## Current real-data checkpoints + +### S21 + +```text +REAL_S21_TRACKS=PASS/FROZEN +``` + +The retained S21 proof reaches Tracks. + +### A6000 + +```text +real-a6000-pre-sfm-2026-09-02 +REAL_A6000_PRE_SFM=PASS/FROZEN +``` + +Retained A6000 counts: + +```text +Feature Sets 689 +Candidate Pairs 38,420 +Match Results 38,420 +Applicable GVRs 37,805 +Verified GVRs 10,952 +Rejected GVRs 26,853 +Track Sets 1 +Tracks 130,714 +Track observations 318,944 +``` + +The A6000 checkpoint stops before real Sparse SfM and Dense/MVS. + +Sparse SfM capability exists through frozen Gates C-G. Real Sparse SfM on the historical S21/A6000 +campaigns remains blocked by known-calibration data. + +## Current architecture + +Start here: + +- [Architecture overview](architecture/overview.md) +- [Reconstruction pipeline](architecture/reconstruction_pipeline.md) +- [Runtime](architecture/runtime.md) +- [Persistence](architecture/persistence.md) +- [Project Database](architecture/project_database.md) + +### Task / resource execution + +- [Task System](architecture/task_system.md) +- [Task Queue](architecture/task_queue.md) +- [Task Kind Registry](architecture/task_kind_registry.md) +- [Resource Governor](architecture/resource_governor.md) +- [Resource Boundary](architecture/resource_boundary.md) +- [Resource-aware Pipeline](architecture/resource_aware_pipeline.md) +- [Internal Parallelism](architecture/internal_parallelism.md) +- [Scheduler / Resource Integration](architecture/scheduler_resource_integration.md) + +Resource authority split: + +```text +resource_governor.md runtime policy +AGENTS.md engineering / agent obligations +target_hardware.md reference-host evidence +other documents scoped summaries and links +``` + +## Scientific pipeline + +- [Photo Quality Triage](architecture/photo_quality_triage.md) +- [Feature Store](architecture/feature_store.md) +- [Precision Feature Pipeline](architecture/precision_feature_pipeline.md) +- [Visual Index](architecture/visual_index.md) +- [Candidate Pair](architecture/candidate_pair.md) +- [Match Result](architecture/match_result.md) +- [Matcher](architecture/matcher.md) +- [Geometric Verification Model](architecture/geometric_verification.md) +- [Geometric Verifier](architecture/geometric_verifier.md) +- [Track Model](architecture/tracks.md) +- [Track Builder](architecture/track_builder.md) +- [Sparse SfM](architecture/sparse_sfm.md) +- [Vulkan ORB Matcher](architecture/vulkan_matcher.md) + +Current production Geometric Verifier lineage: + +```text +Fundamental v1 historical valid identity +Fundamental v2 historical valid identity +Fundamental v3 current production identity +``` + +Historical verifier results are never relabelled. + +## Calibration + +- [Calibration Science v1](architecture/calibration_science_v1.md) +- [Calibration Bootstrap v1](architecture/calibration_bootstrap.md) +- [Calibration Solver Preflight v1](architecture/calibration_solver_preflight_v1.md) + +Historical S21/A6000 geometry evidence must not be retroactively given invented calibration. + +## Development + +- [Build](development/build.md) +- [Testing](development/testing.md) +- [Concurrency](development/concurrency.md) +- [Target Hardware](performance/target_hardware.md) + +Build/test parallelism is host-aware. Fixed historical `-j8`, `-j12` or serialized-suite evidence does +not become a portable default. + +TSan/OpenCV/TBB qualifications and Vulkan validation remain separate evidence boundaries. + +## Roadmap + +- [Roadmap](roadmap/roadmap.md) + +The roadmap owns the current lifecycle / next-work cursor. + +Historical progress cursors inside other records do not override it. + +## Audits + +- [Documentation Inventory Audit](audits/documentation_inventory.md) +- [Global Maintenance Audit](architecture/global_maintenance_audit.md) +- [Foundation Review](architecture/foundation_review.md) + +### Historical audit rule + +`global_maintenance_audit.md` and `foundation_review.md` are historical evidence. + +Do not mechanically modernize their old: + +- schema version; +- Task count; +- compiler/build count; +- resource measurement; +- checkpoint status. + +The later A6000 checkpoint adds new operational evidence; it does not erase the maintenance checkpoint. + +## Concepts + +- [Scan Sets](concepts/scan_sets.md) +- [Visual Index concept](concepts/visual_index.md) +- [Matching and Tracks](concepts/matching_and_tracks.md) +- [Reconstruction Layers](concepts/reconstruction_layers.md) +- [Geometric Constraints](concepts/geometric_constraints.md) + +Concept documents may be historical or explanatory. They do not outrank the current specialized +architecture contract. + +## Future product-definition boundary + +The documentation audit does not invent final contracts for: + +- viewer; +- A6000 live acquisition; +- S21 live acquisition; +- coverage analysis; +- capture guidance; +- suggested viewpoints; +- video/keyframe ingestion; +- final optics onboarding UX; +- profile import/export UX; +- dense/mesh/texture/export UX. + +Those belong to the separate Product Definition and final prompt-tree phases. + +## Repository language + +Canonical target: + +```text +DOCUMENTATION_LANGUAGE=ENGLISH +SOURCE_COMMENT_LANGUAGE=ENGLISH +AGENT_CONTRACT_LANGUAGE=ENGLISH +USER_INTERFACE_LANGUAGE=ENGLISH +``` + +The current-state documentation findings have been remediated in English. + +Some untouched historical/current documents may still require a mechanical language-only normalization +pass. Such translation must preserve historical facts and must not silently modernize scientific or +lifecycle state. + +Executable UI strings are changed only in an explicitly scoped UI-language implementation pass. + +## Navigation rule for future agents + +Before implementation: + +```text +read AGENTS.md +-> read README.md +-> read this index +-> read the specialized architecture contract +-> read the current roadmap +-> inspect historical audits only when their evidence is relevant +``` + +Never use an older historical checkpoint as a substitute for current authority. diff --git a/docs/audits/documentation_inventory.md b/docs/audits/documentation_inventory.md index 9d95b1c..8260a5d 100644 --- a/docs/audits/documentation_inventory.md +++ b/docs/audits/documentation_inventory.md @@ -2,7 +2,7 @@ ## Status -DOCUMENTATION_INVENTORY_AUDIT=IN_PROGRESS +DOCUMENTATION_INVENTORY_AUDIT=PASS_WITH_FINDINGS Audit branch: docs-audit @@ -564,10 +564,61 @@ The comment audit will focus on WHY, CONTRACT, INVARIANT, OWNERSHIP, IDENTITY, p No mass source-comment editing is authorized by this inventory. +# Remediation closure — 2026-09-02 + +The documentation finding-remediation pass is complete. + +```text +D1=PASS +D2=PASS +D3=PASS +D4=PASS +D5=PASS + +BLOCKING_DOC_RESOLVED=7/7 +IMPORTANT_RESOLVED=11/11 + +AUTHORITY_FINDINGS_RESOLVED=3/3 +LINK_FINDINGS_RESOLVED=1/1 +``` + +D1 converged README, AGENTS, roadmap, Project DB and persistence on the current v25 lifecycle. + +D2 reconciled resource/runtime documentation with sixteen production Task kinds, +`MAXIMUM_SAFE_USEFUL_THROUGHPUT`, `SERIALISM_REQUIRES_PROOF`, the v24 RAW batch path and the v25 +Feature batch path. + +D3 replaced stale developer API/build examples, removed fixed build-width policy and preserved the +qualified sanitizer/TSan/Vulkan evidence boundaries. + +D4 reconciled Sparse SfM lifecycle, Track verifier lineage, Visual Index downstream status, current +Geometric Verifier v3 and runtime current-state wording without reopening frozen scientific contracts. + +D5 adds `docs/README.md` as the navigation/authority map and removes the stale fifteen-kind +cross-document anchor dependency. + +The historical `global-maintenance-2026-09-01` checkpoint remains authoritative evidence for the +unchanged boundaries it reviewed. The later `real-a6000-pre-sfm-2026-09-02` checkpoint adds real-data +operational evidence and does not erase the maintenance checkpoint. + +No source code, schema, Task Kind, scientific threshold, Sparse SfM execution, Dense/MVS execution, +viewer or live-capture implementation is authorized by this closure. + +## Language normalization boundary + +Human authority selected English as the repository language. + +The documents modified by the finding-remediation pass are English. Other untouched documentation may +still contain historical or current non-English prose. That remaining language-only normalization is +tracked separately and must not be mistaken for an unresolved current-state authority finding. + +Translation of historical evidence must preserve the historical checkpoint exactly. + # Phase state - DOCUMENTATION_INVENTORY_AUDIT=PASS_WITH_FINDINGS -- DOCUMENTATION_REMEDIATION=IN_PROGRESS -- SOURCE_COMMENT_AUDIT=NOT_STARTED +- DOCUMENTATION_FINDING_REMEDIATION=PASS +- DOCUMENTATION_LANGUAGE_NORMALIZATION=IN_PROGRESS +- SOURCE_COMMENT_AUDIT=NEXT - PRODUCT_DEFINITION=NOT_STARTED - PROMPT_TREE=NOT_STARTED