Comprehensive Documentation Update for Surface Awareness
Surface awareness shipped across three stages but the documentation doesn't reflect it. The proof data pipeline strips the `surface` field, so the website's proof pages can't display it even though the proof chain has it (88 cli, 19 website, 25 unscoped). The quickstart leads with monorepo complexity that confuses simple-app users. The troubleshooting card for "tests fail" is ordered wrong — surface config first, database not running last. The README is missing `config delete` and any mention of surfaces. Several guide and concept pages need minor corrections to stay accurate.
verdict PASSscore 25 / 25findings 4 (0 risk · 2 debt · 2 obs)duration 1h 11mrejection cycles 0shipped May 21, 2026surface website
Pipeline timeline
Intent to proven code in 1h 11m across Think, Plan, Build, and Verify.
Think10m
Plan8m
Build5m
Verify4m
Assertion ledger
25 claims, each independently verified. Showing 8 — show all →
| ID | Says | Matcher | |
|---|---|---|---|
| A001 | Proof entries include the surface field in the website data pipeline | verified | ok |
| A002 | Proof entries without a surface render null instead of undefined | verified | ok |
| A003 | Proof detail pages show which surface was verified | verified | ok |
| A004 | Proof entries without a surface do not show a surface label | verified | ok |
| A005 | Proof explorer rows show the surface as an inline badge | verified | ok |
| A006 | Surface badges match the existing stage badge styling | verified | ok |
| A007 | Proof entries without a surface do not show a surface badge | verified | ok |
| A008 | Quickstart explains how to override detected commands in three lines | verified | ok |
Findings 4 total
debtwebsite/components/docs/proof/ProofExplorer.tsx→ scope
Badge style object duplicated three times in ProofExplorer inline badge container
debtwebsite/components/docs/proof/ProofHero.tsx→ monitor
formatDuration duplicated in ProofHero — known across 4 files per proof context
obswebsite/components/docs/proof/ProofHero.tsx→ monitor
No unit tests for surface conditional rendering in ProofHero or ProofExplorer — by spec design (build-only strategy), but null/undefined/empty-string edge cases untested
obs→ closed
Spec AC2-AC15 checkboxes remain unchecked in spec.md — Plan wrote them as unchecked, Build didn't update them
Integrity seal
scopesha256:28f651f3944bb...
contractsha256:ade40088f9be4...
plansha256:56747c9a4d8d4...
specsha256:f4f06533a7dcc...
build-reportsha256:b6bfb816b2b4a...
build-datasha256:faf299dd5b2cd...
verify-reportsha256:e39050fc10b7c...
verify-datasha256:119e84f91db41...
audit cmd$ ana proof audit docs-comprehensive-update → all hashes match