Documentation audit and hygiene update

[t81dev]

Performed a comprehensive repository-wide documentation audit. Discovered structural drift in architecture documentation and roadmap duplication. Fixed the docs/architecture/OVERVIEW.md layer mappings, replaced docs/ROADMAP.md with a pointer to the authoritative docs/status/ROADMAP.md, updated all linking references, fixed a broken governance check script, and generated audit reports for historical tracking.

---

PR created automatically by Jules for task 10751069735718316809 started by @t81dev

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[greptile-apps]

Greptile Summary

This PR performs a repository-wide documentation hygiene pass: it corrects stale directory path mappings in docs/architecture/OVERVIEW.md (reflecting the flattened core/ → root structure), consolidates the duplicate roadmap by replacing docs/ROADMAP.md with a redirect stub pointing to the authoritative docs/status/ROADMAP.md, updates all downstream link references, fixes a broken governance script (check_docs_structure.py), and adds a structured set of audit records under docs/records/audits/2026-03_documentation_refresh/ for historical traceability.

Key changes:

• docs/architecture/OVERVIEW.md: path mappings corrected (core/isa/ → isa/, core/vm/ → vm/, core/types/ → include/t81/types/, src/canonfs/ → fs/) — directly aligned with the actual repository layout.
• docs/ROADMAP.md: reduced to a one-line redirect stub; the 100-line body is now exclusively in docs/status/ROADMAP.md, eliminating split-brain confusion.
• docs/HANDOFF.md, docs/BUILDABLE_NEXT_STEPS.md, docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md: roadmap links updated to point directly to docs/status/ROADMAP.md.
• scripts/governance/check_docs_structure.py: BOOK_DIRS corrected from book/book-* to docs/book/book-*, matching the actual directory layout.
• One missed update: The root AGENTS.md "Read This First" section still references docs/ROADMAP.md (now a stub) rather than docs/status/ROADMAP.md directly — the only cross-doc reference the PR did not update.
• The OUTPUT_F_UPDATED_DOCUMENTS snapshot is a verbatim copy of the updated OVERVIEW.md without a timestamp/snapshot disclaimer, which could cause confusion if the live file evolves.

Confidence Score: 5/5

Safe to merge — all changes are documentation and a non-breaking script path fix; no production code is touched.

Every substantive fix (stale paths, duplicate roadmap, broken governance script, cross-doc links) is correct and well-evidenced by the accompanying audit records. The two remaining notes are both P2 style items: AGENTS.md still points to the working stub (which redirects correctly), and the OUTPUT_F snapshot lacks a disclaimer. Neither blocks functionality or onboarding.

Root AGENTS.md line 24 (roadmap link not updated); OUTPUT_F_UPDATED_DOCUMENTS/docs/architecture/OVERVIEW.md (missing snapshot disclaimer).

Important Files Changed

Filename	Overview
scripts/governance/check_docs_structure.py	Corrects BOOK_DIRS from book/book-* to docs/book/book-*; the target directories exist and the script logic is otherwise unchanged and correct.
docs/architecture/OVERVIEW.md	Updates stale path mappings (core/isa/ → isa/, core/vm/ → vm/, core/types/ → include/t81/types/, src/canonfs/ → fs/) to reflect the flattened repository structure; well-supported by audit evidence.
docs/ROADMAP.md	Replaces the 100-line duplicate roadmap with a one-line redirect stub pointing to the authoritative docs/status/ROADMAP.md; preserves backward link compatibility.
docs/HANDOFF.md	Single-line link update from docs/ROADMAP.md to docs/status/ROADMAP.md; correct and consistent with the rest of the PR.
docs/BUILDABLE_NEXT_STEPS.md	Single-line link update from docs/ROADMAP.md to docs/status/ROADMAP.md; correct.
docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md	Single-line inline reference updated from docs/ROADMAP.md to docs/status/ROADMAP.md; correct.
docs/records/audits/2026-03_documentation_refresh/OUTPUT_F_UPDATED_DOCUMENTS/docs/architecture/OVERVIEW.md	Verbatim snapshot of the updated docs/architecture/OVERVIEW.md stored as an audit artifact; functionally correct, but lacks a header indicating this is a point-in-time snapshot, which could cause confusion if the live file diverges later.
docs/records/audits/2026-03_documentation_refresh/OUTPUT_A_EXECUTIVE_SUMMARY.md	New audit record: executive summary identifying stale architecture paths, roadmap duplication, and governance script mismatch — all of which are addressed in this PR.
docs/records/audits/2026-03_documentation_refresh/OUTPUT_E_PRIORITIZED_REMEDIATION_PLAN.md	New audit record: prioritized remediation plan that maps directly to the changes made in this PR; serves as a traceable audit trail for the decisions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Before
        A1[AGENTS.md] -->|links to| R1[docs/ROADMAP.md\n100-line duplicate]
        H1[docs/HANDOFF.md] -->|links to| R1
        B1[docs/BUILDABLE_NEXT_STEPS.md] -->|links to| R1
        P1[T81_FOUNDATION_PROJECT_PROFILE.md] -->|links to| R1
        R1 -.- RS1[docs/status/ROADMAP.md\nauthoritative]
        OV1[docs/architecture/OVERVIEW.md] -->|stale paths| C1["core/isa/, core/vm/\nsrc/canonfs/"]
        SC1[check_docs_structure.py] -->|wrong path| BK1["book/book-en"]
    end
    subgraph After
        A2[AGENTS.md] -->|still links to| R2[docs/ROADMAP.md\nredirect stub]
        H2[docs/HANDOFF.md] -->|links to| RS2[docs/status/ROADMAP.md]
        B2[docs/BUILDABLE_NEXT_STEPS.md] -->|links to| RS2
        P2[T81_FOUNDATION_PROJECT_PROFILE.md] -->|links to| RS2
        R2 -->|redirects to| RS2
        OV2[docs/architecture/OVERVIEW.md] -->|correct paths| C2["isa/, vm/, fs/\ninclude/t81/types/"]
        SC2[check_docs_structure.py] -->|correct path| BK2["docs/book/book-en"]
    end
    style R2 fill:#ffe066,stroke:#cc9900
    style A2 fill:#ffe066,stroke:#cc9900

Loading

Comments Outside Diff (1)

1. AGENTS.md, line 24 (link)

   docs/ROADMAP.md reference not updated in AGENTS.md

   The PR updates the roadmap link in docs/HANDOFF.md, docs/BUILDABLE_NEXT_STEPS.md, and docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md, but leaves the root AGENTS.md pointing to the old docs/ROADMAP.md. Since AGENTS.md is the primary onboarding guide for AI agents, it should consistently point directly to the authoritative location rather than relying on the stub's redirect.

_{Reviews (1): Last reviewed commit: "docs: documentation audit and refresh" | Re-trigger Greptile}

[greptile-apps]

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