Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/BUILDABLE_NEXT_STEPS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion docs/HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
99 changes: 1 addition & 98 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
@@ -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.
10 changes: 5 additions & 5 deletions docs/architecture/OVERVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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 |
Original file line number Diff line number Diff line change
@@ -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/` |
Original file line number Diff line number Diff line change
@@ -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`. |
Original file line number Diff line number Diff line change
@@ -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
@@ -0,0 +1,102 @@
# T81 Architecture Overview
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Verbatim copy risks future drift from the live document

OUTPUT_F_UPDATED_DOCUMENTS/docs/architecture/OVERVIEW.md is a byte-for-byte snapshot of docs/architecture/OVERVIEW.md as committed in this PR. If docs/architecture/OVERVIEW.md is subsequently revised, the archived copy in this audit record will silently diverge and could mislead anyone using the audit folder as a historical reference.

Consider adding a brief header note to this file making it clear this is a point-in-time snapshot:

Suggested change
# T81 Architecture Overview
<!-- Audit snapshot captured at HEAD 0cb24d18 (2026-03-30). This file is a
read-only record; for the live version see docs/architecture/OVERVIEW.md. -->
# T81 Architecture Overview


Status: Active
Last Verified (UTC): 2026-02-26
Maturity: Mixed (`Frozen` core, `Experimental` periphery)

> **Architecture File Style Guide**
> - 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`.
> - Authority: `/spec` > `docs/architecture/OVERVIEW.md` > `/docs` > `/book`.

## Purpose

T81 is a ternary operating system for AI. This document is the canonical architecture snapshot of its implemented components, layer boundaries, and bounded determinism claim scope.

## Layer Cake

```mermaid
flowchart TD
L[T81Lang Frontend/Stdlib]
I[TISC ISA]
V[T81VM Interpreter]
A[Axion Policy Engine]
C[CanonFS]
X[Experimental: Cognitive Tiers + Hanoi Concepts]

L --> I --> V --> A --> C
X -. optional / non-DCP .-> V
X -. optional / non-DCP .-> A
```

Diagram source: [`diagrams/overview-layer-cake.mmd`](./diagrams/overview-layer-cake.mmd)

## Current State by Layer

| Layer | Primary code | Primary spec | Maturity | Notes |
| :--- | :--- | :--- | :--- | :--- |
| 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 | `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

T81 is a **ternary semantic architecture executed on binary hardware**. This is an intentional design choice, not a compromise. The platform implements native ternary semantics through a binary substrate compatibility layer:

- **2-Bit Packed Trits**: Trits are packed using 2 bits per trit (0=N, 1=Z, 2=P), allowing 4 trits per byte, naturally aligning with binary storage.
- **SWAR Vectorization**: Operations on these packed trits use SIMD Within A Register (SWAR) techniques, delivering extreme performance on modern x86 and ARM processors without sacrificing ternary correctness.

## Key Invariants

1. Determinism claims are bounded to verified surfaces in [`DETERMINISTIC_CORE_PROFILE.md`](../product/DETERMINISTIC_CORE_PROFILE.md) and [`DETERMINISM_SURFACE_REGISTRY.md`](../governance/DETERMINISM_SURFACE_REGISTRY.md).
2. VM execution is policy-aware: interpreter dispatch and trace paths call Axion verdict evaluation before protected effects.
3. Fault behavior is explicit trap semantics, not undefined behavior (`include/t81/vm/traps.hpp` + VM dispatch checks).
4. Dependency boundaries are governed by [`DEPENDENCY_FIREWALL.md`](./DEPENDENCY_FIREWALL.md).

## Execution Summary

```mermaid
sequenceDiagram
participant FE as Frontend
participant ISA as TISC Program
participant VM as Interpreter
participant AX as Axion
participant FS as CanonFS

FE->>ISA: deterministic bytecode emit
ISA->>VM: load_program()
VM->>AX: eval syscall context (step/opcode)
AX-->>VM: Allow/Warn/Deny + reason
VM->>FS: guarded persistence/read paths (when invoked)
VM-->>VM: trap or continue deterministically
```

Diagram source: [`diagrams/governance-axion-sequence.mmd`](./diagrams/governance-axion-sequence.mmd)

## Indeterminate

- Full JIT/interpreter semantic equivalence status is not asserted here.
- Universal cross-platform bit-identity for all floating-point transcendental behavior is not asserted here.

## Evidence

- [`vm/vm.cpp`](../../vm/vm.cpp)
- [`include/t81/vm/vm.hpp`](../../include/t81/vm/vm.hpp)
- [`include/t81/vm/state.hpp`](../../include/t81/vm/state.hpp)
- [`kernel/axion/policy_engine.cpp`](../../kernel/axion/policy_engine.cpp)
- [`fs/persistent_driver.cpp`](../../fs/persistent_driver.cpp)
- [`docs/product/DETERMINISTIC_CORE_PROFILE.md`](../product/DETERMINISTIC_CORE_PROFILE.md)
- [`docs/governance/DETERMINISM_SURFACE_REGISTRY.md`](../governance/DETERMINISM_SURFACE_REGISTRY.md)
- [`docs/status/IMPLEMENTATION_MATRIX.md`](../status/IMPLEMENTATION_MATRIX.md)

## Acceptance Criteria

- Every non-trivial claim maps to at least one item in **Evidence**.
- Implemented vs experimental surfaces are explicitly separated.
- Diagrams render in GitHub Markdown (Mermaid).
- Determinism statements are bounded to DCP/registry language.
Loading
Loading