Skip to content

docs: add the SSOT receipts section — 5 of 9 claims were missing from the README - #442

Open
yakimoto wants to merge 1 commit into
mainfrom
docs/readme-ssot-receipts
Open

yakimoto wants to merge 1 commit into
mainfrom
docs/readme-ssot-receipts

Conversation

@yakimoto

@yakimoto yakimoto commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

User description

wave-context's E-WATCH surveyor reports this repo at DRIFT: 5/9 SSOT needles missing. The alarm was real and unread — the watcher's dedupe guard filed a fresh issue daily until nine of them buried the signal (wave-av/claude-workstation#3553 fixes the watcher, #3066 is the standing issue).

Additive on purpose

The obvious remedy — replace README.md with npm run generate wave-realtime-edge output — was measured and rejected. It retains every heading but runs 118 lines against this README's 136, and the diff shows it would delete 45 non-blank lines of curated content: the entire Surface/Path/Status table with its armed dates, the substrate note, and several capability rows.

Deleting 45 lines of accurate public documentation to satisfy 5 needles is worse than the drift.

So the missing claims were located, not regenerated: four of the five live in the generated ## The receipts section, which this README did not carry at all; the fifth is a single capability row. Both lifted in verbatim.

Verified

  • 5/5 needles present, checked against the surveyor's own reported list rather than a reading of the facts schema.
  • Zero lines removed — asserted mechanically (every non-blank old line still appears), not by eyeballing the diff.

136 → 147 lines. README only.

🤖 Generated with Claude Code


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.


Note

Low Risk
Documentation-only README addition; no code, auth, or runtime behavior changes.

Overview
Adds a The receipts table to README.md so SSOT verifier needles (auth at the gateway, rt.wave.online, x402 session events, protocol-plane-layer-1, custom SFU/ROOM DO) are present without regenerating or deleting existing README content.

Reviewed by Cursor Bugbot for commit 05f3fef. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary by Sourcery

Add the missing SSOT receipts to the README while preserving its existing curated documentation.

New Features:

  • Add an SSOT receipts section to the README documenting verification evidence for five repository claims.

Bug Fixes:

  • Restore the five claims identified as missing by the SSOT surveyor without removing existing README content.

Documentation:

  • Expand the README with authentication, routing, event, repository-tag, and SFU capability receipts.

Review in cubic


CodeAnt-AI Description

Add SSOT verification receipts to the README

What Changed

  • Added a “The receipts” section listing five key project claims and how each is verified
  • Documented authentication, routing, metered events, protocol classification, and the custom SFU setup
  • Preserved the existing README content while making these claims visible to readers

Impact

✅ Clearer project capability verification
✅ Easier validation of deployment and protocol claims
✅ Fewer missing SSOT claims in the README

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

… the README

wave-context's E-WATCH surveyor reports this repo at DRIFT: 5/9 SSOT needles missing. The alarm
was real and unread — the watcher's dedupe guard was broken and filed a fresh issue every day
until nine of them buried the signal (wave-av/claude-workstation#3553 fixes the watcher, #3066
is the standing issue).

THIS IS ADDITIVE ON PURPOSE. The obvious remedy — replace README.md with
`npm run generate wave-realtime-edge` output — was measured and REJECTED: it retains every
heading but is 118 lines against this README's 136, and the diff shows it would DELETE 45
non-blank lines of curated content, including the entire Surface/Path/Status table with its
armed dates, the substrate note, and several capability rows. Deleting 45 lines of accurate
public documentation to satisfy 5 needles is a worse outcome than the drift.

So the missing claims were located rather than regenerated. Four of the five live in the
generated `## The receipts` section, which this README did not carry at all; the fifth is a
single capability row. Both were lifted in verbatim.

Verified:
  - all 5 needles the surveyor named are present, checked against the surveyor's OWN reported
    list rather than a reading of the facts schema;
  - ZERO lines of the previous README were removed — asserted mechanically by checking every
    non-blank old line still appears, not by reading the diff.

136 -> 147 lines. README only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@codeant-ai

codeant-ai Bot commented Aug 24, 2026

Copy link
Copy Markdown

🤖 CodeAnt AI — Review Status

Status Commit Started (UTC) Finished (UTC)
✅ Reviewed your PR 05f3fef Aug 24, 2026 · 03:30 03:30

@sourcery-ai

sourcery-ai Bot commented Aug 24, 2026

Copy link
Copy Markdown
Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Adds an SSOT receipts section to the README so that all SSOT claims are present without removing any existing curated documentation, and ensures the SSOT surveyor can verify 5/5 required claims from this repo.

File-Level Changes

Change Details Files
Introduce an SSOT receipts section documenting how key operational claims are automatically verified against the repo and runtime configuration.
  • Insert a new ## The receipts section after the capabilities table, describing SSOT verification behavior.
  • Add a claims table mapping each operational claim to its verification method (grep against docs/REALTIME.md, wrangler.toml, capabilities.json, or preview badge).
  • Include the previously missing capability claim about the custom SFU on a Cloudflare Durable Object as a preview-only receipt.
README.md
Preserve existing README content while aligning it with SSOT surveyor expectations.
  • Ensure no existing non-blank lines are removed while adding the receipts section, increasing README length from 136 to 147 lines.
  • Maintain all existing headings, capability rows, and curated narrative content around the new section.
  • Remove a trailing blank line at the end of the README to keep formatting tidy without affecting documented content.
README.md

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@cursor

cursor Bot commented Aug 24, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_d03db118-44ee-4841-b775-071bfacda62f)

