Docs max-out vs standards — INTENT.contractile + methodology.a2ml placeholders unfilled

[hyperpolymath]

Background

Deep audit 2026-06-01 — mirrors the verisimdb#81 shape. valence-shell has an extensive docs surface (34+ root .adoc/.md files, 50+ in docs/) and most of the canonical standards files are present and current. This issue captures the gaps and stale claims.

Standards files — present + current

File	State	Notes
README.adoc	Present, current	574 lines (counted by estate audit 2026-05-26)
CHANGELOG.adoc + CHANGELOG.md	Both present	Possible dual-source drift risk
CONTRIBUTING.md	Present
CODE_OF_CONDUCT.md	Present
SECURITY.md	Present	No placeholders
.well-known/security.txt	Present	Contact, Expires 2027-03-08 — current
.well-known/ai.txt	Present
.well-known/humans.txt	Present
GOVERNANCE.adoc	Present
MAINTAINERS.adoc + MAINTAINERS.md	Both present	Dual-source drift risk
EXPLAINME.adoc	Present	Per-claim caveats — good pattern
PALIMPSEST.adoc	Present
FUNDING.yml	Present
ROADMAP.adoc	Present	References specific audit findings
LICENSE	Present	MPL-2.0 (migrated from PMPL-1.0 — see commit 990b147)
LICENSES/	Present (REUSE format)
NOTICE	Present
THIRD_PARTY_NOTICES.md	Present
RSR_COMPLIANCE.md + RSR_OUTLINE.adoc	Present	RSR-PLATINUM claimed
CLAUDE.md	Present, current	Has "HONEST STATUS (2026-02-12)" pattern

Standards files — MISSING or with PLACEHOLDERS

File	Issue	Severity
.machine_readable/INTENT.contractile	5 unfilled placeholders: {{ONE_PARAGRAPH_PURPOSE}}, {{ONE_PARAGRAPH_ANTI_PURPOSE}}, {{MONOREPO_OR_STANDALONE}}, {{DEP1}}/{{DEP2}}, {{CONSUMER1}}/{{CONSUMER2}}	HIGH — agents reading this can't disambiguate scope
.machine_readable/agent_instructions/methodology.a2ml	1 placeholder: description = "{{PROJECT_UNIQUE_STRENGTH}}"	HIGH — divergent-mode invariants are commented-out (no language-invariant, no divergent-invariants list)
docs/ARCHITECTURE.md	Present	But mixed with 50 phase-design docs; needs a top-level summary
FAQ.adoc	MISSING	Per estate standards
CODEOWNERS (top-level or .github/)	Not seen in audit	Check
docs/audits/ directory	Missing — only docs/governance/CRG-AUDIT-2026-04-18.adoc and docs/reports/audit/audit-2026-04-04.md exist	Per estate standards

Count drift / stale claims

Claim	Doc	Reality	Severity
"200+ theorems"	README.adoc:14	~478 candidates per audit (or 220 actual definitions)	Low — undercount
"250+ theorems"	README.adoc:43	Same as above; inconsistent within README	Medium — fix internal consistency
"602 tests passing"	README.adoc:25	CLAUDE.md says 736	Medium — drift
"10 proof holes across 8 proof files (4 gaps, 4 axioms, 2 structural)"	CLAUDE.md:85	docs/PROOF_HOLES_AUDIT.md says 3 (1 real gap, 1 axiom, 1 structural)	High — CLAUDE.md is months stale on this number
"4 fuzz targets"	README.adoc:65	Actual: 7 in impl/rust-cli/fuzz/fuzz_targets/	Low — undercount
"33 source files" / "~21,000 lines"	CLAUDE.md:83	Actual: 32 src files, 21,331 LoC	Already accurate
"30 source files, 15,720 lines"	CLAUDE.md:178	Same file claims both 33/21K AND 30/15.7K — internal contradiction	High

Tier / RSR claims to verify

• README badge: "RSR-PLATINUM" — RSR_COMPLIANCE.md says this. The estate standards tier evidence checklist should be cross-checked since the proof-debt audit (docs/tech-debt-2026-05-26.md) lists 9 markers (Idris2 partials + Agda postulates) — this should still leave Platinum tenable but the evidence pack should be refreshed.

• README badge: "Proofs-200+ theorems" — actual count higher; refresh.

Standards-canon Gold tier (per verisimdb#81 framing)

Adopting the same Silver → Gold framing verisimdb used:

Silver (current state) ≈ all canonical files exist, most current, two stale internal-count claims, two .machine_readable/ placeholders unfilled.

Gold target:

• Fill INTENT.contractile placeholders (purpose, anti-purpose, architectural invariants, ecosystem)
• Fill methodology.a2ml PROJECT_UNIQUE_STRENGTH + divergent invariants
• Reconcile README count claims (theorems, tests, fuzz, source files) with CLAUDE.md and reality
• Fix the 33-vs-30 source-file internal contradiction in CLAUDE.md
• Refresh CLAUDE.md:85 "10 proof holes" → 3 (matching docs/PROOF_HOLES_AUDIT.md)
• Add FAQ.adoc
• Either delete MAINTAINERS.md (keeping .adoc) or vice versa — same for CHANGELOG
• Add docs/audits/2026-06-01-deep-audit.adoc capturing this audit's seed inventory

References

• docs/tech-debt-2026-05-26.md — estate-scan baseline, classified as Severity OK
• estate-standards: hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md
• estate-memory: [Estate boundary conventions]

🤖 Filed by deep audit 2026-06-01