docs: max-out vs estate standards + fill INTENT.contractile + reconcile drift counts (closes #44)

[hyperpolymath]

Closes#44.

Mirrors the verisimdb#81 Gold-tier docs sweep. Brings valence-shell from Silver (canonical files exist; placeholders unfilled; numeric drift) to Gold (all placeholders filled; counts reconciled to actual repo state; dual-source eliminated; FAQ + audit log added).

Summary

• Fill all 5 INTENT.contractile placeholder slots (purpose, anti-purpose, STANDALONE, deps, consumers) + add 9-item architectural-invariants + 8-item ask-before-touching.
• Fill methodology.a2mlPROJECT_UNIQUE_STRENGTH + 9-rule divergent-invariants + 9-item known-constraints. Grounded against sibling repos (echidna/proven/ephapax).
• Reconcile drift counts (authoritative: counted from actual repo state, not from any prior doc).
• Delete dual-source pairs (CHANGELOG.md, MAINTAINERS.md); update 10+ outbound references to point at the .adoc survivors.
• Add FAQ.adoc (12 Q&A pairs) and docs/audits/2026-06-01-deep-audit.adoc (audit-log baseline).
• Refresh 0-AI-MANIFEST.a2ml (was a stale rsr-template-repo stub) and .well-known/ai.txt (was pointing at non-existent AI.a2ml).

Drift counts — before / after

Claim	Source	Before	After
Tests passing	README.adoc (3 sites)	602 / 555	736
Theorem candidates	README.adoc (7 sites)	200+ / ~250+	~478 (per issue #42)
Source files	CLAUDE.md (internal contradiction)	33 / 30	32 (measured 2026-06-01)
Rust LoC	CLAUDE.md (internal contradiction)	~21,000 / 15,720	21,331 (wc -l)
Proof holes	CLAUDE.md:85	10 across 8 files	3 (1 gap + 2 axioms, matches PROOF_HOLES_AUDIT.md)
Fuzz targets	README.adoc:65	4	7
Citation BibTeX	README.adoc:540	v0.14.0 / 2025	v0.9.0 / 2026
FAQ "production-ready?" para	README.adoc:490	v0.14.0 / 82% / 177 tests	v0.9.0 / ~78% / 736
License badge URL	README.adoc:3	malformed https://[License: PMPL-1.0,...]	proper shields.io URL, MPL-2.0

Files

Added

• FAQ.adoc — 12 Q&A
• docs/audits/2026-06-01-deep-audit.adoc — audit baseline + 9 newly-surfaced drift items found during execution (not in Docs max-out vs standards — INTENT.contractile + methodology.a2ml placeholders unfilled #44's list)

Deleted

• CHANGELOG.md (kept CHANGELOG.adoc)
• MAINTAINERS.md (kept MAINTAINERS.adoc)

Modified

• .machine_readable/INTENT.contractile, .machine_readable/agent_instructions/methodology.a2ml
• 0-AI-MANIFEST.a2ml (rewrite from stale template stub)
• .well-known/ai.txt (link targets corrected)
• README.adoc, CLAUDE.md (drift reconcile)
• GOVERNANCE.adoc, RSR_COMPLIANCE.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.adoc (link target updates for deleted dual-source files)

Wiki audit

gh api repos/hyperpolymath/valence-shell --jq .has_wiki returns true. Cloning https://github.com/hyperpolymath/valence-shell.wiki.git yields a single Home.md (35 bytes, "Welcome to the valence-shell wiki!"). No content was written from this PR — wikis are user-facing artefacts that need owner direction. Captured as a follow-up in the audit log.

Test plan

• CI green (asciidoc lint, link check, SPDX header check, SECURITY/MAINTAINERS presence)
• git grep "CHANGELOG.md\|MAINTAINERS.md" returns only historical artefacts (CONTINUATION_SESSION_COMPLETE.md, COMPREHENSIVE_EXAMPLES.md vsh-tail example, docs/tech-debt-2026-05-26.md baseline), no live cross-refs.
• grep "{{.*}}" .machine_readable/INTENT.contractile .machine_readable/agent_instructions/methodology.a2ml returns nothing.
• Spot-check that docs/audits/2026-06-01-deep-audit.adoc renders cleanly in asciidoctor.

Follow-ups (not blocking this PR — recorded in audit log)

• Wiki state: decide populate vs. disable vs. redirect-stub.
• impl/rust-cli/$FILE stray 5-byte file (looks like a CI shell artefact).
• .well-known/ai.txt historically referenced AI.a2ml — fixed in this PR, but estate-wide ai.txt convention should be verified against standards/.

🤖 Generated with Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 131 issues detected

Severity	Count
🔴 Critical	9
🟠 High	22
🟡 Medium	100

⚠️Action Required: Critical security issues found!

View findings

[
{
"reason": "Action perpolymath/standards/.github/workflows/governance-reusable.yml@main\n needs attention",
"type": "unpinned_action",
"file": "governance.yml",
"action": "pin_sha",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Action dtolnay/rust-toolchain@nightly needs attention",
"type": "unpinned_action",
"file": "validation.yml",
"action": "pin_sha",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Workflow executes remote script directly (curl/wget piped to shell). Download, verify checksum/signature, then execute.",
"type": "download_then_run",
"file": "lean-verification.yml",
"action": "verify_download_integrity",
"rule_module": "workflow_audit",
"severity": "high"
},
{
"reason": "Workflow executes remote script directly (curl/wget piped to shell). Download, verify checksum/signature, then execute.",
"type": "download_then_run",
"file": "rust-cli.yml",
"action": "verify_download_integrity",
"rule_module": "workflow_audit",
"severity": "high"
},
{
"reason": "Issue in boj-build.yml",
"type": "missing_timeout_minutes",
"file": "boj-build.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Issue in casket-pages.yml",
"type": "missing_timeout_minutes",
"file": "casket-pages.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Issue in casket-pages.yml",
"type": "missing_timeout_minutes",
"file": "casket-pages.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Issue in cflite_batch.yml",
"type": "missing_timeout_minutes",
"file": "cflite_batch.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Issue in cflite_pr.yml",
"type": "missing_timeout_minutes",
"file": "cflite_pr.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium"
},
{
"reason": "Issue in codeql.yml",
"type": "missing_timeout_minutes",
"file": "codeql.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium"
}
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence