Skip to content

DOC_STATUS.md

Latest commit

 

History

History
142 lines (113 loc) · 6.96 KB

DOC_STATUS.md

File metadata and controls

142 lines (113 loc) · 6.96 KB
Raw

Documentation status map

Generated by reconciling every tracked Markdown file against the tree on 2026-08-01.

Five months. 4,080 commits. The docs did not all keep up.

Some of these files describe the system as it is. Some are dated records of a run that happened once and will never happen again. Some are rendered from code and get overwritten on the next build. They all look the same in a file listing.

That's the problem this page solves. Reading a July soak verdict as current status, or a scoping proposal as an implemented design, is the mistake — and it's an easy one to make, because nothing on disk tells you which kind of document you opened.

A document's category tells you how to read it.

Category How to read it Count
Guide Describes the system as it is. Should be true today. 91
Historical A dated record of one run, audit, or session. Never updated to match the present — that would falsify the record. 36
Runbook Incident procedure, written against aura doctor --bundle fields. 29
Standard An evidence bar a claim must clear. Evergreen; changes only when the bar changes. 12
Generated Rendered from code. Do not hand-edit — regenerate. 4
Compliance Framework mappings (OWASP, NIST, MITRE ATLAS). 4
Claims What is and is not supported by evidence. 3

Start here

Document What it answers
../README.md What Aura is, how to run it, what the evidence boundary is
../HOW_IT_WORKS.md The same ideas without the math
../ARCHITECTURE.md The technical spec, §0–§18
../INSTALL.md Install, boot modes, environment variables
USER_GUIDE.md Using the app
OPERATOR_GUIDE.md Running it on your own hardware
../TESTING.md The test surface
../CLAIMS_NOT_SUPPORTED.md What is deliberately not claimed

Generated — regenerate, never hand-edit

Document Regenerate with Drift check
ARCHITECTURE_MAP.md make architecture-map —
FMEA.md make fmea-doc python tools/render_fmea.py --check
RUNTIME_CONTRACT.md make contract-doc python tools/render_health_contract.py --check
AURA_PROGRESS.md python tools/reqproof/progress.py —

All four were regenerated on 2026-08-01. The architecture map had drifted badly — it reported 148 subsystems and 2,204 Python files against an actual 154 and 2,597.

Historical — dated records, read as of their date

These are not wrong; they are true about the moment they describe. They are deliberately left as written.

Soak and certification runs SOAK_VERDICT_2026_07_15.md · SOAK_VERDICT_2026_07_18.md · SOAK_VERDICT_2026_07_25.md · CERT_2026_07_25_CLOSEOUT.md · VERIFY_2026_07_25.md · THIRD_PARTY_VALIDATION_2026_05_05.md

Session and pass records IMPROVEMENT_PASS_2026_07.md · SYSTEMS_MATURITY_2026_07_12.md · WHAT_IS_AURA_2026_07.md · AURA_EXECUTION_PLAN.md · AURA_PROMPT_COVERAGE_AUDIT.md

Evidence bundle — docs/evidence/ (11 files, July 2026)

Scoping proposals — scoping/ (9 files, April–July 2026). These propose designs. Several name modules that were never built (core/substrate/, core/autonomy/progress_tracker.py); that is what a proposal is, not a broken reference.

Benchmark results — aura_bench/results/, tests/*RESULTS.md

Known documentation debt

Recorded rather than quietly fixed, because each is a real statement about the repo:

  1. Nine spec documents named by an April mission prompt never existed — AGENTS.md, AURA_MASTER_SPEC.md, docs/RUNTIME_INVARIANTS.md, docs/PRODUCTION_HARDENING_PLAN.md, docs/SKILL_CERTIFICATION_MATRIX.md, docs/DEPTH_AUDIT.md, docs/ABUSE_GAUNTLET.md, docs/FORMAL_VERIFICATION_PLAN.md, and the second AURA_MASTER_SPEC.md. Git history contains no commit that added any of them. They are now annotated as such in AURA_EXECUTION_PLAN.md rather than left looking like links.
  2. docs/SELF_MODEL_MIRROR_EVIDENCE.md is absent by design — SM-12-LIVE-CERTIFICATION states it is issued only from real trial artifacts. Its absence is the honest state, not a gap.
  3. No published PGP key, despite SECURITY.md having pointed at security/pgp-public-key.asc for months. Corrected.
  4. ROADMAP.md grades predate the July–August work and should be re-scored before being quoted.

What was corrected on 2026-08-01

The factual errors found and fixed, for anyone who quoted the old numbers:

Was Is
"~7,400 tests" (CLAUDE.md) 24,931 collected across 1,771 files
"1013 passed" April snapshot (README) Replaced with the current count + chunk-runner instructions
148 subsystems / 2,204 files (arch map) 154 / 2,597
AURA_MEM_THRESHOLDS (OPERATOR_GUIDE) Does not exist; real vars are AURA_PROCESS_RSS_LIMIT_GB, AURA_MLX_MEMORY_LIMIT_GB, AURA_MLX_WORKER_RSS_LIMIT_GB, AURA_MLX_32B_LOAD_MIN_AVAILABLE_GB
AURA_HOST (INSTALL) Not read anywhere; bind address is the --host flag
"Gemini 3.5" (AI_SYSTEM_CARD) gemini-2.5-pro
"pinned with hashes in requirements/core.txt" (SECURITY) Hashes are in requirements_lock.txt (3,625 entries); core.txt has none
"SHA-256 checksum against MODEL_MANIFEST.json" (MODEL_CARD) No such file; identity is a fingerprint over config + index metadata + weight-file listing, explicitly not a weight hash
"Settings → Updates. Channels: stable/beta/dev" (USER_GUIDE) No channels; updates run through make update / update-live / rollback
8 runbook links using _ (KNOWN_FAILURE_MODES) Files use -; all 8 repaired
9 runbooks missing from the index Added
"aura status once available" in 18 runbooks Replaced with make release-status
research/timescale_stability.py (ARCHITECTURE) core/consciousness/timescale_stability.py
latent_cortex/*.py (RLC handoff) core/brain/llm/latent_cortex/*.py
core/executors/browser_executor.py executors/browser_executor.py

Maintaining this

Re-run the reference check before publishing docs:

make architecture-map
python tools/render_fmea.py --check
python tools/render_health_contract.py --check

When adding a document, put its category in a status line at the top. When a document records a run, put the date in its filename — that is what keeps it from being read as current a month later.