@coderabbitai

coderabbitai Bot commented Aug 24, 2026

Copy link
Copy Markdown

Warning

Review limit reached

Next included review available in 55 minutes.

View limit details

Limit details: You’ve used the included review currently available. Your 91 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d6673307-6c33-4ef2-84af-f7b6afa1a257

📥 Commits

Reviewing files that changed from the base of the PR and between 3902a75 and 05f3fef.

📒 Files selected for processing (1)
  • README.md

Comment @coderabbitai help to get the list of available commands.

@codeant-ai codeant-ai Bot added the size:S This PR changes 10-29 lines, ignoring generated files label Aug 24, 2026
@qodo-code-review

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can switch off images and animations for a plain-text comment

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@gitar-bot

gitar-bot Bot commented Aug 24, 2026

Copy link
Copy Markdown

Note

Automatic reviews are paused because your team has used its included automatic processing for this billing period (headroom scales with your seat count). You can still comment "Gitar review" to run one anytime, and automatic reviews resume on their own by September 1. Add seats for more headroom.
Learn more

Code Review ✅ Approved

Adds the missing SSOT receipts section to the README to resolve survey drift without deleting existing curated content. No issues found.

Options

Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Compact
gitar display:verbose         

Was this helpful? React with 👍 / 👎 | Gitar

@macroscopeapp

macroscopeapp Bot commented Aug 24, 2026

Copy link
Copy Markdown

Approvability

Verdict: Would Approve

Macroscope's review found this PR approvable — This PR adds a small, self-contained receipts section to README.md and changes no executable code or production configuration. The modified file is owned by the author, and no runtime impact is present.

Not approved because:

  • Credit balance exhausted. Approvability relies on correctness review in order to determine eligibility

Review your spending limits in Billing settings. You can add or adjust custom eligibility rules. Learn more.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.


Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Add SSOT “The receipts” section to README to eliminate verification drift

📝 Documentation 🕐 Less than 10 minutes

Grey Divider

AI Description

• Add missing SSOT “receipts” claim table to README to satisfy verifier needles.
• Keep existing curated README content intact; avoid regenerating from template output.
• Document how each claim is verified (source file grep / preview status).
Diagram

graph TD
  R["README.md"] --> V(["SSOT verifier"]) --> S["Source files"]
  S --> D["docs/REALTIME.md"]
  S --> W["wrangler.toml"]
  S --> C["capabilities.json"]
  R --> U["Repo visitors"]
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Regenerate README from generator output
  • ➕ Guarantees README matches the generator’s canonical SSOT output
  • ➕ Reduces manual drift risk long-term
  • ➖ Would remove substantial curated content (e.g., Surface/Path/Status table)
  • ➖ Creates noisy diffs and potential loss of intentional human-authored context
2. Automate “receipts” injection (generated snippet include)
  • ➕ Keeps curated README while ensuring receipts stay in sync
  • ➕ Smaller future diffs; reduces ongoing manual maintenance
  • ➖ Requires build/CI or docs tooling changes to support partial generation
  • ➖ Adds process complexity for what is currently a one-time drift fix

Recommendation: The PR’s additive approach is the best immediate fix: it restores the missing SSOT needles without deleting curated README content and keeps the change surface small. If drift recurs, consider a follow-up to auto-inject only the receipts subsection rather than regenerating the full README.

Files changed (1) +12 / -1

Documentation (1) +12 / -1
README.mdAdd SSOT “The receipts” claim/verification table +12/-1

Add SSOT “The receipts” claim/verification table

• Introduces a new “## The receipts” section containing a claim-to-verification mapping table, restoring previously missing SSOT needles. Also removes a trailing blank line at EOF while leaving existing README content intact.

README.md

@qodo-code-review

Copy link
Copy Markdown

Qodo Fixer

No findings are available for this PR yet. Findings appear here once Qodo has reviewed the PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:S This PR changes 10-29 lines, ignoring generated files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant