70 KiB
70 KiB
docs/INDEX.md — Documentation Triage
Phase 1 triage: 2026-06-16 · Phase 2 reorg: 2026-06-16 · Phase 3 stubs: 2026-06-16
Total files inventoried: 328
Status tags: CURRENT · WORKING · HISTORICAL · SUPERSEDED · OBSOLETE · DELETE
Status Key
| Tag | Meaning |
|---|---|
| CURRENT | Accurate and up-to-date; reflects present architecture |
| WORKING | Active draft or living document; still being edited |
| HISTORICAL | Accurate for its time; kept as a record |
| SUPERSEDED | Replaced by a specific newer document |
| OBSOLETE | Describes architecture or processes that no longer exist |
| DELETE | No value (empty, duplicate, pure noise) |
Full File Index
| Path | Topic | Status | Notes |
|---|---|---|---|
| ./.claude/CLAUDE.md | Authoritative architecture/status reference | CURRENT | Self-declared authoritative reference; internally consistent (v3.0.3, LithosAnanke v1.0.8, ACL phases 1-6 done/7-8 pending); used as ground truth for this audit. |
| ./CODE_OF_CONDUCT.md | Community conduct standards | CURRENT | Standard Contributor Covenant boilerplate, not version/architecture-dependent. |
| ./CONTRIBUTING.md | Contribution guidelines, build/test workflow | WORKING | References "780+ tests" and points to docs/CLAUDE.md as project overview, while authoritative CLAUDE.md cites 936+ tests and itself (.claude/CLAUDE.md) as authoritative — minor staleness, but actively-useful living doc. |
| ./NOTICE.md | License attribution notice | CURRENT | Static legal/attribution text tied to Starship License 1.0, consistent with CLAUDE.md license section. |
| ./ONTOLOGY.md | Formal taxonomy/thermodynamic lexicon | CURRENT | Dated 2025-12-13; explicitly referenced as canonical lexicon by CLAUDE.md and README; conceptual framework, not version-dependent. |
| ./README.md | Project overview/quick start | SUPERSEDED | Cites release tag v1.5.0-RELEASE, "800+ test suite", "21 theory files" vs CLAUDE.md's current v3.0.3, 936+ tests, 24 theory files — predates several version bumps; superseded by .claude/CLAUDE.md. |
| ./ROADMAP.md | VM→Kernel→OS→FPGA phased roadmap | SUPERSEDED | Dated 2025-12-14, describes StarKernel/HAL as not yet begun, but CLAUDE.md shows LithosAnanke v1.0.8 with M0–M6 complete and M7 in progress — overtaken by progress; CLAUDE.md's embedded roadmap summary is now current. |
| docs/working/experiments/campaigns/doe_2x7/README.md | 2^7 factorial DoE methodology guide | CURRENT | Reusable how-to-run guide for the DoE experiment class, not tied to one run; matches current 7-loop architecture. |
| docs/working/experiments/campaigns/l8_attractor_map/SESSION_REPORT_2025-12-10.md | Narrative session report on L8 attractor debugging | HISTORICAL | Dated first-person account of one specific debugging/analysis session; accurate record of its time. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/TIDBITS.md | Informal findings notes from L8 attractor analysis | HISTORICAL | Informal commentary tied to one specific dataset/run (2025-12-09); a snapshot artifact. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/comprehensive_report.md | Statistical report on L8 heartbeat across 180 runs | HISTORICAL | Dated analysis report of one specific experiment run's results. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/comprehensive_report.md.pdf | Rendered PDF of comprehensive_report.md | HISTORICAL | Rendered artifact of the same dated run's report; same status as its .md source. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/heartbeat_analysis.md | Heartbeat statistical analysis (ANOVA, workload effects) | HISTORICAL | Dated 2025-12-09, tied to this specific 180-run dataset; a results record. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/mathematical_framework.md | Oscillator-inspired equations fit to heartbeat data | HISTORICAL | Speculative modeling derived from this one dataset's measured frequencies; dated analysis artifact. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/mathematical_framework.md.pdf | Rendered PDF of mathematical_framework.md | HISTORICAL | Rendered artifact of the same dated analysis. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/tables/NOTES.md | Notes accompanying generated data tables | HISTORICAL | Supporting notes for one run's generated tables; tied to that dated results directory. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/tables/anova_results.txt | Raw ANOVA output (tick count/duration vs workload) | HISTORICAL | Raw statistical output specific to the 2025-12-09 run. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/binary_2cycle_analysis_report.md | Binary 2-cycle clustering analysis of heartbeat phase space | HISTORICAL | Dated (2025-12-11) follow-on analysis of the same 180-run dataset. |
| docs/working/experiments/campaigns/l8_attractor_map/run_log.txt | Raw execution log of L8 attractor experiment run | HISTORICAL | Raw run transcript referencing a specific results directory; record of one execution session. |
| docs/working/experiments/campaigns/l8_validation/EXPERIMENT_SUMMARY.txt | L8 Jacquard validation experiment design summary | HISTORICAL | Fixed summary of one validation campaign ("IMPLEMENTED: 2025-11-26"), not a reusable guide (README fills that role). |
| docs/working/experiments/campaigns/l8_validation/README.md | L8 Jacquard validation methodology guide | CURRENT | Reusable how-to/experimental-design guide for re-running this class of experiment; matches current L8 Jacquard architecture. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_20251208_102205/conditions_randomized.txt | Randomized condition matrix for one validation run | HISTORICAL | Raw generated condition list timestamped 2025-12-08; specific run's input data. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_20251208_102205/conditions_raw.txt | Unrandomized condition matrix for one validation run | HISTORICAL | Companion raw matrix for the same dated run. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_30reps_20251126_135128/conditions_randomized.txt | Randomized condition matrix, 30-rep run | HISTORICAL | Dated 2025-11-26 run's input matrix; an earlier run in the same family. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_30reps_20251126_135128/conditions_raw.txt | Unrandomized condition matrix, 30-rep run | HISTORICAL | Companion raw matrix for the same 2025-11-26 run. |
| docs/working/experiments/campaigns/shape_validation/README.md | Workload shape validation methodology guide | CURRENT | Reusable quick-start guide for re-running the shape-validation experiment class; architecture-consistent with CLAUDE.md. |
| docs/working/experiments/campaigns/shape_validation/shape_RAJ_run_20251127_093208/conditions_randomized.txt | Randomized condition matrix for one shape-validation run | HISTORICAL | Specific dated (2025-11-27) run's randomized input data. |
| docs/working/experiments/campaigns/shape_validation/shape_RAJ_run_20251127_093208/conditions_raw.txt | Unrandomized condition matrix for one shape-validation run | HISTORICAL | Companion raw matrix for the same 2025-11-27 run. |
| docs/working/experiments/campaigns/shape_validation/shape_run_20251123_083147/conditions_randomized.txt | Randomized condition matrix, earlier shape-validation run | HISTORICAL | Dated 2025-11-23, earlier run in same family. |
| docs/working/experiments/campaigns/shape_validation/shape_run_20251123_083147/conditions_raw.txt | Unrandomized condition matrix, earlier shape-validation run | HISTORICAL | Companion raw matrix for the 2025-11-23 run. |
| docs/working/experiments/campaigns/window_scaling/QUICK_START.md | Window-scaling (James Law) experiment quick-start steps | CURRENT | Reusable step-by-step workflow for re-running the experiment; procedural, not tied to a single completed run. |
| docs/working/experiments/campaigns/window_scaling/README.md | Window-scaling experiment design / James Law hypothesis | CURRENT | Reusable experimental-design overview (hypothesis, expected outcomes) for the experiment class. |
| docs/working/papers/published/James_Steady-State_Convergence_Adaptive_Runtime.pdf | Published SSRN academic paper | CURRENT | Confirmed present; explicitly named as the published SSRN paper in CLAUDE.md; a citable finished artifact. |
| ./scripts/SCRIPT_REPAIR_LOG.md | Bug-fix log for run_ablation_study.sh | HISTORICAL | Documents specific fixes made 2025-11-20 to a script that still exists; valuable as a record but not living guidance. |
| docs/working/papers/ACADEMIC_WORDING_GUIDELINES.md | Academic language rules for physics-metaphor claims | CURRENT | Active style guide for SSRN paper and derivatives; referenced by authors/contributors. |
| docs/working/scratch/AGENTS.md | Repo structure and contribution rules for AI/human contributors | CURRENT | Accurate description of build, test, naming, and PR conventions; matches current codebase layout. |
| docs/working/scratch/AI_AGENT_MANDATORY_README.md | Mandatory AI-agent pre-read for physics runtime changes | CURRENT | Governance document; rules are evergreen; references live subsystem names. |
| docs/working/papers/ANTI_CLAIMS.md | Explicit boundary statements for SSRN/peer-review defensibility | CURRENT | Directly supports published SSRN paper; no code references that have drifted. |
| ./docs/CLAUDE.md | Docs-root instructions for Claude Code; two-tier doc model plan | WORKING | Describes a docs/formal/ + docs/working/ restructure not yet executed; active planning doc, not authoritative state ref (.claude/CLAUDE.md is). |
| docs/working/archive/COMPUTATIONAL_PHYSICS_FRAMEWORK.md | Expansive "physics of computation" claims framework | HISTORICAL | Contains strong over-claims ("This is not metaphor") that contradict ANTI_CLAIMS.md and ACADEMIC_WORDING_GUIDELINES.md; dates from earlier draft thinking (2025-12-10). |
| ./docs/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word format) | WORKING | Active proposal document; companion to the PDF version. |
| ./docs/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF) | WORKING | Active funding proposal; filename indicates a working/submission-ready draft. |
| docs/working/archive/DOCUMENTATION_AUDIT.md | Docs audit from 2025-12-14; gap/inconsistency findings | HISTORICAL | Audit from a past triage pass; most findings have since changed; useful historical record. |
| docs/working/papers/EXECUTIVE_SUMMARY.md | Plain-English summary of StarForth results for non-specialists | CURRENT | Accurate, well-calibrated summary with correct metaphor framing; audience: journalists, admins, reviewers. |
| docs/working/papers/FINAL_REPORT/appendix_glossary.adoc | AsciiDoc glossary appendix for multi-chapter report | CURRENT | Formal, math-precise definitions consistent with current ontology; intended for book/report compilation. |
| docs/working/papers/FORMAL_CLAIM_TABLE.md | Structured claim–evidence–reproducibility table for peer review | CURRENT | Core scientific accountability doc; tied to SSRN paper claims; still valid. |
| docs/working/archive/GAP_ANALYSIS.md | Gap analysis: StarForth → StarKernel → StarshipOS → FPGA | SUPERSEDED | Written when StarKernel had "zero implementation"; LithosAnanke v1.0.8 has M0-M6 complete — the kernel gaps section is stale. |
| docs/working/papers/NEGATIVE_RESULTS.md | Documented failure modes and limitations | CURRENT | Honest failure-mode catalog; still accurate and academically valuable. |
| docs/working/papers/NULL_HYPOTHESIS.md | Formal null hypothesis and falsification criteria | CURRENT | Rigorous statistical framing for SSRN claims; no stale references. |
| docs/working/papers/ONTOLOGY.md | Master ontology/taxonomy/lexicon for adaptive runtime concepts | CURRENT | Authoritative term definitions; referenced by root ONTOLOGY.md and docs/README.md; actively used. |
| docs/working/papers/ONTOLOGY_README.md | Index/guide to ontology file set (md, tex, adoc) | CURRENT | Accurate pointer document for ontology artifacts; still valid. |
| ./docs/README.md | Top-level docs directory README and navigation | WORKING | Navigation is broadly accurate but mentions HAL migration as "current active work" which is further along now. |
| docs/working/papers/REPLICATION_INVITE.md | Formal open invitation to independent replication | CURRENT | Evergreen scientific openness statement; expected output values still match claimed results. |
| docs/working/papers/REPRODUCIBILITY.md | One-command reproduction protocol with exact expected output | CURRENT | References valid build commands and --doe flag; expected output values consistent with published claims. |
| docs/working/papers/SCIENTIFIC_DEFENSE_CHECKLIST.md | Checklist of attack vectors and defenses for peer review | WORKING | Many "missing defenses" (GPG signing, Zenodo DOI, R/Python scripts) not yet addressed; still actively relevant. |
| docs/working/papers/SENSITIVITY_ANALYSIS.md | Parameter sweep design: robustness of 0% CV claim | CURRENT | Documents planned sensitivity experiments; scientifically sound framing; supports SSRN defensibility. |
| ./docs/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, FINAL) | WORKING | "FINAL" in name suggests submission-ready; likely supersedes DARPA_SSM_Proposal_James.docx but keep both until confirmed. |
| docs/working/papers/SSRN_companion/Math_Companion_SSRN.pdf | Compiled PDF of math companion to SSRN paper | CURRENT | Rendered output of the .tex source; companion to the published SSRN paper. |
| docs/working/papers/SSRN_companion/Math_Companion_SSRN.tex | LaTeX source for math companion document | CURRENT | Source of record for comprehensive math/engineering structures reference; cross-references implementation. |
| docs/working/papers/SSRN_companion/figures/fig1_snake_trajectory.pdf | Figure asset: snake/phase trajectory | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig2_K_vs_window.pdf | Figure asset: K vs window width | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig3_FFT_spectrum.pdf | Figure asset: FFT spectrum | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig4_golden_ratio_penalties.pdf | Figure asset: golden ratio penalties | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig5_bimodal_distributions.pdf | Figure asset: bimodal distributions | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig6_performance_vs_k.pdf | Figure asset: performance vs K | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig7_performance_by_regime.pdf | Figure asset: performance by regime | CURRENT | Figure asset for the SSRN math companion. |
| ./docs/SYSTEM_NARRATIVE.pdf | Compiled PDF of system narrative | CURRENT | Rendered output of SYSTEM_NARRATIVE.tex; technical story for patent counsel and reviewers. |
| ./docs/SYSTEM_NARRATIVE.tex | LaTeX source: technical narrative for patent/research review | CURRENT | Well-framed, correctly calibrated narrative; accurate description of the adaptive runtime and 90-run experiment. |
| docs/working/scratch/TASK_LIST.md | AI/human task list with working rules and incremental tasks | WORKING | All tasks are unchecked; likely predates recent physics work; rules section is evergreen but specific tasks may be stale or partially done. |
| docs/working/archive/artifacts/kanban-workflow/MANIFEST.adoc | Artifact manifest for kanban workflow validation scripts | HISTORICAL | Tracks process-tooling artifacts from a past workflow setup session; no ongoing relevance to VM or kernel. |
| docs/working/scratch/assets/README.md | Binary assets holding area README | WORKING | Correctly flags book-FIXED.docx etc. as misplaced; the guidance (move to LFS/external) is still actionable. |
| docs/working/scratch/assets/book-FIXED.docx | Book/report Word document | WORKING | Binary asset misplaced in docs/assets; should move to LFS per assets/README.md guidance. |
| docs/working/architecture/heartbeat_csv_export.md | Heartbeat CSV export design: format, columns, TODO status | WORKING | Several columns marked ⚠️ TODO; matches CLAUDE.md note that heartbeat_export_csv() is not yet implemented; active design/tracking doc. |
| ./docs/ontology.pdf | Compiled PDF of ontology.tex |
CURRENT | Rendered output of ontology.tex; self-contained reference for academic inclusion. |
| ./docs/ontology.tex | LaTeX source for formal ontology | CURRENT | Source of record matching ONTOLOGY.md content; used for journal/conference paper inclusion. |
| docs/working/archive/prog-prove.pdf | Unknown — likely Isabelle/HOL or proof-assistant tutorial PDF | HISTORICAL | Filename suggests a proof-programming reference; not authored by this project; reference material only. |
| docs/working/architecture/getting-started/DEVELOPER.md | Dev environment setup, Isabelle install | CURRENT | Generic setup instructions still match current build system. |
| docs/working/architecture/getting-started/README.md | Getting-started index/TOC | CURRENT | Navigation page; links resolve to existing files. |
| docs/working/architecture/getting-started/quick-start/factorial-doe.md | Quick-start for 2^6 per-loop factorial DoE | OBSOLETE | Describes retired ENABLE_LOOP_1..6 compile-time toggles; replaced by L8 Jacquard runtime mode selector. Hardcoded /home/rajames/... paths. |
| docs/working/architecture/getting-started/quick-start/heartbeat-doe.md | Quick-start for heartbeat DoE run | HISTORICAL | Dated 2025-11-20, references a specific completed run directory and hardcoded user paths. |
| docs/working/architecture/getting-started/quick-start/optimization-doe.md | Quick-start for 5-opportunity optimization DoE | HISTORICAL | References dated result dirs from a completed tuning campaign; superseded conceptually by L8's data-driven design. |
| docs/working/experiments/02-experiments/L8_WIRING_CODE_REVIEW_GUIDE.md | Code review guide for L8 wiring (L2/L3/L5/L6) | HISTORICAL | Dated 2025-12-05; matches current physics_metadata.c — completed, accurate review record. |
| docs/working/experiments/02-experiments/L8_WIRING_IMPLEMENTATION_SUMMARY.md | Summary of L8 gating implementation | HISTORICAL | Dated 2025-12-05, marked complete; verified consistent with current source. |
| docs/working/experiments/02-experiments/L8_WIRING_PLAN.md | Plan for wiring loops to L8 mode selector | SUPERSEDED | Superseded by L8_WIRING_IMPLEMENTATION_SUMMARY.md and L8_WIRING_CODE_REVIEW_GUIDE.md (plan was executed and reviewed). |
| docs/working/experiments/02-experiments/README.md | Experiments directory index | CURRENT | Accurately lists existing subdirectories. |
| docs/working/experiments/02-experiments/factorial-doe/guide.md | Full 2^6 factorial DoE guide | OBSOLETE | Describes retired per-loop Makefile-toggle architecture, replaced by L8 Jacquard. |
| docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md | Handling incompatible factorial loop configs | OBSOLETE | Build-time incompatibility handling for the retired 2^6 toggle experiment. |
| docs/working/experiments/02-experiments/factorial-doe/index.md | Index for factorial DoE docs | OBSOLETE | Points to stale doc paths; describes retired architecture. |
| docs/working/experiments/02-experiments/factorial-doe/workflow.md | Factorial DoE data pipeline workflow | HISTORICAL | Documents completed 2025-11-19 factorial campaign that produced data behind current L8 design; toggle architecture retired. |
| docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md | Heartbeat DoE corrected metric design | SUPERSEDED | Superseded by phase2-corrected.md ("corrected and finalized" version). |
| docs/working/experiments/02-experiments/heartbeat-doe/design.md | Original Phase 2 heartbeat DoE design | SUPERSEDED | Pre-correction draft; superseded by corrected-design.md / phase2-corrected.md. |
| docs/working/experiments/02-experiments/heartbeat-doe/execution-guide.md | How to run Phase 2 heartbeat DoE | HISTORICAL | Dated 2025-11-20, hardcoded stale path; describes running the now-superseded design. |
| docs/working/experiments/02-experiments/heartbeat-doe/implementation-summary.md | Deliverables summary for heartbeat DoE | HISTORICAL | Point-in-time "complete" status snapshot dated 2025-11-20 for pre-correction design. |
| docs/working/experiments/02-experiments/heartbeat-doe/phase2-corrected.md | Final corrected heartbeat DoE design | WORKING | Latest version in the revision chain; still describes not-yet-fully-implemented work. |
| docs/working/experiments/02-experiments/james-law/protocol.md | SSM gravitational-collapse threshold hypothesis/protocol | WORKING | Forward-looking theoretical experiment protocol, no completion markers. |
| docs/working/experiments/02-experiments/physics-optimization/doe-guide.md | Guide for 5-opportunity progressive optimization DoE | CURRENT | Generic script-driven methodology still consistent with current physics engine. |
| docs/working/experiments/02-experiments/physics-optimization/execution-guide.md | Guide for 90-run comprehensive physics validation | CURRENT | Underlies the "0% variance across 90 runs" claim in CLAUDE.md. |
| docs/working/experiments/02-experiments/physics-optimization/hotwords-cache.md | Hot-words cache experiment results (1.78x speedup) | HISTORICAL | Completed-experiment results report with fixed numbers. |
| docs/working/experiments/02-experiments/physics-optimization/proposals.md | 9 proposed future optimization opportunities | WORKING | Living forward-looking proposal doc built on hotwords-cache result. |
| docs/working/experiments/02-experiments/physics-optimization/reproduce.md | Reproduction recipe for hotwords-cache result | CURRENT | Narrow, still-valid step-by-step reproduction guide. |
| docs/working/architecture/03-architecture/OVERVIEW.md | Top-level architecture overview (3-layer model, physics loops, boot sequence) | WORKING | Header says "Status: Complete, 2025-12-14" but roadmap still frames StarKernel as "PLANNED"/HAL migration "IN PROGRESS," lagging CLAUDE.md's actual M0-M6-done/M7-in-progress state; needs a refresh pass. |
| docs/working/architecture/03-architecture/README.md | Directory index/landing page for 03-architecture/ | WORKING | Shorter duplicate of OVERVIEW.md's roadmap; same staleness (treats StarKernel as not-yet-started); functions as nav index, content needs sync with CLAUDE.md. |
| docs/working/architecture/03-architecture/adaptive-systems/adaptive-window-and-decay.md | Root-cause investigation: rolling-window shrink + decay_slope placeholder bugs | HISTORICAL | Dated 2025-11-08, "Root Cause Analysis Complete." Diagnostic/incident report; trigger doc for window-inference-redesign.md. |
| docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md | Alternate Loop #5 proposal: prefetch-accuracy-driven binary-chop window tuning | SUPERSEDED | Superseded by window-inference-redesign.md. Undated draft ending in an open question to the user (never approved); the shipped Loop #5 uses Levene's test, not this mechanism. |
| docs/working/architecture/03-architecture/adaptive-systems/multivariate-dynamics.md | Phase 2 DoE experiment design: multivariate stability fingerprinting across 7 metrics | WORKING | Dated 2025-11-20, "Status: Design Phase." Forward-looking proposal tied to still-unimplemented heartbeat instrumentation. |
| docs/working/architecture/03-architecture/adaptive-systems/window-inference-redesign.md | Redesign of window-width inference using Levene's test on disjoint chunks | CURRENT | Dated 2025-11-19, "DESIGN (approved for implementation)." Matches the Loop #5/#6 mechanism CLAUDE.md/OVERVIEW.md describe as actually implemented (inference_engine.c). |
| docs/working/architecture/03-architecture/hal/README.md | Index/reading-order guide for HAL doc set | WORKING | Status table claims all 5 HAL docs "Complete, 2025-12-14," but describes target architecture per overview.md's own disclaimer, not built code; misleading without that caveat. |
| docs/working/architecture/03-architecture/hal/interfaces.md | hal_* C interface contract spec (time, interrupt, memory, console, cpu, panic) | WORKING | Normative target API design; current codebase uses sf_time_backend_t-style naming per overview.md — this HAL layer is not yet built as specified. |
| docs/working/architecture/03-architecture/hal/migration-plan.md | 7-phase plan to migrate codebase to hal_* interfaces | WORKING | Forward plan ("Phase 2 IN PROGRESS" per roadmap); CLAUDE.md's current source tree shows this migration not yet executed. |
| docs/working/architecture/03-architecture/hal/overview.md | HAL rationale/design-principles doc | WORKING | Contains the key disclaimer: "current codebase uses sf_time_backend_t... different naming" — explicitly flags the whole HAL doc family as target/aspirational, not current. |
| docs/working/architecture/03-architecture/hal/platform-implementations.md | Example hal_* implementations for Linux and kernel platforms | OBSOLETE | Assumes src/platform//hal_*.c layout; actual built StarKernel tree (per CLAUDE.md) uses src/starkernel/{arch,boot,capsule,hal,memory,...} — a different, already-implemented structure. |
| docs/working/architecture/03-architecture/hal/starkernel-integration.md | Kernel HAL integration guide, src/platform/kernel/ layout, milestone roadmap to "ok" prompt | OBSOLETE | Describes Milestone 1 "Boot + Serial Output" as a starting point; LithosAnanke is actually at v1.0.8 with M0-M6 complete, M7 in progress, using a wholly different src/starkernel/ directory structure. |
| docs/working/architecture/03-architecture/heartbeat-system/architecture.md | Proposes vm_tick() dispatcher centralizing Loop #3/#5 heartbeat logic | HISTORICAL | No date; ends in an open question, never confirmed adopted. Foundational rationale doc; superseded in specifics by instrumentation-plan.md's HeartbeatTickSnapshot design. |
| docs/working/architecture/03-architecture/heartbeat-system/critical-insight.md | Discovery memo: heartbeat tick rate is variable, not fixed; Stage 1 DoE baseline was flawed | HISTORICAL | Dated 2025-11-20, "Game-changer for Phase 2 DoE." Point-in-time investigation memo that directly motivated implementation-plan.md. |
| docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md | Plan for HeartbeatRateSample logging to capture variable tick rate | SUPERSEDED | Superseded by instrumentation-plan.md. Same date (2025-11-20) and goal, but proposes an earlier/different struct (HeartbeatRateSample) than the HeartbeatTickSnapshot design CLAUDE.md cites as the live target. |
| docs/working/architecture/03-architecture/heartbeat-system/instrumentation-plan.md | Per-tick instrumentation plan: HeartbeatTickSnapshot, tick_buffer, heartbeat_export_csv() | WORKING | Explicitly the doc CLAUDE.md cites as current ("declared in include/vm.h, but heartbeat_export_csv() is not yet implemented"). Checklist entirely unchecked. |
| docs/working/architecture/03-architecture/heartbeat-system/segfault-analysis.md | Root-cause analysis of heartbeat-thread/main-thread race on RollingWindowOfTruth | HISTORICAL | Dated 2025-11-19, "Identified & Ready for Fix," includes a past-tense commit-message template implying the tuning_lock fix was applied. No current doc mentions this race as open. |
| docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md | Investigative bug-hunt audit of 6 feedback loops (precursor to the 7-loop model) | SUPERSEDED | Superseded by feedback-loops.md. Dated 2025-11-08, full of strikethrough "FIXED" headers; covers only 6 loops, unlike the polished current 7-loop reference. |
| docs/working/architecture/03-architecture/physics-engine/feedback-loops.md | Canonical reference: all 7 feedback loops, tuning knobs, related source files | CURRENT | Matches CLAUDE.md's explicit citation ("all 7 loops detailed") verbatim; clean finished reference table covering Loops #1-7 including #5/#6 inference. |
| docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md | Gap-analysis backlog of metrics not yet collected (stack depth, bucket histograms, etc.) | WORKING | Explicitly self-titled "GAPS ONLY"; prioritized TODO backlog, not a current-state description; some gaps may have since been filled. |
| docs/working/architecture/03-architecture/physics-engine/monitoring-principles.md | Doctrinal rules for non-perturbative monitoring instrumentation | CURRENT | Presents itself as binding/evergreen ("canonical rules for ALL AI assistants"); uses an older "four core loops (FL1-FL4)" framing that should be reconciled with the current 7-loop model, but the doctrine itself remains in force. |
| docs/working/architecture/03-architecture/physics-engine/ssm-equations.md | Exploratory mathematical modeling of SSM via physics analogies for patent/DARPA strategy | HISTORICAL | Dated 2025-11-29, self-labeled "Status: Research Analysis - Exploratory." Predates Jacquard naming; speculates generically about future "L8" without Jacquard/attractor-bucket/mode-name vocabulary. |
| docs/working/architecture/03-architecture/physics-engine/ssm-raw-data-analysis.md | Raw experimental data analysis from a specific Nov 22-27 2025 DoE campaign (51,840 runs) | HISTORICAL | Dated 2025-11-29; tied to specific named CSV files and a calendar-based "Next Steps" plan. Uses "L8" and 4 of 6 Jacquard mode names but never "Jacquard" — an early/transitional naming stage. |
| docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md | Formal theoretical definition of SSM as a computational model (attractor basins, axioms) | OBSOLETE | Zero mentions of "Jacquard," "L8," "attractor bucket," or the six named modes from CLAUDE.md; reads as a conceptual precursor never reconciled with the concrete ssm_jacquard.c system. |
| docs/working/architecture/03-architecture/pipelining/context-window-and-binary-chop.md | Context-window infrastructure (Knob #6) + planned binary-chop tuning for Loop #4 | WORKING | Dated 2025-11-06, "Phase 1 Extension Complete," but binary-chop decision logic explicitly a doubling-rule stub with "Phase 2 (Next session)" unchecked; corroborated as still-unutilized by wired-not-utilized.md. |
| docs/working/architecture/03-architecture/pipelining/design.md | Master architectural design for pipelining/speculative execution (Loop #4) | HISTORICAL | No date/status stamp; entirely aspirational ("Goal:", "Hypothesis"); Phase 3+ (actual prefetching/speculation) roadmap items remain unchecked and appear unrealized per wired-not-utilized.md. |
| docs/working/architecture/03-architecture/pipelining/phase-1-instrumentation.md | Completed-checkpoint record of Phase 1 transition-tracking instrumentation | HISTORICAL | Dated 2025-11-06, "Phase 1 Complete," 731 tests passing — accurate closed record of one sub-phase; its Phase 2-4 TODOs were never closed per wired-not-utilized.md. |
| docs/working/architecture/03-architecture/pipelining/wired-not-utilized.md | Critical-issue report: pipelining decision/speculation logic defined but never called | WORKING | No date/commit stamp; ends on an unactioned recommendation ("Option A: Disable") with no resolution language. Indicates Loop #4's prediction/speculation half may still be inactive in code. |
| docs/working/architecture/03-architecture/word-acl/DESIGN.md | Full design spec for word-level ACL system (C fields, ACL.4th, zuse.4th, two-console model) | CURRENT | Explicitly the doc CLAUDE.md designates authoritative; internal 8-phase punch list (Phases 1-6 done, 7-8 remaining) matches CLAUDE.md's summary exactly. |
| docs/working/archive/quality/README.md | Quality directory index | OBSOLETE | States "18 modules"; current is 22 categories/936+ tests per CLAUDE.md. |
| docs/working/archive/quality/audits/codebase-audit-report.md | Full codebase audit | HISTORICAL | Dated 2025-12-03; point-in-time snapshot, paired with corrective-actions.md. |
| docs/working/archive/quality/audits/corrective-actions.md | Resolution log for codebase audit | HISTORICAL | Dated 2025-12-03, v3.0.1, "COMPLETE" — 21/22 issues resolved; companion to codebase-audit-report.md. |
| docs/working/archive/quality/audits/implementation-audit.md | Adaptive tuning implementation audit | HISTORICAL | Dated 2025-11-19, references 787/840 tests (now 936+); overtaken by later OPP reports. |
| docs/working/archive/quality/audits/section-2-audit.md | Physics subsystem safety audit (full) | HISTORICAL | Dated 2025-11-20; paired with section-2-executive-summary.md. |
| docs/working/archive/quality/audits/section-2-executive-summary.md | Physics safety audit executive summary | HISTORICAL | Dated 2025-11-20, "complete - awaiting final approval"; summary counterpart to section-2-audit.md. |
| docs/working/archive/quality/phase-tracking/phase-2-implementation-checklist.md | Checklist for heartbeat instrumentation (tick_buffer/snapshot) | WORKING | CLAUDE.md confirms struct exists but heartbeat_export_csv() still not implemented — open, unrealized plan. |
| docs/working/archive/quality/phase-tracking/phase-2-issues-identified.md | Float/double violations root-cause list in physics code | HISTORICAL | Dated 2025-11-08, "in progress" at the time; precedes implementation-checklist. |
| docs/working/archive/quality/phase-tracking/phase-2a-session-summary.md | Session summary: WORD_FROZEN flag + linear decay | HISTORICAL | Dated 2025-11-07, "complete & validated"; distinct earlier "Phase 2a" thread. |
| docs/working/archive/quality/regression/detection-framework.md | Regression detection framework design (for OPP #2+) | HISTORICAL | Dated 2025-11-19, design doc later used in opp-02-report.md. |
| docs/working/archive/quality/regression/opp-02-report.md | OPP #2 window-width tuning experiment report | HISTORICAL | Dated 2025-11-19, "complete"; recommends a config for OPP #3 — completed dated report. |
| docs/working/archive/quality/validation/break-me-report.md | Adversarial/fuzz testing report (intended) | DELETE | File is empty (0 bytes); never written despite break_me_tests.c existing. |
| docs/working/archive/quality/validation/comprehensive-physics-validation.md | Triple-blind 90-run DoE physics validation protocol | HISTORICAL | Dated 2025-11-06; source protocol behind the "0% variance across 90 runs" figure cited in CLAUDE.md. |
| docs/working/archive/quality/validation/phase-1-protocol.md | GitHub governance/document-routing validation protocol | OBSOLETE | Dated 2025-11-03; describes a governance/vault repo system absent from current architecture, unrelated to physics DoE. |
| docs/working/archive/quality/validation/phase-2-executive-summary.md | DoE paradigm shift: factorial to multivariate dynamics (750-run plan) | HISTORICAL | Dated 2025-11-20, "design complete, ready for implementation." |
| docs/working/archive/operations/README.md | Ops directory index / build & CI overview | CURRENT | Build/test commands match current Makefile; honestly labels CI/CD section "(Future)". |
| docs/working/archive/operations/backlog-gatekeeper.md | Backlog governance (ECO/CAPA gatekeeper) | OBSOLETE | References a .github/workflows/... file that doesn't exist; no .github/ directory in repo at all. |
| docs/working/archive/operations/jenkins-pipeline-guide.adoc | Jenkins CI pipeline architecture | OBSOLETE | No Jenkinsfile or CI config exists anywhere in the repo. |
| docs/working/archive/operations/qa-intake-workflow.adoc | QA defect intake / CAPA process | OBSOLETE | Cites stale version v2.0.2 (current v3.0.3); references nonexistent GitHub issue templates and Jenkins automation. |
| docs/working/archive/operations/refinement/annotations.adoc | C/Isabelle refinement annotation guide | WORKING | "Phase 1 in-progress" header; active methodology guide for ongoing refinement work. |
| docs/working/archive/operations/refinement/capa.adoc | C/Isabelle refinement defect tracking log | WORKING | All phases "not started," currently empty live tracking doc. |
| docs/working/archive/operations/refinement/roadmap.adoc | C/Isabelle refinement roadmap | WORKING | All key functions listed "OPEN"; active planning doc with 6-8 month estimate. |
| docs/working/archive/operations/workflow.md | CI/CD trunk-based branch workflow (devl/test/qual/prod) | OBSOLETE | Describes branches/Jenkins triggers that don't exist; repo only has master and feature branches. |
| docs/working/archive/research/README.md | Research directory index | SUPERSEDED | References a patent-filing placeholder/submission package now superseded by the published SSRN paper. |
| docs/working/archive/research/doe-metrics-schema.md | DoE CSV metrics schema (35 columns) | HISTORICAL | Dated 2025-11-19, predates the 2025-12-08 CSV-export suppression noted in CLAUDE.md. |
| docs/working/archive/research/literature-review.md | Literature positioning for the optimization paper | SUPERSEDED | Draft feeder material for the now-published SSRN paper. |
| docs/working/archive/research/research-outline.md | Paper outline draft ("working title" + alternatives) | SUPERSEDED | Pre-publication draft outline; paper has since been published. |
| docs/working/archive/research/results-for-publication.md | Draft abstract targeting PLDI/ASPLOS | SUPERSEDED | Draft abstracts for venues other than where it was ultimately published (SSRN). |
| docs/working/archive/session-logs/2025-11-20-recap.md | Dated session recap (DoE multivariate dynamics pivot) | HISTORICAL | Explicitly dated point-in-time design discussion record. |
| docs/working/archive/session-logs/2025-11-26-worklog.md | Dated work log (L8 Jacquard integration) | HISTORICAL | Explicitly dated; documents the l8-final-integration milestone. |
| docs/working/archive/session-logs/README.md | Session-logs directory index | CURRENT | Accurately describes folder purpose; explicitly warns logs may be outdated. |
| docs/working/archive/session-logs/experimental-addendum.md | Mislabeled: actually a "StarForth to StarshipOS Hybrid Kernel Transformation Plan" | OBSOLETE | Early kernel design plan superseded by the actually-implemented LithosAnanke v1.0.8 architecture (M0-M7). |
| docs/working/archive/session-logs/experimental-iteration-usage.md | Usage guide for run_doe.sh / run_experimental_iteration.sh | WORKING | Matching scripts still exist in scripts/; living usage guide, not a dated log. |
| docs/working/archive/session-logs/serialized-questing-pike.md | Informal narrative on physics-analogy overclaiming risk | HISTORICAL | Captured point-in-time exploratory discussion, not a guide. |
| ./docs/patent/CHANGES_SUMMARY.md | Patent revision log (title, James Law language, claim changes) dated 2025-12-10 | HISTORICAL | Records decisions made during v2 revisions; accurate for its time but describes edits already applied — not a live working document. |
| ./docs/patent/JARGON_CHANGES.md | Term-replacement log (e.g. "Execution Heat" → "Execution Frequency Counters") dated 2025-12-10 | HISTORICAL | Records terminology decisions already baked into _v2 section files; useful audit trail but not a living document. |
| ./docs/patent/Makefile | LaTeX build rules for main.tex |
CURRENT | Minimal but functional; drives pdflatex main.tex double-pass build. |
| ./docs/patent/README_V3.md | Overview claiming patent_v3_complete.tex is the master document |
OBSOLETE | Describes a master file (patent_v3_complete.tex) that does not exist; structure does not match the actual main.tex-based layout. |
| ./docs/patent/USPTO_COVER_LETTER.md | Draft USPTO provisional cover letter with placeholder contact fields | WORKING | Contact fields ([Your email], [Your phone]) still blank; needs completion before filing. |
| ./docs/patent/main.tex | Master LaTeX patent document; inputs _v2 section files | CURRENT | This is the live build root; actual \input order confirmed. |
| ./docs/patent/sb0015a.pdf | USPTO form SB0015a (Provisional Application cover sheet) | CURRENT | Byte-identical to final_provisional/sb0015a.pdf (205016 bytes both); root copy is authoritative working copy. |
| ./docs/patent/sb0016.pdf | USPTO form SB0016 (fee transmittal or declaration) | WORKING | Differs from final_provisional/sb0016.pdf (557654 vs 577171 bytes); root copy is smaller — likely a prior draft; the larger final_provisional/ copy appears to be the filed version. |
| ./docs/patent/ssm_RAJ_v1_patent_application.pdf | Compiled patent application PDF | CURRENT | Byte-identical to final_provisional/ssm_RAJ_v1_patent_application.pdf (1735085 bytes both); root copy is authoritative working copy. |
| ./docs/patent/ssm_provisional_patent.tex | Standalone monolithic provisional patent LaTeX document | SUPERSEDED | Self-contained single-file precursor; superseded by the modular main.tex + sections/ architecture. |
| ./docs/patent/sections/01_title_inventors.tex | Section file — title/inventors | OBSOLETE | Does not exist on disk; name never appears in any \input in main.tex. |
| ./docs/patent/sections/02_cross_reference.tex | Section file — cross-references | OBSOLETE | Does not exist on disk; the 02_* slot in main.tex is 02_field_v2, not a cross-reference section. |
| ./docs/patent/sections/02_cross_reference_v2.tex | Section file — cross-references v2 | OBSOLETE | Does not exist on disk; main.tex uses 02_field_v2, not a cross-reference section. |
| ./docs/patent/sections/03_background.tex | Background of the Invention — original draft | SUPERSEDED | Exists on disk; superseded by 03_background_v2.tex which main.tex actually inputs. |
| ./docs/patent/sections/03_background_v2.tex | Background of the Invention — revised | CURRENT | Inputted by main.tex. |
| ./docs/patent/sections/04_summary.tex | Summary of the Invention — original draft | SUPERSEDED | Exists on disk; superseded by 04_summary_v2.tex which main.tex actually inputs. |
| ./docs/patent/sections/04_summary_v2.tex | Summary of the Invention — revised | CURRENT | Inputted by main.tex. |
| ./docs/patent/sections/05_brief_description.tex | Brief Description of Drawings — original | OBSOLETE | Does not exist on disk; the 05_* slot in main.tex is 05_drawings. |
| ./docs/patent/sections/05_brief_description_v2.tex | Brief Description of Drawings — v2 | OBSOLETE | Does not exist on disk; main.tex uses 05_drawings, not this name. |
| ./docs/patent/sections/06_detailed_description.tex | Detailed Description — original draft | SUPERSEDED | Exists on disk; superseded by 06_detailed_description_v2.tex which main.tex actually inputs. |
| ./docs/patent/sections/06_detailed_description_v2.tex | Detailed Description — revised | CURRENT | Inputted by main.tex. |
| ./docs/patent/sections/07_claims.tex | Claims section — original | OBSOLETE | Does not exist on disk; the 07_* slot in main.tex is 07_embodiments, not claims. |
| ./docs/patent/sections/07_claims_v2.tex | Claims section — v2 | OBSOLETE | Does not exist on disk; main.tex uses 07_embodiments and 08_claims_v2 for claims. |
| ./docs/patent/sections/08_abstract.tex | Abstract section | OBSOLETE | Does not exist on disk; main.tex uses 11_abstract_v2 for the abstract. |
| ./docs/patent/sections/RAJ_v1_01_title_inventors.tex | RAJ v1 title/inventors section | OBSOLETE | Does not exist on disk; entire RAJ_v1_* naming scheme not referenced in main.tex. |
| ./docs/patent/sections/RAJ_v1_02_cross_reference.tex | RAJ v1 cross-reference section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_03_background.tex | RAJ v1 background section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_04_summary.tex | RAJ v1 summary section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_05_brief_description.tex | RAJ v1 brief description section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_06_detailed_description.tex | RAJ v1 detailed description section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/final_provisional/README.md | README for the final_provisional/ subdirectory | OBSOLETE | Does not exist on disk. |
| ./docs/patent/final_provisional/sb0015a.pdf | USPTO form SB0015a — filed copy | SUPERSEDED | Byte-identical to root sb0015a.pdf (205016 bytes); root copy is the working canonical version. |
| ./docs/patent/final_provisional/sb0016.pdf | USPTO form SB0016 — filed copy | CURRENT | Differs from root sb0016.pdf (577171 vs 557654 bytes); this larger copy is the filed/submitted version and is the more complete document. |
| ./docs/patent/final_provisional/ssm_RAJ_v1_patent_application.pdf | Compiled patent application PDF — filed copy | SUPERSEDED | Byte-identical to root ssm_RAJ_v1_patent_application.pdf (1735085 bytes); root copy is the working canonical version. |
| docs/working/scratch/src/INTEGRATION_NOTES.adoc | StarForth↔StarshipOS sync scripts (integrator.sh) | HISTORICAL | Describes ad-hoc integrator.sh scripts and one-day debugging session; superseded by formal capsule/build pipeline in current CLAUDE.md. Worth keeping as record of integration approach. |
| docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc | L4Re integration checklist, hardcoded local paths | OBSOLETE | References absolute local dev paths (/home/rajames/CLionProjects/...) and a TODO checklist for copying platform files; current architecture has moved on. |
| docs/working/scratch/src-index.adoc | docs/src documentation index | WORKING | Active index/TOC for the docs/src tree, but contains multiple dead links (ABI.adoc, BLOCK_STORAGE_GUIDE.adoc, WORD_DEVELOPMENT.adoc, TESTING.adoc, BREAK_ME_REPORT.adoc, GAP_ANALYSIS.adoc) — needs pruning/repair. |
| docs/working/architecture/architecture-internals/INIT_SYSTEM.adoc | INIT system / conf/init.4th boot mechanism | CURRENT | Describes init.4th, INIT word, dictionary fence — matches current capsule/init architecture described in CLAUDE.md. |
| docs/working/architecture/architecture-internals/MESSAGING.adoc | Thermodynamic "Message Field" model for StarshipOS IPC | WORKING | Forward-looking design doc for a not-yet-implemented StarshipOS messaging subsystem; consistent with physics/thermodynamic metaphor language. |
| docs/working/scratch/src/bug_report.adoc | GitHub issue template (bug report) converted to AsciiDoc | DELETE | Generic GitHub bug-report template with smartphone/browser/OS fields irrelevant to a CLI FORTH VM; auto-converted from .github/ISSUE_TEMPLATE; no project-specific value. |
| docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc | Build-time flags/defines reference | CURRENT | Cross-checked flag names against Makefile; consistent catalog of build options, actively useful reference. |
| docs/working/architecture/build-and-tooling/DOCUMENTATION_README.adoc | How docs/API docs are generated (make docs, Doxygen→AsciiDoc) | CURRENT | Describes docs/src/appendix/ generation via scripts/generate-doxygen-appendix.sh, directly wired into Makefile. |
| docs/working/architecture/build-and-tooling/INIT_TOOLS.adoc | tools/extract-init and init.4th↔disk image sync tooling | WORKING | Describes tools/extract-init; tool binary not confirmed in current tools/ directory — may have been renamed; treat as living doc needing verification. |
| docs/working/hardware/PGO_GUIDE.adoc | Profile-Guided Optimization guide | WORKING | Content matches current Makefile pgo/pgo-build/pgo-perf/pgo-valgrind targets exactly, but the document's own title line literally reads "QUARANTiNE ME MOTHERFUCKER" — self-flagged for review before being trusted as polished. |
| docs/working/hardware/PLATFORM_BUILD_GUIDE.adoc | Cross-compilation / platform build matrix (POSIX, L4Re) | CURRENT | Matches Makefile L4RE=1 flag and platform/time_posix.c, platform/time_l4re.c files in src/platform/. |
| docs/working/scratch/ci-cd/FMEA_BLOCKING_GATES.adoc | FMEA gating for CAPA/ECR/ECO governance workflow | CURRENT | Dated 2025-11-03, describes active GitHub Workflows + pending Jenkins governance gate; consistent with other governance docs. |
| docs/working/scratch/ci-cd/GITHUB_ISSUES_GOVERNANCE_FLOW.adoc | Relationship between GitHub Issues and governance in_basket | CURRENT | Same governance doc set, dated 2025-11-03, internally consistent. |
| docs/working/scratch/ci-cd/GOVERNANCE_INPUT_AUDIT.adoc | Audit/compliance checklist for governance input routing | CURRENT | Dated 2025-11-03, "COMPLIANT" audit result; part of active governance documentation set. |
| docs/working/scratch/ci-cd/JENKINS_GOVERNANCE_INTEGRATION.adoc | Jenkins pipeline → governance in_basket integration spec | CURRENT | Same active governance doc set, dated 2025-11-03. |
| docs/working/scratch/src/development/AGENTS.adoc | Repository guidelines / coding conventions | DELETE | Duplicate of docs/working/scratch/AGENTS.md (the live version); older AsciiDoc precursor with stale binary path (./build/starforth). Archived in docs/trash/duplicates-pass4.tar.gz. |
| docs/working/scratch/src/development/CONTRIBUTING.adoc | Generic contribution guide for "StarshipOS" | OBSOLETE | Boilerplate/templated contribution guide (placeholder coc-contact@example.org, generic Conventional Commits advice) not tailored to actual StarForth workflow or governance process; contradicts more specific and current ci-cd governance docs. |
| docs/working/architecture/doxygen/DOXYGEN_QUICK_REFERENCE.adoc | Doxygen comment cheat-sheet | CURRENT | Matches make docs/make docs-html targets and Doxygen pipeline; straightforward reference card still applicable. |
| docs/working/architecture/doxygen/DOXYGEN_STYLE_GUIDE.adoc | Doxygen documentation style guide | CURRENT | Companion to quick-reference; consistent with active Doxygen→AsciiDoc/HTML/PDF pipeline. |
| docs/working/scratch/src/feature_request.adoc | GitHub issue template (feature request) converted to AsciiDoc | DELETE | Generic GitHub feature-request template, garbled by adoc conversion; no project-specific content. |
| docs/working/architecture/getting-started/INSTALL.adoc | Installation guide (prerequisites, build/install) | WORKING | References ./build/starforth run path rather than current ./build/amd64/<profile>/starforth convention; otherwise generally accurate. |
| docs/working/architecture/getting-started/QUICKSTART.adoc | Quick-start build/run guide | WORKING | Same stale-path issue (./build/starforth instead of ./build/amd64/standard/starforth); otherwise build command list matches current Makefile targets. |
| docs/working/scratch/governance/index.adoc | Pointer/redirect to external StarForth-Governance repo | CURRENT | Tiny stub file that redirects to the external governance repository README; still valid as a redirect. |
| docs/working/scratch/COMMUNICATION_GUIDE.adoc | "Analogy cheat sheet" for explaining physics-driven OS concept to various audiences | WORKING | Internal communications/marketing aid; not tied to specific code, ages well, still usable living document. |
| docs/working/scratch/GOVERNANCE_EXPORT_NOTES.adoc | Checklist of Phase 1 physics artifacts to mirror into governance repo | WORKING | Dated 2025-10-23; references HOLA_PROTOCOL.adoc and formal/Physics_*.thy files which still exist — consistent and current as an internal checklist. |
| docs/working/specifications/HOLA_PROTOCOL.adoc | HOLA shared-memory analytics protocol spec | CURRENT | Cross-checked against include/physics_runtime.h: HOLA_SHARED_MAGIC, HOLA_PROTOCOL_MAJOR/MINOR, and the analytics header struct all exist verbatim in current source — accurate technical reference. |
| docs/working/architecture/MAMA_FORTH_SUPERVISOR_ARCHITECTURE.adoc | Multi-VM supervisor architecture ("Mama Forth") | WORKING | Concept is alive in current code — src/starkernel/capsule/mama_forth_words.c exists and capsule birth protocol (MAMA_INIT capsule type) matches CLAUDE.md; this doc appears to be the design precursor to the now-partially-implemented capsule system. |
| docs/working/scratch/src/internal/PHASE_2A_COMPLETION_REPORT.adoc | Completion report: Freeze flag + linear decay (Phase 2a) | HISTORICAL | Accurate closed record dated 2025-11-07; feature is shipped and stable — downgraded from CURRENT as a completion record, not a living doc. |
| docs/working/scratch/src/internal/PHASE_2_IMPLEMENTATION_SUMMARY.adoc | Phase 2 action-item summary pointing to design + completion docs | HISTORICAL | Companion index to PHASE_2A_COMPLETION_REPORT; both docs describe a completed, closed phase — downgraded from CURRENT. |
| docs/working/scratch/src/internal/PHASE_2_PHYSICS_DECAY_AND_FREEZE.adoc | Design spec for decay/freeze mechanisms | HISTORICAL | Marked "Design Phase" as of 2025-11-07, but the corresponding PHASE_2A_COMPLETION_REPORT.adoc shows this has since been implemented and validated — spec is now historical record of the design rationale behind the now-shipped feature. |
| docs/working/architecture/PHYSICS_CONE_OF_INFLUENCE_DESIGN.adoc | Feedback-control architecture design ("cone of influence") | WORKING | Forward-looking architectural design note for scheduling/control; consistent with physics engine terminology still in active use. |
| docs/working/architecture/PHYSICS_CONTROL_SYSTEM_DESIGN.adoc | Physics observables → scheduling/memory management integration design | WORKING | Design-stage architecture note, not yet fully realized; scheduling/memory integration is still aspirational per current CLAUDE.md roadmap. |
| docs/working/scratch/src/internal/PHYSICS_HOTWORDS_CACHE_INTEGRATION.adoc | Hot-words cache integration implementation checklist | SUPERSEDED | Describes a step-by-step plan to add hot-words caching; this feature is now implemented and documented as "Loop #1 — Execution Heat" / ENABLE_HOTWORDS_CACHE=1 / dictionary_heat_optimization.c in current CLAUDE.md. |
| docs/working/scratch/src/internal/PHYSICS_IMPLEMENTATION_OPTIONS.adoc | Three implementation-path options for physics engine | HISTORICAL | "Phase 1 complete" framing with options for next steps; physics engine has since progressed well past this decision point (7 loops, L8 Jacquard). |
| docs/working/scratch/src/internal/PHYSICS_IMPLEMENTATION_STATUS.adoc | POSIX vs L4Re porting strategy status for physics hooks | HISTORICAL | Describes early wiring state of physics_metadata_touch() calls; physics engine has since matured substantially — status snapshot now outdated. |
| docs/working/scratch/src/internal/PHYSICS_SCHEDULING_PLAN.adoc | Planning note for physics-inspired scheduling metadata | HISTORICAL | Describes DictPhysics struct fields as stub/unpopulated placeholders; current DictPhysics is now populated and actively used — doc predates that implementation. |
| docs/working/architecture/PHYSICS_SIGNAL_MAP.adoc | Telemetry signal inventory (L4Re KIP signals + VM-internal counters) | WORKING | Useful living reference of available L4Re kernel telemetry signals for future physics/scheduler work; L4Re remains a supported platform. |
| docs/working/scratch/src/internal/SHARED_CLAUDE.adoc | Cross-project Claude-instance shared notepad (StarForth↔StarshipOS) | DELETE | Dated 2025-10-19 ad-hoc session notes/chat log between AI instances about integrator script status; pure transient working notes with no lasting reference value. |
| docs/working/architecture/VM_FORMALIZATION_PLAN.adoc | Isabelle/HOL formalization roadmap for docs/src/internal/formal/ theories |
CURRENT | Directly describes the docs/src/internal/formal/*.thy files which exist on disk and are wired into the Makefile's Isabelle build targets. |
| docs/working/hardware/performance-profiling/ARM64_OPTIMIZATIONS.adoc | ARM64 assembly optimization summary | CURRENT | Referenced headers (include/vm_asm_opt_arm64.h, vm_inner_interp_arm64.h, arch_detect.h) all confirmed present in current include/ tree. |
| docs/working/hardware/performance-profiling/ASM_OPTIMIZATIONS.adoc | x86_64 assembly optimization guide | CURRENT | Referenced headers (vm_asm_opt.h, vm_inner_interp_asm.h) confirmed present; consistent with USE_ASM_OPT=1 build flag in current CLAUDE.md. |
| docs/working/hardware/performance-profiling/PROFILER.adoc | Built-in word-execution profiler guide | CURRENT | Describes profiler integrated with PGO pipeline; consistent with make test PROFILE=1 and profiler.c present in current src tree. |
| docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc | Dictionary allocation strategy proposal for L4Re | WORKING | References src/dictionary_management.c:228 (vm_create_word() malloc) and defining_words.c:554 (FORGET free) — both locations exist; malloc/free dependency has likely not yet been replaced with L4Re-native allocator. |
| docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc | General L4Re integration guide (IPC, dataspaces, package structure) | WORKING | Broad integration guide; L4Re remains a supported platform per CLAUDE.md tech stack diagram. |
| docs/working/hardware/platform-integration/PLATFORM_ABSTRACTION.adoc | Platform abstraction layer (vtable pattern for POSIX/L4Re) | CURRENT | Matches actual platform/linux/time.c and platform/l4re/time.c files present in current src tree per CLAUDE.md source tree listing. |
| docs/working/hardware/platform-integration/RASPBERRY_PI_BUILD.adoc | Raspberry Pi 4 / ARM64 build guide | CURRENT | Matches rpi4-cross Makefile target and ARM64 architecture support (ARCH=raspi) listed in current CLAUDE.md build targets. |
| docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc | Block I/O L4Re porting endpoints (blkio vtable mapping) | CURRENT | Describes blkio_open/close/read vtable API; matches blkio_*.c backend files listed in current CLAUDE.md source tree. |
| docs/working/scratch/testing-quality/KANBAN-WORKFLOW-VALIDATION.adoc | Validation procedure for GitHub Projects Kanban automation (CAPA-032) | CURRENT | Dated 2025-11-02 with explicit source commit hash; references .github/workflows/capa-kanban-sync.yml which is a concrete CI artifact. |
| docs/working/archive/legacy/OPTIMIZATION_OPPORTUNITIES.md | Physics engine optimization opportunity ranking dated 2025-11-19 | SUPERSEDED | Superseded by docs/03-architecture/physics-engine/ and Loop #5/#6 implementations |
| docs/working/archive/legacy/README.md | Index and usage guide for the docs/archive directory | CURRENT | Self-referential; accurately describes the archive's purpose and sub-structure |
| docs/working/archive/legacy/START_HERE_HEARTBEAT_DOE.md | Phase 2 heartbeat DoE launch guide (250 runs, 5 elite configs) | SUPERSEDED | README notes this is superseded by docs/02-experiments/heartbeat-doe/ |
| docs/working/archive/legacy/phase-1/Reference/BACKLOG_INJECTION_ANALYSIS.md | Governance model analysis of GitHub issue injection points | HISTORICAL | Nov 2025 snapshot of CI/process governance state |
| docs/working/archive/legacy/phase-1/Reference/EXPERIMENT_QUICK_REFERENCE.txt | Quick-reference ops card for the 90-run A/B/C physics validation experiment | HISTORICAL | Raw ops card tied to a specific pre-publication experiment run |
| docs/working/archive/legacy/phase-1/Reference/IMPLEMENTATION_SUMMARY.md | Phase 1 CI/Kanban automation implementation summary | HISTORICAL | Records CI automation decisions made during project Phase 1 |
| docs/working/archive/legacy/phase-1/Reference/JENKINS_USER_GUIDE.md | Jenkins CI user guide | HISTORICAL | Jenkins may no longer be the active CI system; check .github/workflows/ |
| docs/working/archive/legacy/phase-1/Reference/KANBAN-TESTING-GUIDE.md | Guide for testing GitHub Projects Kanban automation | HISTORICAL | Companion to CAPA-032 Kanban work; superseded by live workflow |
| docs/working/archive/legacy/phase-1/Reference/KANBAN-WORKFLOW-TEST.md | Kanban workflow test procedures | HISTORICAL | Point-in-time test doc for Kanban automation validation |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_FINAL_STATUS.md | Final status report for project Phase 1 | HISTORICAL | Closed-loop status report; accurately captures Phase 1 completion state |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_IMPLEMENTATION_COMPLETE.md | Phase 1 implementation completion announcement | HISTORICAL | Records the Phase 1 done-condition at time of writing |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_TESTING_RESULTS.md | Phase 1 testing results summary | HISTORICAL | Test results from Phase 1 CI/governance work |
| docs/working/archive/legacy/phase-1/Reference/PHYSICS_EXPERIMENT_README.md | README for the 90-run physics validation experiment | HISTORICAL | Companion README to the experiment data in physics_experiment/ |
| docs/working/archive/legacy/phase-1/Reference/RULE_1_GATES_IMPLEMENTATION.md | Implementation notes for Rule 1 CI gating | HISTORICAL | CI gate design decisions from Phase 1 |
| docs/working/archive/legacy/phase-1/Reference/SECURITY.md | Security notes predating the ACL system | HISTORICAL | Pre-ACL security model; superseded by docs/03-architecture/word-acl/DESIGN.md |
| docs/working/archive/legacy/phase-1/Reference/SESSION_SUMMARY.md | Transient AI session summary | HISTORICAL | Session-level notes; limited long-term value |
| docs/working/archive/legacy/phase-1/Reference/TEST-CAPA-TEMPLATE.md | CAPA test case template | HISTORICAL | Template used during Phase 1 CAPA process |
| docs/working/archive/legacy/phase-1/Reference/codex_audit_report.md | Codex audit report of the codebase | HISTORICAL | Point-in-time static analysis or review; may be stale |
| docs/working/archive/legacy/phase-1/Reference/codex_capa_list.md | CAPA action items derived from Codex audit | HISTORICAL | Action items from Phase 1 audit cycle |
| docs/working/archive/legacy/phase-1/Reference/github_backlog_items.md | GitHub backlog items list | HISTORICAL | Snapshot of backlog at Phase 1; likely stale |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/DEVIATION_REPORT_CSV_FORMATTING.md | CSV formatting deviation report for experiment output | HISTORICAL | Experiment data-hygiene note for the 90-run run |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/FORMAL_CLAIMS_FOR_REVIEWERS.txt | Formal claims document prepared for peer reviewers | HISTORICAL | Pre-publication version; superseded by published SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/01_MAIN_PAPER/PAPER_KEY_CONTRIBUTIONS_SUMMARY.md | Key contributions summary for peer review submission | HISTORICAL | Pre-SSRN draft; superseded by papers/James_Steady-State_Convergence_Adaptive_Runtime.pdf |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/01_MAIN_PAPER/PEER_REVIEW_PAPER_DRAFT.md | Full paper draft submitted for peer review | HISTORICAL | Pre-SSRN draft; superseded by published SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/FORMAL_CLAIMS_FOR_REVIEWERS.txt | Formal claims for reviewers (supporting docs copy) | HISTORICAL | Duplicate of physics_experiment/FORMAL_CLAIMS_FOR_REVIEWERS.txt |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/FORMAL_VERIFICATION_INTERPRETATION.md | Interpretation guide for Isabelle/HOL proofs for reviewers | HISTORICAL | Pre-publication; proof/ directory is the live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/PEER_REVIEW_SUBMISSION_PACKAGE.md | Cover doc for the full peer review submission package | HISTORICAL | Submission metadata; superseded by SSRN publication |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/QUICK_REFERENCE.txt | Quick reference for reviewers | HISTORICAL | Reviewer-facing summary; superseded by published abstract |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/VARIANCE_ANALYSIS_SUMMARY.md | Variance analysis summary for the 90-run experiment | HISTORICAL | Source data for SSRN paper; keep as experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/experiment_summary.txt | Comprehensive 90-run experiment summary | HISTORICAL | Primary experimental record; source data for SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/run_logs/test_matrix.txt | Test matrix for full 90-run experiment | HISTORICAL | Experimental record; run configuration matrix |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/05_SUPPLEMENTARY/PEER_REVIEW_PAPER_OUTLINE.md | Outline used to structure the peer review paper | HISTORICAL | Pre-publication outline; superseded by final SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/05_SUPPLEMENTARY/WORK_COMPLETION_STATUS.md | Work completion checklist for peer review submission | HISTORICAL | Point-in-time submission checklist |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/00-abstract.adoc | AsciiDoc abstract section for peer review paper | HISTORICAL | Pre-publication AsciiDoc draft; superseded by SSRN PDF |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/01-introduction.adoc | AsciiDoc introduction section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/01-summary.adoc | AsciiDoc summary section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/02-formal-theorems.adoc | AsciiDoc formal theorems section | HISTORICAL | Pre-publication; proof/ directory is live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/02-related-work.adoc | AsciiDoc related-work section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/03-experimental-methodology.adoc | AsciiDoc experimental methodology section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/03-methodology.adoc | AsciiDoc methodology section (alternate) | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/04-results.adoc | AsciiDoc results section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/04-variance-analysis.adoc | AsciiDoc variance analysis section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/05-convergence-proof.adoc | AsciiDoc convergence proof section | HISTORICAL | Pre-publication; proof/ directory is live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/05-discussion.adoc | AsciiDoc discussion section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/06-stability-proof.adoc | AsciiDoc stability proof section | HISTORICAL | Pre-publication; proof/ directory is live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/07-predictability-bounds.adoc | AsciiDoc predictability bounds section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/08-peer-review-defense.adoc | AsciiDoc peer-review defense section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/index.adoc | AsciiDoc index/master file for the peer review paper | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/paper.adoc | AsciiDoc combined paper source | HISTORICAL | Pre-publication; superseded by SSRN PDF |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/README.md | README for the peer review submission package | HISTORICAL | Submission index; superseded by SSRN publication |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/QUICK_REFERENCE.txt | Quick reference for the 90-run experiment | HISTORICAL | Ops-level quick card; raw experiment record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/experiment_summary.txt | Top-level experiment summary | HISTORICAL | Primary experimental record; source data for SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/full_90_run_comprehensive/experiment_summary.txt | Full 90-run comprehensive experiment summary | HISTORICAL | Experimental record (duplicate path from submission tree) |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/full_90_run_comprehensive/run_logs/test_matrix.txt | Test matrix for full 90-run experiment | HISTORICAL | Run configuration matrix |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/run_logs/test_matrix.txt | Run logs test matrix (top-level) | HISTORICAL | Raw run log; experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run/experiment_summary.txt | Test run experiment summary | HISTORICAL | Pre-full-run trial; experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run/run_logs/test_matrix.txt | Test run matrix | HISTORICAL | Raw test matrix for trial run |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run2/experiment_summary.txt | Second test run experiment summary | HISTORICAL | Pre-full-run trial #2; experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run2/run_logs/test_matrix.txt | Second test run matrix | HISTORICAL | Raw test matrix for trial run #2 |
| docs/working/archive/legacy/phase-1/Reference/toolchain/gcc.txt | GCC toolchain version/configuration notes | HISTORICAL | Point-in-time toolchain pinning record |
| docs/working/archive/legacy/phase-1/Reference/toolchain/make.txt | Make version/configuration notes | HISTORICAL | Point-in-time toolchain pinning record |