docs: fix stale proof-suite claims in FABRIC-2.md; correct docs/CLAUDE.md's Makefile pointer

FABRIC-2.md item 5.2: both lemmas described as deliberately oops-flagged
(ROLL semantics, pipeline pm_wf invariant) were actually resolved
2026-08-13, same day, but FABRIC-2.md was never updated to match --
found during a docs-tree maintainability sweep. Corrected both, and
flagged a real untracked finding the pipeline fix surfaced: the Isabelle
model's accuracy num/den fraction pair doesn't correspond to the real
PipelineGlobalMetrics C struct at all. Also reconciled the theory-count
drift (53/54 mid-sweep numbers vs. the actual current 52, matching
proof/COVERAGE.md; proof/FINDINGS.md's own stale "53" flagged but not
fixed, out of this pass's scope).

docs/CLAUDE.md described a docs/Makefile with docs-formal/docs-working/
docs-index/docs-audit targets that doesn't exist anywhere in the tree.
The real build is docs/formal/Makefile with a completely different
target set (vol1/vol2/vol3/books/standalone/doxygen/clean) -- corrected
to match, and noted docs/INDEX.md has no automation and goes stale
between manual triage passes.

doxygen installed on this machine (was missing entirely, blocking the
API-reference build target).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-18 21:05:21 -04:00
co-authored by Claude Sonnet 5
parent 5b248343b0
commit 4270cf23f1
2 changed files with 54 additions and 9 deletions
+24 -6
View File
@@ -42,15 +42,33 @@ is audience and stability, not quality.
## Makefile Targets
**Corrected 2026-08-18** — this section previously described a `docs/Makefile` with
`docs-formal`/`docs-working`/`docs-index`/`docs-audit`/`docs`/`docs-clean` targets. That file
does not exist and none of those targets exist anywhere in the tree. The real build lives one
level down, at `docs/formal/Makefile`, with a different target set entirely:
```
make docs-formal — build all three LaTeX volumes → PDFs in formal/build/
make docs-working — render working/ markdown to HTML (optional, low priority)
make docs-index — generate docs/INDEX.md inventory of all doc files
make docs-audit — list files tagged OBSOLETE or SUPERSEDED in INDEX.md
make docs — run docs-formal + docs-index
make docs-clean — remove formal/build/ artifacts
# Run from docs/formal/
make — everything: all three volumes + books + standalone docs + doxygen
make vols — vol1 + vol2 + vol3 (the three-volume LaTeX set)
make vol1 — Volume I only
make vol2 — Volume II only
make vol3 — Volume III only
make books — dev-guide + user-guide + cookbook
make standalone — experiments + proofs + ssrn + patent (standalone LaTeX docs)
make doxygen — API reference PDF (requires the `doxygen` binary installed;
runs doxygen → fix-doxygen-unicode.py → doxygen/latex → PDF)
make clean — remove build artifacts
```
`docs/working/` has no build step of its own (no HTML rendering target exists) — it's read
directly as markdown. `docs/INDEX.md` exists but is maintained manually, following this
file's own Phase 1 triage process below — there is no `docs-index`/`docs-audit` automation
that generates or checks it; treat `INDEX.md` as something a triage pass produces by hand,
and expect it to go stale between passes (confirmed stale as of this correction — check its
own date against `git log -1` before trusting it).
---
## Phase 1: Triage (DO THIS FIRST)