7.3 KiB
docs/formal/CLAUDE.md — Authoring Conventions for the Formal Documentation Tier
Draft — generated 2026-06-16, starter for Bob's review. Override any rule below with explicit instruction.
Purpose
docs/formal/ is the press-ready LaTeX documentation set for StarshipOS /
StarForth / LithosAnanke. Audience: patent counsel, SSRN reviewers, potential
licensees, paying customers, hobbyist hackers with hardware in hand. Nothing
goes here until it is ready to be cited.
The set is ten publications in three groups, all built from the shared
common/preamble.tex and common/starship.bib and assembled from scraps/:
| Group | Publications |
|---|---|
| Research volumes | vol1-vm-physics, vol2-kernel, vol3-research |
| Practitioner books | dev-guide, user-guide, cookbook |
| Standalone reports | experiments, proofs, ssrn, patent |
The four standalone reports wrap material that lives elsewhere and may build
independently: experiments links R-generated figures from
docs/working/experiments/; proofs mirrors the Isabelle/HOL corpus in
proof/; ssrn includes the Math Companion and references the published PDF;
patent wraps the legal-hold source in docs/patent/ (no claim language is
drafted here — see "What NOT to do").
Scraps System
docs/formal/scraps/ contains press-ready LaTeX fragments converted from
every document in docs/working/. Each scrap is a self-contained .tex
fragment — no \documentclass, no \begin{document} — ready to \input{}
into any publication.
Scrap file naming
Mirror the source path under scraps/:
docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc
→ docs/formal/scraps/architecture/build-and-tooling/BUILD_OPTIONS.tex
Scrap header (required on every file)
%% SCRAP: architecture/build-and-tooling/BUILD_OPTIONS
%% SOURCE: docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc
%% STATUS: working-triage (CURRENT|WORKING|HISTORICAL|SUPERSEDED|OBSOLETE)
%% FITS: dev-guide/ch-build, cookbook/appendix-flags
%% EDITORIAL: lifted — prose rewritten to press voice
FITS: lists candidate \input{} locations across the three publications.
Use none if the scrap is archive/historical material kept for completeness.
Scrap prose conventions (editorial lift)
- Rewrite passive and wordy constructions to active, tight prose.
- Strip filler phrases ("it is important to note that", "as mentioned above").
- Convert bullet lists to
\begin{itemize}or prose where a list is lazy. - Code blocks →
\begin{lstlisting}[language=bash]or[language=C]. - Tables →
\begin{tabular}withbooktabsrules. - All claims checked against
ANTI_CLAIMS.md; hedged language preserved. %% TODO(bob):for anything that requires dictation or verification.%% PATENT:flag on any section touching patent-adjacent claims.
The practitioner books
Scraps feed primarily the three practitioner books, each of which has its own
main.tex that \input{}s scraps in chapter order:
| Directory | Title | Audience |
|---|---|---|
dev-guide/ |
StarForth Developer Guide | Contributors, embedders, kernel hackers |
user-guide/ |
StarForth User Guide | End users running StarForth interactively |
cookbook/ |
The StarForth Cookbook | FORTH programmers wanting patterns and recipes |
A FITS: target may also name a research volume (vol1–vol3) or a
standalone report (experiments, proofs, ssrn, patent) when a scrap
suits one of those. A scrap can be \input{} into more than one publication.
| Volume | Scope |
|---|---|
| Vol I — StarForth VM and Physics Runtime | FORTH-79 interpreter, physics-driven adaptive runtime (7 feedback loops), Isabelle/HOL formal verification, 90-run experimental results. |
| Vol II — LithosAnanke Kernel and Capsule System | Bare-metal UEFI kernel (M0–M7), capsule birth protocol, word-level ACL, platform support, L8 Jacquard Mode Selector. |
| Vol III — Research Reference | SSRN paper transcript, Mathematical Companion, formal claim tables, reproducibility protocol, roadmap. |
Voice and Tone
- Technical precision over enthusiasm. Never write "cutting-edge," "revolutionary," or "state-of-the-art." Let results speak.
- Third person throughout. Not "we did X" — "the system does X" or "the implementation uses X."
- Calibrated claims only. If a claim appears in
ANTI_CLAIMS.mdas out-of-bounds, it does not appear here. Seedocs/working/papers/ANTI_CLAIMS.md. - Thermodynamic metaphors are modeling tools, not physics claims. Always introduce
the domain of use: "using execution frequency as a proxy for thermal energy, …"
See
ONTOLOGY.mdfor canonical term definitions. - Proper nouns are proper. Never rename: James Law, SSM (Steady-State Machine), Jacquard Selector, Uberkernel, Hades. These are registered terms.
LaTeX Conventions
Preamble
All volumes \input{../common/preamble} and \bibliography{../common/starship}.
Do not duplicate preamble content across volumes.
Source and TODO markers
Every chapter stub must carry at the top:
%% SOURCE: <path to working/ source material>
%% TODO(bob): [description of what's needed — dictate or write]
Do not remove %% SOURCE: comments when a chapter is filled in — they serve as
provenance for later reviewers.
Fonts and formatting
- Body text: Computer Modern (default), 11pt,
a4paper,twoside. - Code listings:
listingspackage,basicstyle=\ttfamily\small. - Math:
amsmath,amssymb. Q48.16 fixed-point notation:\mathbb{Q}_{48.16}. - Figures:
\includegraphics[width=\linewidth]{...}. All figures incommon/figures/or in the volume directory'sfigures/subfolder. - Tables:
booktabspackage.\toprule/\midrule/\bottomrule— no vertical rules.
Cross-volume references
Use \label{vol:N:chap:slug} convention, e.g. \label{vol1:chap:physics}.
Do not reference across volumes via \ref in production builds; link by title instead.
Citations
All citations go through common/starship.bib. Use BibTeX keys in format:
james:2025:ssrn— published paperjames:2025:patent— patent applicationjames:2025:proof:loop1— Isabelle/HOL theory file
Promotion Criteria
A section of docs/working/ is ready for formal inclusion when:
- The underlying code or claim is confirmed in
.claude/CLAUDE.mdor the running codebase. - It has been reviewed against
ANTI_CLAIMS.mdandACADEMIC_WORDING_GUIDELINES.md. - There is a
%% SOURCE:pointer to the working/ document it came from. - It compiles without errors and warnings.
A stub with %% TODO(bob): markers does satisfy #4 — compilable stubs are the
goal of Phase 3, not finished chapters.
What NOT to do
- Never invent results. If a number isn't in a source doc or the published paper, stub it:
%% TODO(bob): cite figure here. - Never invent proofs. If a theorem isn't in
proof/*.thy, mark it TODO. - Never draft patent-adjacent text (independent/dependent claims, claim mapping) without Bob's explicit dictation. Leave those sections as
%% TODO(bob): PATENT — do not draft. - Never copy-paste from
COMPUTATIONAL_PHYSICS_FRAMEWORK.md. That doc is HISTORICAL and contains out-of-scope claims that contradictANTI_CLAIMS.md.