t81-foundation

Root Documentation Alignment Audit

Date: October 27, 2026
Inspected baseline: 391b9652502b2712e6838b132bc498e2c1f4f2ba (origin/main, README revision #598), including corrective PR #597.
Scope: repository entry points, all 44 tracked root files, directly related contributor adapters and maintenance documentation. This is a documentation audit, not an independent certification of architecture, performance, security, or historical reports.

1. Baseline and authority

The user’s active checkout was corrective/pr560-witness at 04154aee, with an earlier README. Work was isolated on docs/root-research-alignment from the main snapshot above, where the revised README was present. A GitHub commit API read during the audit independently confirmed that remote main still pointed to this SHA. No unseen README revision was reconstructed.

The complete English README, Master Continuity Charter, Research Charter, H01–H08 register, October 25 reassessment, consolidation ledger, and Investigations 01–08/corrective reports were inspected for the relevant claims. Each root file was read; generated Makefile/build-log content was inspected structurally and by source/claim searches, not treated as authored documentation or re-executed. Binary bytecode samples were inspected as bytes. The table below is the complete tracked root-file inventory, not a list of only changed files.

Normative specifications and accepted governance decisions remain requirements. Source and executable tests establish implementation behavior within their tested scope; they do not silently amend specifications. Reports establish historical reported findings; measurements require their actual inputs, environment, controls, and raw artifacts. Drafts, models, and proposed capabilities are not measured benefits. The Master Continuity Charter remains the continuity authority for canonical H01–H08, including Hanoi/CWEB history; Scientific Investigation numbers and H-S1 are separate identifiers. No charter, canonical register, frozen ISA, benchmark data, branch protections, or governance activation was modified.

2. Root file audit

Classification: A update required; B improvement recommended; C no change required; D historical or authoritative, preserve except explicit qualifications; E missing file assessed separately. Classification describes the inspected baseline. Actions may be a correction or an explicit deferral, not a claim that every listed file changed.

File	Classification	Finding	Proposed action / disposition	Evidence
.clang-format	C	C++ formatting configuration; no research claims.	Preserve.	E08
.clang-tidy	C	Static-analysis configuration; no certification claim.	Preserve.	E08
.cursorrules	A	Old stack framing, incomplete source map, historical code treated as reference oracle.	Align agent adapter and evidence requirements.	E01/E03
.editorconfig	C	Editor whitespace/encoding rules.	Preserve.	File contents
.gitattributes	C	Linguist presentation settings, not execution guarantees.	Preserve.	File contents
.gitignore	C	Build/cache exclusions; tracked artifacts remain tracked.	Preserve; no cleanup disguised as documentation.	E08
.gitmodules	C	Optional llama.cpp submodule declaration.	Preserve; no dependency upgrade.	E08
.pre-commit-config.yaml	C	mdformat 1.0.0 and text/JSON/YAML hygiene hooks.	Use configured Markdown formatter.	E08
AGENTS.md	A	Runtime-first identity omitted primary research continuity and explicit evidence standards.	Add charter/register and claim-boundary rules; retain operational lanes.	E01/E02
BALANCED_TERNARY_COMPARATIVE_RESEARCH.md	D	Investigation 05 includes broad historical closure claims.	Preserve body and results; read with Investigation 06 and corrective evidence.	E06
BUILD.bazel	C	Explicit placeholder naming CMake as authoritative.	Preserve; do not advertise Bazel support.	File contents
CMakeDoxyfile.in	C	Generated Doxygen substitution template.	Preserve; no behavioral defect identified.	E08
CMakeLists.txt	B	Actual target assembly; version 1.9.1 differs from Python metadata 1.9.2; declared CMake minimum 3.16.	Do not renumber releases or refactor; document discrepancy and validate configuration.	E08
CMakePresets.json	A	dev description hard-coded a 405-test inventory.	Remove count; keep generator, flags, and preset behavior unchanged.	E08
CODE_OF_CONDUCT.md	D	Contributor conduct and enforcement policy.	Preserve policy.	File contents
CONTRIBUTING.md	A	Missing experiment/negative-result submission standards; inaccurate src-only implementation map.	Add evidence requirements, actual source map, prerequisites, and separate research build.	E01/E03/E08
Dockerfile	B	Image description presented deterministic ternary computing without research context.	Change image description only; image build not reproduced.	E01/E08
EXACT_RATIONAL_CONVERSION_FEASIBILITY.md	D	Pinned Investigation 02, REVISE; governance blockers are historical evidence.	Preserve result and conditions.	E06
INDEPENDENT_RATIONAL_CONVERSION_VALIDATION.md	D	Investigation 04 validates an experimental prototype, explicitly leaves other hosts untested.	Preserve; do not promote to production proof.	E06
LICENSE	D	Apache-2.0 legal terms.	Preserve byte-for-byte.	File contents
Makefile	A	Tracked CMake-generated file embeds author-machine source/build paths.	Leave generated artifact unchanged; direct contributors to out-of-source CMake. Root removal requires separate layout review.	E08/E09
PROJECT_STRUCTURE.md	A	Customer-readiness framing and incomplete/inaccurate implementation guide.	Replace descriptive map with verified locations and historical-material boundaries.	E03/E08
README.es.md	A	Predates #598; stable/test-count/verified badges and broad integration claims.	Add localized outdated-translation qualification, remove unsupported badges, repair banner path; full translation deferred.	E01/E10
README.md	A	Research revision is present on baseline; stale source paths, correction chronology, and reused research build directory.	Preserve research identity; correct paths and #597 status, qualify remaining baseline/replay defects.	E01/E03/E04/E08
README.pt-BR.md	A	Predates #598; same technical staleness as Spanish.	Qualify historical translation, remove unsupported badges, repair banner; defer full translation.	E01/E10
README.ru.md	A	Predates #598; same technical staleness as Spanish.	Qualify historical translation, remove unsupported badges, repair banner; defer full translation.	E01/E10
README.zh-CN.md	A	Predates #598; same technical staleness as Spanish.	Qualify historical translation, remove unsupported badges, repair banner; defer full translation.	E01/E10
SECURITY.md	A	Overbroad compliance, signing, determinism, and complete-provenance language; generic support rule contradicted v0 table.	Scope claims to configured paths; distinguish identity/authentication/authorization/replay; retain reporting route and v1 maintenance policy.	E03/E05
SUPPORT_TAXONOMY.md	A	Directory-wide three-tier taxonomy conflicts with existing four-class surface register.	Refer to authoritative surface classes and current layout; do not change any surface assignment.	E07
SYSTEMS_AND_SUBSYSTEMS_REPORT.md	D	Dated report calls components production-ready.	Add dated historical qualification only; preserve original body.	E01/E07
T81_CAPABILITIES_REPORT.md	D	Dated RFC-derived report claims universal guarantees and production capability.	Add dated qualification: RFC presence is not implemented/tested behavior; preserve body.	E01/E07
TERNARY_COMPARATIVE_CLAIMS_AUDIT.md	D	Investigation 06 and its negative/corrective findings.	Preserve historical results, including unverified figures and scope limits.	E06
_config.yml	C	Jekyll exclusions; no research or support promise.	Preserve.	File contents
build.log	D	Tracked historical build transcript, not evidence of current validation.	Preserve; identify as historical/generated material.	E09
import.apl	D	Existing wildcard sample policy, not a production authorization recommendation.	Preserve; no policy semantics changed.	E03/E09
install.ps1	C	Windows x86-64 release downloader, not cross-platform conformance proof.	Preserve; installation not executed.	E05
install.sh	C	Linux/macOS release downloader for recognized CPU architectures.	Preserve; remote assets not installed or certified.	E05
pyproject.toml	A	Package summary implied general governed AI inference and bit-exact reproducibility.	Align description only; preserve package version, Python compatibility, and build settings.	E01/E08
record_hash.txt	D	Recorded object reference without a complete standalone evidence packet.	Preserve; do not present as current verification.	E09
symbolic_algebraic.tisc	D	Tracked binary sample bytecode.	Inspect bytes; preserve without re-executing or rewriting.	E09
symbolic_algebraic_exported.tisc	D	Tracked exported bytecode sample, byte-identical to companion at baseline.	Preserve; equality is not proof of execution correctness.	E09
test_input.txt	D	Existing input sample.	Preserve; no new research result inferred.	E09
test_record.json	D	Sample action record contains placeholder references.	Preserve; do not advertise as valid detached evidence.	E09
tiny-model-policy.apl	D	Policy pinned to a historical model hash.	Preserve; no new authorization claims.	E09

Missing root candidates (E): ROADMAP.md, CHANGELOG.md, and NOTICE are absent. No new root files are justified: the engineering roadmap exists at docs/ROADMAP.md, research continuity has its own changelog, and this audit establishes no new legal attribution requirement. Existing root-layout authority remains unchanged.

3. Related files and material inconsistencies

Related surface examined	Finding / correction
.github/copilot-instructions.md, .cursorrules	Align with root AGENTS, real source paths, evidence requirements, and preserved lineage; repair obsolete architecture references.
.github/PULL_REQUEST_TEMPLATE.md	Add research contribution type and reproducibility, controls, uncertainty, falsifier, and negative-result fields. The lowercase template spelling resolves to this same tracked file on this host; there is only one tracked PR template.
.github/ISSUE_TEMPLATE/bug_report.md, feature_request.md	Require exact commit/configuration and reproduced evidence; allow bounded hypothesis and negative-result submissions.
.github/ISSUE_TEMPLATE/rfc.md, spec_clarification.md, .github/instructions/spec.instructions.md, CODEOWNERS, RELEASE_TEMPLATE.md	Inspected; preserve normative-change/ownership processes. Existing malformed-looking RFC/clarification template frontmatter is a separate issue, not repaired here.
docs/HANDOFF.md, docs/ROADMAP.md, docs/BUILDABLE_NEXT_STEPS.md, docs/README.md	Identify runtime work as supporting maintenance; route scientific questions to the README and continuity records. No priority lane or scheduled research deliverable added.
docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md	Date and qualify the older runtime/product comparison; preserve its body as historical framing.
docs/process/policies/AGENTS.md	Mark old agent contract historical; root AGENTS supplies current guidance. Preserve original wording for traceability.
.github/workflows/ci.yml, python-wheels.yml, release.yml, remaining workflow definitions	Inspect validation entry points, publication metadata, and platform matrices. No workflow or permissions modified; definitions are not proof of successful runs.
docs/governance/, spec/, scripts, and examples referenced below	Resolve source paths and evidence boundaries; preserve normative classification, semantics, and experimental findings.

Principal corrections:

• The repository is a research platform; deterministic runtime engineering is an instrument and supporting track. No general ternary, integrated-system, or production-readiness advantage is assumed.
• The old three-tier directory taxonomy incorrectly made language tooling DCP and kernel code experimental wholesale. The root guide now points to the existing four-class surface register without assigning new status.
• Source roots differ from target-assembly directories: vm/vm.cpp, fs/, kernel/axion/, lang/frontend/, and tools/model/ are current implementation locations.
• PR #597 is already merged in the baseline. It corrected hardware harness controls and marked C–F unimplemented. Its conventional baseline still hard-codes three classifications and ignores model semantics; its policy ignores the required event and the fixture permits a wildcard. Config A times a process and a field read, not re-execution. Therefore the README retains an inconclusive comparative interpretation instead of importing the corrected report’s positive assurance verdict. These are source-inspection findings; this documentation pass did not rerun Investigation 08 timings.
• Security prose now distinguishes pre-operation authorization, content integrity, authentication, reproducibility, and independently enforced trust boundaries. The checked-in release workflow packages artifacts and requests an SBOM; it does not establish that all releases are cryptographically signed.
• The research runner selects Ninja and experiment-specific CMake options; it now uses build-research in entry-point instructions, avoiding reuse of a differently configured normal build. Prerequisites and offline Asio input are stated. A fixed test-count claim was removed from the dev preset description without changing configuration behavior.
• All four translations are explicitly marked outdated in their own language. Unsupported stable/test-count/verified badges are removed and banner paths repaired. Their remaining sections are historical text, not a claimed full translation of #598. Technical retranslation and historical-link cleanup remain follow-up work.

4. Evidence supporting corrections

• E01 — Research mission: English README, Master Continuity Charter, Research Charter, canonical register, and source-grounded lineage. The register/charters are preserved; they are continuity records, not independent scientific replication.
• E02 — Continuity and reported reassessment: October 25 reassessment and consolidation ledger. The reassessment includes broad historical wording and old source paths; it is not silently rewritten to match the README. Use the charter and pinned source to bound its interpretation.
• E03 — Implementation boundaries: task admission/execution, probe construction/execution, VM default engine, pre-dispatch check, storage driver contract, and read verification configuration. The task APL is checked before its probe; that does not prove it is passed into the probe’s instruction engine. CanonFS content identity is not truth or authenticated provenance.
• E04 — Investigations 07/08: corrective assessment, baseline computation and policy, timing boundaries, hard-coded dispositions, and hardware report. Reports and result data remain unchanged.
• E05 — Security/publication: threat model, release workflow, wheel workflow, and the existing disclosure route in SECURITY.md. Published assets, credentials, and branch protections were not altered or certified.
• E06 — Historical experiments: Investigation 01, Investigation 02, Investigation 04, Investigation 05, Investigation 06, and the Hanoi arithmetic evidence. Their claims are historical and scoped, including failures and untested hosts.
• E07 — Existing authority: RFC-0048, surface register, determinism registry, authority model, and multilingual policy. No normative artifact changed.
• E08 — Build/tooling: CMakeLists.txt, options, target assembly, research runner, presets, Python metadata, and pre-commit configuration. Python package compatibility is distinct from the Python version required by research tooling.
• E09 — Root artifact provenance: the tracked Makefile declares itself generated and embeds /Users/t81dev/Code/t81-foundation as both source/build root; root logs, sample policies, sample JSON/hash/input, and binary bytecode are not a new validation packet. Root removal/relocation requires a separate layout decision; none is performed.
• E10 — Translations: Spanish, Portuguese, Russian, and Chinese root READMEs still preserve the older runtime narrative. The English source revision is known; a corresponding full translation revision is not established. Notices do not invent a translation source SHA or reviewer identity.

5. Deliberately unchanged claims and artifacts

The Master Continuity Charter, Research Charter, hypothesis register, Hanoi source/evidence, normative ISA and surface classifications, research dispositions, raw benchmark data, and existing historical report bodies remain unchanged. The two root capability/system reports and the historical agent/profile documents receive qualifications only. Reported throughput and arithmetic figures in the English README remain explicitly reported results; this audit does not independently validate those timings. No new release numbers or native-hardware benefits are asserted. A lack of software speedup is not generalized to every possible ternary architecture.

6. Unresolved questions and excluded follow-up

• Complete technical translation of #598 and its corrections remains necessary for all four languages; historical sections and their old links are not promoted to current instructions.
• Root CMake version is 1.9.1 while Python package metadata is 1.9.2. Presets use schema version 3 although the root declares a CMake 3.16 minimum. The documented 3.25+ path is conservative; no release/version-policy change or downgrade support claim is made.
• The generated root Makefile, build log, bytecode samples, and placeholder records remain tracked because root layout is governed. Removing or relocating them is not part of this documentation PR.
• Historical governance/status documents contain pre-relocation paths and maturity wording. Their authoritative surface assignments are not amended through a root guide. A separate review must reconcile paths without silently promoting surfaces.
• Investigation 08 needs a model-interpreting conventional executor, equivalent authorization/evidence contracts, and matched timing boundaries. This audit neither implements that experiment nor treats its missing ablations as negative results.
• The existing architecture-target checker scans only root and benchmark CMake files. Nine of its ten reported targets are declared in src/**/CMakeLists.txt; the tenth, t81_python, is a stale name in the unchanged architecture table. The actual optional binding module is _t81 (CMakeLists.txt:1742). It fails unchanged on this baseline for both reasons. A separate follow-up must reconcile the stale name and expand the scan; this PR changes neither the checker nor its input table.
• Linux, Windows, x86-64 execution, remote CI, Docker image builds, published release assets, and wheel installation were not validated in this session. Platform matrices were inspected, not promoted to passing results. A linker warning about duplicate libt81_core.a occurs in the research build; tests still pass.

7. Validation results

Validation is performed on macOS 26.5.2 ARM64 with Apple Clang 21, Python 3.14.3, CMake 4.3.0, Ninja 1.13.2, and a pre-existing Asio source directory. Logs are local session artifacts; the commands below define the reproducible checks. Passing regressions are bounded checks, not independent reproduction of historical benchmark measurements.

Check	Result and scope
python3 scripts/ci/run_research_regressions.py --build-dir /tmp/t81-root-research-regressions --asio-source /Users/t81dev/Code/t81-foundation/build/_deps/asio-src --jobs 6	PASS: clean configure, eight named targets built, all eight research/contract CTests passed. Substitute a local Asio 1.30.2 checkout for the host-specific path.
cmake --list-presets	PASS: all seven configure presets parse; no claim that every preset was built.
python3 scripts/governance/check_root_structure.py	PASS: existing 81 top-level entries retained; no new root file.
python3 scripts/governance/check_active_docs_link_hygiene.py	PASS: active-surface legacy-path pattern check; this is not a full link crawler.
python3 scripts/ci/check_tisc_freeze_integrity.py	PASS: existing checker reports 209 opcode entries and its frozen-range checks; ISA files unchanged.
python3 scripts/ci/check_architecture_targets.py	FAIL, pre-existing on base and head: nine targets missed by the limited CMake scan plus stale documented t81_python (actual module _t81). Source, checker, and architecture table unchanged.
python3 docs/research/continuity/probes/verify_lineage.py --foundation-root <this-worktree> --hanoi-root <pinned-Hanoi-checkout> --lang-root <pinned-t81-lang-checkout>	PASS: selected historical byte identities checked with existing pinned local repositories.
python3 docs/research/continuity/probes/reproduce_hanoi_arithmetic.py --hanoi-root <pinned-Hanoi-checkout> --output-dir /tmp/t81-root-hanoi-probe	PASS for expected-counterexample collection: 422/547 addition failures, 140/201 multiplication failures, and 0/27 negation failures preserved. This does not mean the arithmetic candidate passed.
Protected artifact and root inventory comparison	PASS: all 44 root files classified; 81 root entries retained; charters, canonical register, LICENSE, conduct policy, CMakeLists, and protected specification/research/workflow subtrees unchanged.
Configured mdformat 1.0.0 with GFM/frontmatter/TOC extensions	PASS on 13 active/new Markdown files. Full changed-file check retains baseline formatting failures in ten historical/maintenance files; see exclusions below.
Local relative-link and image target validation	PASS: Markdown-it relative-link/image target scan across 28 root and changed Markdown files; zero missing targets and zero introduced missing targets. Fixed the old CI guidance and CLI driver links. External HTTP and heading anchors were not checked.
git diff --check	PASS: no whitespace errors in the final working diff.

Formatting uses mdformat==1.0.0 with mdformat-gfm, mdformat-frontmatter, and mdformat-toc, as configured. The full changed-file check was executed and is not a blanket pass. To avoid unrelated rewriting of historical bodies, existing formatting differences remain in README.es.md, README.pt-BR.md, README.ru.md, README.zh-CN.md, SYSTEMS_AND_SUBSYSTEMS_REPORT.md, T81_CAPABILITIES_REPORT.md, docs/BUILDABLE_NEXT_STEPS.md, docs/HANDOFF.md, docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md, and docs/process/policies/AGENTS.md. The same formatter finds each nonconformant at the unmodified baseline. Active/new documents were formatted and checked successfully. No historical mathematical result was changed to satisfy formatting.

The local link scan parses Markdown links/images and HTML src/href attributes, resolves repository-relative targets, and compares missing targets with the inspected baseline. It does not establish external URL availability or validate heading anchors. CI’s lychee HTTP crawl was not executed locally.

The ordinary full CTest suite, all build presets, external HTTP link crawling, and historical performance/hardware experiments were not run. No new benchmark or security outcome is inferred from this editorial change.

8. Final review correction

Review of initial PR head 218e24da193eba2efa7cf028bea28d4e359e9fce reproduced the architecture checker’s exit code 1 and identical output on base and head. Source inspection distinguished nine declarations outside the scan from the stale tenth name: module declaration, target table, and limited scan. Earlier wording that called all ten valid missed declarations was incorrect and is corrected above. No checker, target, or runtime behavior is changed. A fresh research configure/build in /tmp/t81-pr600-independent-build passed all eight selected CTests; the retained formatting exceptions were also reproduced individually on the base snapshot.

This site is open source. Improve this page.