Verification And Tests

Verification in this repository has two meanings that must stay separate. The current website repository verifies documentation, rendering, linting, search coverage, and build integrity. Future protocol implementations must verify settlement rules, cryptography, storage proofs, wallet behavior, data availability, useful-work evidence, privacy, and service boundaries. Passing website verification is necessary for docs quality, but it is not protocol verification.

This page describes the local gates that exist today and the future tests that should be added when implementation surfaces exist. It also records the Phase 002 review discipline: source anchors, maturity labels, repeated execution review, doublecheck, and explicit evidence gates.

Verification Ladder

flowchart TD A[Docs source checks] --> B[Lint] B --> C[Search coverage] C --> D[Production build] D --> E[Phase-specific content acceptance] E --> F[GSD execution review loop] F --> G[Doublecheck and source audit] G --> H[Future protocol test suites] H --> I[Security and privacy validation] style A fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style B fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style C fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style D fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style E fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style F fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style G fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style H fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px,color:#4A148C style I fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238

The ladder is ordered from current local checks to future protocol checks. Today, npm run verify reaches lint, search coverage, and build through scripts/verify.sh. Phase 002 adds additional scoped checks for docs pages. Future protocol repositories must add deeper suites after the implementation exists.

Current Local Commands

The current command surface is defined in package.json:

npm run lint runs ESLint.
npm run verify:search runs the search coverage verifier.
npm run build builds the Next.js site.
npm run verify runs bash ./scripts/verify.sh.

scripts/verify.sh is the wrapper gate. It runs lint, search coverage, and build. That is the command to use before closing website documentation work. When npm run verify passes, the site is locally consistent enough to build and serve its docs content. It does not prove target protocol behavior.

The repo currently produces broad Turbopack filesystem tracing warnings in known config/content paths during build. Those warnings should be monitored, but they are separate from Phase 002 docs correctness unless the current plan introduces new warnings.

Content-Source Checks

Phase 002 documentation work requires stronger content checks than the base repository wrapper. For advanced developer pages, local acceptance should verify at least:

Exact YAML frontmatter fields required by 002-TODO.md.
toc: true on scoped pages.
mdi:alphabet-*-box-outline icons instead of the older mdi:alpha-*-circle family.
Non-index pages have substantive body content.
Every scoped page has ## Read Next.
Every scoped page has ## Evidence and Further Reading.
Source links include local files or whitepaper sections required by the TODO.
Current repo claims point to real files such as src/lib/content/, src/app/api/, config/, package.json, or scripts/verify.sh.
Future protocol claims are labeled as target architecture when implementation is absent.
All content/**/index.md files remain frontmatter-only under the user’s override.

These checks are deterministic and local. They can be implemented with rg, wc, short shell scripts, or future docs-specific validation scripts. They should not rely on a model to decide whether a required heading exists.

GSD Review Loop

Every Phase 002 plan-level verify section requires the repository prompt /.github/prompts/gsd-review-tasks-execution.prompt.md, also named /GSD-Review-Tasks-Execution, to be run inline in YOLO mode at least three distinct times. The execution contract is strict:

Open the prompt file locally.
Review the implemented plan scope against the plan and TODO.
Fix all issues and warnings found in scope.
Run at least three distinct passes.
Stop only after at least two consecutive passes show no significant issues.
Do not satisfy the prompt by shelling out to external model CLIs or APIs.

For documentation-only plans, the review focuses on source coverage, concept drift, unsupported implementation claims, broken anchors, missing headings, frontmatter drift, and verification evidence. Crypto or security specialist review is triggered only if the plan changes code or claims that require that surface.

Doublecheck

The user has asked to use doublecheck wherever possible. In this phase, doublecheck is used as a source audit for repo-specific claims. The workflow is: extract claims, verify local claims against workspace files first, use external sources only for standards or facts not resolved locally, and record whether claims are verified, plausible, contradicted, or unsupported.

For these docs, doublecheck should confirm that pages do not invent files, commands, endpoints, or shipped protocol behavior. It should also confirm that external references such as JSON-RPC and RFC 8259 are official standards pages when cited.

Security and Privacy Review

The Privacy Threat Model section on validation makes privacy testing explicit. Documentation should call out privacy risks instead of implying they are solved by architecture diagrams. Future implementation tests should include wallet UX, telemetry, timing leakage, support export, selective disclosure, and recovery scenarios. Website docs can describe those requirements, but only protocol and wallet implementations can prove them.

Security review should be triggered when code changes expose new request surfaces, authentication flows, secret handling, wallet actions, or external integrations. For this website docs work, the main security risk is misdocumentation: telling builders that an unimplemented service, wallet, or API is safe or live.

Future Protocol Tests

Future protocol tests should be added beside the implementation they verify. Likely suites include:

Storage root and HJMT-style proof tests.
Replay-protection and nullifier-domain tests.
Package validation and batch ordering tests.
Data availability publication and retrieval tests.
Checkpoint artifact and maturity tests.
Wallet-local possession and disclosure tests.
WASM wallet storage, prompt, and recovery tests.
RPC request validation and error hygiene tests.
Useful-work evidence, scoring, challenge, slashing, and appeal tests.
Governance and genesis configuration tests.

These are not website tests. They should not be faked by adding Markdown examples. When implementation code exists, tests should use real project primitives and deterministic fixtures.

Evidence Gate

Before closing a docs plan, use this evidence gate:

Run scoped deterministic checks for the files changed by the plan.
Run the required three-pass inline GSD review loop.
Fix all findings.
Run npm run verify.
Record summary evidence in the plan summary.
Update 002-review-log.md, 002-doublecheck-report.md, ROADMAP.md, and STATE.md.

If any gate fails, do not move to the next plan until the issue is fixed or the blocker is explicitly recorded.

What Passing Means

Passing npm run verify means the website passed its configured local checks. Passing the Phase 002 scoped checks means the edited docs pages meet the current plan’s structural and source-coverage expectations. Passing the inline GSD review loop means no significant in-scope issues were found in the last two review passes. These are strong documentation signals, but they are still not protocol security proofs.

Future protocol code should define its own pass meanings. A storage test pass should mean roots and proofs behaved as expected. A wallet test pass should mean authorization, disclosure, recovery, and privacy cases passed under real wallet primitives. A useful-work test pass should mean evidence and dispute logic behaved as specified. Keeping those meanings separate makes release notes, audits, and user claims safer.

Failure Handling

When a verification command fails, fix the cause before moving forward. Do not work around a failing docs check by weakening the claim it was supposed to protect unless the TODO or plan actually changed. If a check cannot be run, the summary should state the exact command, blocker, and residual risk. Silent skips are not acceptable evidence gates.

Review Evidence Records

Plan summaries should record what was checked, not just that review happened. Useful evidence includes word-count results, frontmatter checks, source-anchor checks, index.md body checks, review-run identifiers, doublecheck claim IDs, and the final npm run verify result. This evidence makes the next plan safer because it can resume from concrete facts instead of reconstructing intent from diffs alone. It also makes regressions easier to isolate.

Evidence and Further Reading

Use the source bullets below as an audit checklist, not decoration: when reusing this page, preserve the named section scope, the responsible actor, and the split between live repository evidence, target architecture, and open design work.

scripts/verify.sh for the current local wrapper that runs lint, search coverage, and build.
package.json for the current npm run verify, npm run lint, npm run build, and npm run verify:search commands.
.github/prompts/gsd-review-tasks-execution.prompt.md for the inline review loop contract.
.github/skills/doublecheck/SKILL.md for the source-audit workflow.
Privacy Threat Model And Metrics section 10 for privacy simulation and validation expectations.
Proof-of-Useful-Work Whitepaper section 5 for useful-work proof and evidence concepts.

Z00ZBlockchain