Commit Graph

1 Commits

Author SHA1 Message Date
Bo 81fe2d5ae8 feat(docs): sovereignty-proof page — F6/F7 + RPI-leanness case studies (soc-vuu6.32 #sovereignty-proof) (#386)
## Summary

New \`docs/sovereignty-proof/\` surface with two committed case studies
showing where independent-vendor review caught what same-vendor review
missed:

- **2026-05-15 RPI-leanness council** — Codex (gpt-5.5) independently
reframed "RPI is waterfall" to "plan.md is an artifact-boundary bug",
turning a multi-week methodology rewrite into a single-port surgical
change (PR #275 was already in-flight implementing this).
- **2026-05-16 CDLC research council** — Two Codex judges independently
flagged the F6 session-misjoin bug in
\`cli/cmd/ao/flywheel_citation_feedback.go\` and the F7
\`hooks/citation-tracker.sh\` wiring gap. No Claude judge surfaced
either.

## Why

Council non-negotiable #2
(.agents/council/2026-05-18-validate-agentops-3.0-doctrine.md).
Mixed-model capability must be visible as load-bearing proof of the
sovereignty thesis, not buried as opt-in obscurity. The page is what
makes the sovereignty claim falsifiable + linkable from the README hero
(unblocks soc-vuu6.30).

## Mechanical guarantees

- \`scripts/validate-sovereignty-proof-citations.sh\` scans every
\`.md\` under \`docs/sovereignty-proof/\` for \`file:line\` citations
(\`path/to/file:NN\` or \`path/to/file:NN-MM\`) and verifies each
resolves at HEAD. Currently 16 citations across 3 pages.
- New CI job \`validate-sovereignty-proof-citations\` (required) wires
the script into \`validate.yml\` with broad triggers so any
referenced-surface change re-runs the gate. Added to merge-gate
\`needs:\` arrays + summary echo.
- 8-case bats regression suite at
\`tests/scripts/validate-sovereignty-proof-citations.bats\` (pass /
file-missing / line-overflow / fenced-code-block / backtick / multi-page
/ no-dir / no-markdown).
- mkdocs nav entry under Concepts → Sovereignty Proof.
- \`docs/documentation-index.md\` Concepts entry.

## Acceptance (BDD)

Given a visitor wants to verify the sovereignty claim is real, When they
click "Sovereignty proof" from README hero (slice 1, blocked on this),
Then they land on \`docs/sovereignty-proof/index.md\` showing real
\`/council --mixed\` output from the 2026-05-15 reframe AND 2026-05-16
F6+F7 findings with \`file:line\` citations and verdict file links.

## Verification

\`\`\`bash
bash scripts/validate-sovereignty-proof-citations.sh
# validate-sovereignty-proof-citations: scanned 3 pages, 16 citations
# PASS — all citations resolve.

bats tests/scripts/validate-sovereignty-proof-citations.bats
# 1..8 (all pass)
\`\`\`

Closes-scenario: soc-vuu6.32#sovereignty-proof
Bounded-context: BC1-Corpus
Evidence: docs/sovereignty-proof/index.md
Evidence: scripts/validate-sovereignty-proof-citations.sh
Evidence: tests/scripts/validate-sovereignty-proof-citations.bats
Evidence: .github/workflows/validate.yml
2026-05-21 00:48:38 +00:00