t81dev · t81dev · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
@@ -245,3 +245,5 @@ Estas ventajas se combinan en dominios donde **la reproducibilidad**, **la infer
 ## Licencia
 
 Licencia Apache 2.0.
+
+> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
@@ -239,3 +239,5 @@ Apache 2.0
 
 Thanks for checking it out.  
 Early feedback, issues, and contributors are very welcome.
+
+> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
@@ -245,3 +245,5 @@ Essas vantagens se combinam em domínios em que **reprodutibilidade**, **inferê
 ## Licença
 
 Licença Apache 2.0.
+
+> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
@@ -245,3 +245,5 @@ ctest --test-dir build --output-on-failure
 ## Лицензия
 
 Лицензия Apache 2.0.
+
+> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
@@ -245,3 +245,5 @@ IEEE 754 浮点数存在破坏可重复性的平台特定舍入模式、结合
 ## 许可证
 
 Apache 许可证 2.0。
+
+> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
@@ -198,7 +198,7 @@ Key files:
 - [README.md](../README.md)
 - [docs/README.md](README.md)
 - [docs/HANDOFF.md](HANDOFF.md)
-- [docs/ROADMAP.md](ROADMAP.md)
+- [docs/status/ROADMAP.md](status/ROADMAP.md)
 
 Definition of done:
 

@@ -65,7 +65,7 @@ When in doubt, prefer these in order:
 - Documentation index: [docs/README.md](README.md)
 - Contributing guide: [CONTRIBUTING.md](../CONTRIBUTING.md)
 - Buildable next tasks: [docs/BUILDABLE_NEXT_STEPS.md](BUILDABLE_NEXT_STEPS.md)
-- Contributor-facing roadmap: [docs/ROADMAP.md](ROADMAP.md)
+- Contributor-facing roadmap: [docs/status/ROADMAP.md](status/ROADMAP.md)
 - AI CLI reality check: [docs/status/AI_CLI_IMPLEMENTATION_MATRIX.md](status/AI_CLI_IMPLEMENTATION_MATRIX.md)
 
 The short version:

@@ -1,100 +1,3 @@
 # T81 Contributor Roadmap
 
-This is the short roadmap for someone trying to build T81 forward without first absorbing the entire historical planning corpus.
-
-## Roadmap goal
-
-Move T81 from "ambitious and credible" toward "pick-up-able and extensible by new contributors" without weakening its determinism, governance, or provenance posture.
-
-## Phase 1: Make the current value obvious
-
-Primary goal: make the runtime story clearer than the long-horizon OS story.
-
-Success looks like:
-
-- a newcomer can tell what T81 is in under a minute
-- the runtime path feels complete enough to try and explain
-- the docs clearly distinguish:
-  - usable now
-  - experimental but demoable
-  - draft architectural direction
-
-Recommended work:
-
-- continue tightening README and docs entry points
-- reduce duplicated roadmap/status material
-- keep handoff documents current
-
-## Phase 2: Harden the CanonFS interchange lane
-
-Primary goal: turn RFC-00D1 from a good seed into a contributor-friendly subsystem.
-
-Success looks like:
-
-- import/export semantics are stable enough for non-authors to build against
-- policy and provenance are real, not placeholder-shaped
-- interchange behavior is documented in a small number of obvious files
-- the stable seed contract is named explicitly so examples, tests, and tooling
-  can depend on it without pretending the whole RFC is finished
-
-Recommended work:
-
-- deepen policy-profile semantics
-- add more negative/edge-case tests
-- clarify which RFC-00D1 surfaces are draft vs implementation detail
-- keep the current stable seed explicit:
-  `canonfs import` / `canonfs export`,
-  `t81.canonfs-import.v1`,
-  `t81.canonfs-export.v1`,
-  provenance/manifest schemas,
-  `host-file` / `host-directory`,
-  and current policy-profile names
-- consider promoting more of RFC-00D1 only after the deferred v1 questions stop
-  moving
-
-## Phase 3: Pick one narrow new subsystem and keep it narrow
-
-Primary goal: avoid broad new architectural spread.
-
-Best candidate today:
-
-- RFC-00D0 service descriptor and resolution prototype before full TCP/IP breadth
-
-Success looks like:
-
-- a small base-81-aware resolver exists
-- CanonFS-backed descriptor loading works
-- API and evidence behavior are testable without pretending the full stack is done
-
-## Phase 4: Keep the repo boring to operate
-
-Primary goal: portability, CI, and docs should not become the bottleneck.
-
-Success looks like:
-
-- CI failures are mostly meaningful, not housekeeping
-- formatting and portability regressions are fixed quickly
-- Windows/macOS/Linux lanes stay trustworthy
-
-Recommended work:
-
-- keep workflow drift low
-- keep portable helper patterns centralized
-- avoid reintroducing ad hoc platform-specific builtins or checkout gaps
-
-## What not to do next
-
-- do not expand scope across many draft subsystems at once
-- do not rewrite stable accepted surfaces just because the repo is large
-- do not make the OS/bare-metal lane the only public story
-- do not let planning docs multiply faster than buildable work
-
-## Decision rule
-
-Prefer work that does one of these:
-
-- makes a current surface easier to adopt
-- turns draft work into something another engineer can finish
-- removes project dependence on one maintainer’s memory
-
-De-prioritize work that mainly adds conceptual breadth without making the existing system easier to use or extend.
+> **Note:** This document has been superseded. Please see the authoritative roadmap at [`docs/status/ROADMAP.md`](status/ROADMAP.md) for current planning, strategy, and subsystem execution details.
@@ -5,7 +5,7 @@ Last Verified (UTC): 2026-02-26
 Maturity: Mixed (`Frozen` core, `Experimental` periphery)
 
 > **Architecture File Style Guide**
-> - Terminology mapping: "TISC ISA" -> `core/isa/`; "VM Interpreter" -> `vm/vm.cpp`; "Axion Governance Engine" -> `kernel/axion/`; "CanonFS" -> `fs/` + `include/t81/canonfs/`; "Experimental tiers" -> `experimental/`.
+> - Terminology mapping: "TISC ISA" -> `isa/`; "VM Interpreter" -> `vm/`; "Axion Governance Engine" -> `kernel/axion/`; "CanonFS" -> `fs/` + `include/t81/canonfs/`; "Experimental tiers" -> `experimental/`.
 > - Link style: repo-relative markdown links to concrete files only.
 > - Diagram conventions: GitHub-renderable Mermaid only.
 > - Maturity labels: `Frozen`, `Stable`, `Experimental`, `Stubbed`.
@@ -37,11 +37,11 @@ Diagram source: [`diagrams/overview-layer-cake.mmd`](./diagrams/overview-layer-c
 
 | Layer | Primary code | Primary spec | Maturity | Notes |
 | :--- | :--- | :--- | :--- | :--- |
-| Data types | `core/types/` | [`spec/t81-data-types.md`](../../spec/t81-data-types.md) | Frozen | Deterministic-core surface. |
-| TISC ISA | `core/isa/` + VM decode/dispatch | [`spec/tisc-spec.md`](../../spec/tisc-spec.md) | Frozen | Opcode semantics/freeze governed. |
-| VM interpreter | `core/vm/` | [`spec/t81vm-spec.md`](../../spec/t81vm-spec.md) | Stable | DCP includes interpreter path, not JIT. |
+| Data types | `include/t81/types/` | [`spec/t81-data-types.md`](../../spec/t81-data-types.md) | Frozen | Deterministic-core surface. |
+| TISC ISA | `isa/` + VM decode/dispatch | [`spec/tisc-spec.md`](../../spec/tisc-spec.md) | Frozen | Opcode semantics/freeze governed. |
+| VM interpreter | `vm/` | [`spec/t81vm-spec.md`](../../spec/t81vm-spec.md) | Stable | DCP includes interpreter path, not JIT. |
 | Axion governance | `kernel/axion/` | [`spec/axion-kernel.md`](../../spec/axion-kernel.md) | Stable (bounded) | Policy verdicts integrated in VM step path. |
-| CanonFS | `src/canonfs/` + `include/t81/canonfs/` | [`spec/supplemental/canonfs-spec.md`](../../spec/supplemental/canonfs-spec.md) | Stable (bounded) | Integrity controls implemented; claims remain bounded. |
+| CanonFS | `fs/` + `include/t81/canonfs/` | [`spec/supplemental/canonfs-spec.md`](../../spec/supplemental/canonfs-spec.md) | Stable (bounded) | Integrity controls implemented; claims remain bounded. |
 | Experimental tiers/kernel concepts | `experimental/` | [`spec/cognitive-tiers.md`](../../spec/cognitive-tiers.md), [`spec/supplemental/hanoi-kernel-spec.md`](../../spec/supplemental/hanoi-kernel-spec.md) | Experimental / Stubbed | Not part of DCP guarantees. |
 
 ## Binary Host Execution Boundary

@@ -170,7 +170,7 @@ For someone discovering the project, the best reading order is:
 
 1. `README.md` for the current public story and first-run paths,
 2. `docs/HANDOFF.md` for what is mature, what is draft, and how to approach the codebase,
-3. `docs/ROADMAP.md` for the current sequencing of work,
+3. `docs/status/ROADMAP.md` for the current sequencing of work,
 4. `docs/BUILDABLE_NEXT_STEPS.md` for bounded contributor lanes,
 5. RFC-00D1 for the best current example of a draft architecture turning into code,
 6. RFC-00D0 for the networking direction that remains design-led.

@@ -0,0 +1,26 @@
+# Executive Summary
+
+## Total Documents Reviewed
+810 Markdown files were identified across the repository. The review focused on root documentation, architecture references, RFCs, governance policies, and status/roadmap trackers.
+
+## Major Stale Areas
+- **Architecture Overview (`docs/architecture/OVERVIEW.md`)**: References to `core/isa/`, `core/vm/`, and `core/types/` are stale. The repository structure is actually `isa/`, `vm/`, `fs/`, `include/t81/types/`, etc., at the root level.
+- **Status/Roadmap (`docs/status/ROADMAP.md` vs `docs/ROADMAP.md`)**: Duplication exists for roadmap documents.
+- **Governance script mismatch (`scripts/governance/check_docs_structure.py`)**: Book directory checks pointed to `book/book-en` instead of `docs/book/book-en`.
+
+## Major Contradictions
+- **Layer Mapping**: The `docs/architecture/OVERVIEW.md` layer mapping contradicts the physical repository layout (`isa`, `vm`, `fs`, `include` are top-level directories, not nested under a `core/` directory).
+- **Status Reporting**: Multiple files in `docs/` (like `ROADMAP.md` vs `docs/status/ROADMAP.md`) report redundant or potentially diverging information.
+
+## Highest-Risk Docs
+- `README.md` and translated equivalents
+- `docs/architecture/OVERVIEW.md`
+- `docs/ROADMAP.md` vs `docs/status/ROADMAP.md`
+- `docs/HANDOFF.md`
+
+## Systemic Doc Hygiene Problems
+- The repository was restructured (likely flattening `core/` to root), but architectural documentation was not updated to reflect this.
+- Link staleness due to directory structural changes.
+
+## Overall Documentation Health Assessment
+The documentation is largely excellent in intent, precision, and tone. However, it suffers from structural staleness due to a recent directory refactoring (e.g., flattening `core/`). The authoritative specifications (`spec/`) and governance documents are high quality, but the explanatory layer (`docs/architecture/`) needs immediate alignment with repository reality to prevent onboarding friction.
@@ -0,0 +1,12 @@
+# Document Inventory Table
+
+| Path | Type | Authority | Freshness | Risk | Recommended Action |
+|---|---|---|---|---|---|
+| `README.md` | root overview | canonical | VERIFIED | CRITICAL | KEEP |
+| `docs/architecture/OVERVIEW.md` | architecture reference | high-authority | STALE | HIGH | REVISE |
+| `docs/ROADMAP.md` | roadmap summary | operational | CONTRADICTED | HIGH | REPLACE |
+| `docs/status/ROADMAP.md` | roadmap | operational | VERIFIED | MEDIUM | KEEP |
+| `docs/HANDOFF.md` | onboarding doc | explanatory | PARTIALLY VERIFIED | HIGH | REVISE |
+| `docs/BUILDABLE_NEXT_STEPS.md` | roadmap/tasks | explanatory | PARTIALLY VERIFIED | MEDIUM | REVISE |
+| `docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md` | explanatory | explanatory | PARTIALLY VERIFIED | LOW | REVISE |
+| `scripts/governance/check_docs_structure.py` | script | operational | STALE | HIGH | REVISE |
@@ -0,0 +1,9 @@
+# Stale Claims Register
+
+| Document Path | Quoted or Summarized Claim | Classification | Evidence | Recommended Correction |
+|---|---|---|---|---|
+| `docs/architecture/OVERVIEW.md` | `"TISC ISA" -> core/isa/; "VM Interpreter" -> core/vm/` | CONTRADICTED | `ls -d isa vm` shows these are at repo root, not under `core/`. | Update mapping instructions and paths in the table to use `isa/`, `vm/`, `include/t81/types/` etc. |
+| `docs/architecture/OVERVIEW.md` | `Data types -> core/types/` | CONTRADICTED | No `core/` or `types/` at root. Types are likely in `include/t81/types/` or `include/t81/data_types/` or `lang/`. | Check `include/` and adjust path to `include/t81/types/`. |
+| `docs/architecture/OVERVIEW.md` | `VM interpreter -> core/vm/` | CONTRADICTED | Actual path is `vm/`. | Change to `vm/`. |
+| `docs/architecture/OVERVIEW.md` | `CanonFS -> src/canonfs/ + include/t81/canonfs/` | CONTRADICTED | Actual path is `fs/` + `include/t81/canonfs/` | Change `src/canonfs/` to `fs/`. |
+| `scripts/governance/check_docs_structure.py` | `book/book-en` in BOOK_DIRS | STALE | Directory `book` is actually inside `docs/book` | Prefix with `docs/` |
@@ -0,0 +1,8 @@
+# Cross-Document Conflict Register
+
+| Documents Involved | Nature of Contradiction | Probable Authoritative Source | Recommended Resolution |
+|---|---|---|---|
+| `docs/architecture/OVERVIEW.md` vs Repo Directory Root (`isa/`, `vm/`, `fs/`) | The overview maps sub-systems to `core/isa/`, `core/vm/`, `src/canonfs/`, but the actual directory structure is flattened (`isa/`, `vm/`, `fs/`). | Repo Directory Root | Update `docs/architecture/OVERVIEW.md` to reflect flattened repository structure (`isa/`, `vm/`, `fs/`, `include/t81/types/`). |
+| `docs/ROADMAP.md` vs `docs/status/ROADMAP.md` | Duplicate roadmap documents. The `docs/status/` version is ~7x larger and likely the canonical tracking document, whereas `docs/ROADMAP.md` is shorter and likely an outdated summary or symlink that drifted. | `docs/status/ROADMAP.md` | Replace `docs/ROADMAP.md` with a direct relative link (markdown link or single-line redirect text) to `docs/status/ROADMAP.md`, or delete it completely if link hygiene allows. |
+| `docs/HANDOFF.md` vs Directory Structure | Mentions architecture subsystems but doesn't explicitly misname paths like `OVERVIEW.md`, but relies on `OVERVIEW.md` for exact paths. It also links to `docs/ROADMAP.md`. | Directory Structure | Fix `OVERVIEW.md` first. Update `docs/ROADMAP.md` links to `docs/status/ROADMAP.md`. |
+| `docs/BUILDABLE_NEXT_STEPS.md`, `docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md` | Outdated roadmap link. | Directory Structure | Update `docs/ROADMAP.md` links to `docs/status/ROADMAP.md`. |
@@ -0,0 +1,24 @@
+# Prioritized Remediation Plan
+
+## Priority 0: Critical Corrections Required Immediately
+
+1. **Target**: `docs/architecture/OVERVIEW.md`
+   - **Why**: Directly misleads contributors on codebase structure, breaking onboarding.
+   - **Action**: Update the "Architecture File Style Guide", "Current State by Layer", and "Evidence" sections. Change paths from `core/isa/` to `isa/`, `core/vm/` to `vm/`, `core/types/` to `include/t81/types/`, and `src/canonfs/` to `fs/`.
+   - **Evidence Required**: `ls -l isa/ vm/ fs/ include/t81/types/` confirms these directories exist at the root level.
+
+2. **Target**: `docs/ROADMAP.md`
+   - **Why**: Duplicate document causing split-brain confusion. The authoritative status roadmap is `docs/status/ROADMAP.md` (~21KB vs ~3KB).
+   - **Action**: Replace `docs/ROADMAP.md` with a stub pointing to `docs/status/ROADMAP.md` (or delete if link hygiene allows, but a stub prevents broken links).
+   - **Evidence Required**: `ls -l docs/ROADMAP.md docs/status/ROADMAP.md`
+
+3. **Target**: `scripts/governance/check_docs_structure.py`
+   - **Why**: Broken script causing CI/governance failures.
+   - **Action**: Fix the `BOOK_DIRS` array to point to `docs/book/book-*`.
+
+## Priority 1: Root Docs and Onboarding
+
+1. **Target**: `docs/HANDOFF.md`, `docs/BUILDABLE_NEXT_STEPS.md`, `docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md`
+   - **Why**: The entry points for serious contributors. Make sure they point to the correct paths and status documents.
+   - **Action**: Review references to architecture and status docs, ensure they align with the corrected paths from Priority 0 (`docs/status/ROADMAP.md`).
+   - **Evidence Required**: Run `check_active_docs_link_hygiene.py`.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -245,3 +245,5 @@ Estas ventajas se combinan en dominios donde la reproducibilidad, **la infer
		## Licencia

		Licencia Apache 2.0.

		> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -239,3 +239,5 @@ Apache 2.0

		Thanks for checking it out.
		Early feedback, issues, and contributors are very welcome.

		> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -245,3 +245,5 @@ Essas vantagens se combinam em domínios em que reprodutibilidade, **inferê
		## Licença

		Licença Apache 2.0.

		> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -245,3 +245,5 @@ ctest --test-dir build --output-on-failure
		## Лицензия

		Лицензия Apache 2.0.

		> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -245,3 +245,5 @@ IEEE 754 浮点数存在破坏可重复性的平台特定舍入模式、结合
		## 许可证

		Apache 许可证 2.0。

		> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md).