Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(docs-freshness): count reading a doc as verifying it, so a checked page stops reading as stale
nirholas574337336e16
diff --git a/CLAUDE.md b/CLAUDE.mdindex 060731d4c..9cc880cbf 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -295,9 +295,9 @@ Remember stop-and-ask gate 2: production deploys need owner approval unless the1. **Prepare a CLEAN worktree: `npm run prep:worktree -- --apply`.** That is the whole step; it encodes everything below, and running it beats staging by hand. Plan first with a bare `npm run prep:worktree` (writes nothing), `--path <dir>` to stage your own tree instead of colliding with a concurrent agent on the default `/workspaces/.deploy-wt`, `--force` to replace an existing tree (refused if it holds uncommitted work). What it does: `git worktree add --detach <path> HEAD`, then hardlinks every artifact in the `ARTIFACTS` list of `scripts/prepare-deploy-worktree.mjs` with `cp -al` on the same filesystem (not just the first). Three of them are build-critical, `node_modules`, `chat/node_modules` and `character-studio/build`; the optional ones (`walk-sdk/dist`, `multiplayer/node_modules`, `animation-sources`) are what let the worktree also run the repo's own test suite, so a pre-ship `npm test` can be taken at the exact commit being shipped instead of in the shared tree. It then copies BOTH `.env` and `.env.local`. Omitting either nested one kills the build minutes in: an OOM exit 144 on the avatar-studio rebuild, or `Cannot find package '@sveltejs/vite-plugin-svelte'` on the chat build. A nested artifact that is missing from the source tree is BUILT first (`deps:chat`, `build:avatar-studio`) rather than skipped, which is the failure a hand-run `cp -al` produces on a machine that has never deployed. `.env.local` is the one that carries `DATABASE_URL`, and without it step 3's migration gate cannot read the schema state and refuses to submit. **Remove it when the deploy lands** (`git worktree remove --force <path>`); that is what step 0 exists to clean up after. See `docs/ops/gcp-production.md`.2. **Build: `npm run build:gcp`.** ORDER IS LOAD-BEARING and `build:gcp` already encodes it. Never hand-run the steps in a different order. The full chain, in order:- `check:conflicts` → `check:browser-graph` → `check:tdz-bootstrap` → `ensure:avatar-studio` → `build:info:snapshot` → `build:lib:full` (the UMD lib) → `build:avatar-sdk` → `build:chat` → `build` (the frontend `vite build`) → `publish:lib` → `build:info` → `check:dist` → `check:pages`+ `check:conflicts` → `check:browser-graph` → `check:tdz-bootstrap` → `ensure:avatar-studio` → `build:info:snapshot` → `docs:freshness` → `build:lib:full` (the UMD lib) → `build:avatar-sdk` → `build:chat` → `build` (the frontend `vite build`) → `publish:lib` → `build:info` → `check:dist` → `check:pages`- Why the order is load-bearing: `check:conflicts` runs first so an unresolved merge-conflict marker fails in seconds instead of after a full build. `check:tdz-bootstrap` sits beside it for the same reason: it refuses a browser module whose top-level bootstrap call runs above the `let`s that call writes. JavaScriptCore checks an assignment target's temporal dead zone before evaluating the right-hand side and V8 does not, so that ordering ships green on Chrome and throws "Cannot access uninitialized variable." on every Safari, which is how `/avatars/:id` went dead on iOS and macOS while every desktop check passed. `build:lib:full` writes `dist-lib/agent-3d.js`, `build:avatar-sdk` copies that bundle into `avatar-sdk/dist/index.mjs`, and the frontend `vite build` resolves `avatar-sdk/src/agent.js` against it, so both must come BEFORE `build`; skipping them shipped whatever stale `avatar-sdk/dist` the build machine happened to hold, and in a fresh worktree failed the build outright with `Could not resolve "../dist/index.mjs"` (2026-08-17). The frontend `vite build` runs with `emptyOutDir`, so it WIPES `dist/` and everything that writes into `dist/` must come after it: that is why `publish:lib`, which mirrors the UMD lib into `dist/`, follows `build` rather than sitting next to `build:lib:full`, and `check:dist` fails without that bundle present. `ensure:avatar-studio` consumes `character-studio/build` and `build:chat` consumes `chat/node_modules`, which is exactly why step 1 stages worktree artifacts. Do NOT hand-run `build:vercel` as the frontend build: it builds the SDK/lib sub-artifacts, NOT the static HTML pages, so `dist/` ends up without `/`, `/create`, etc. and `check:dist` fails.+ Why the order is load-bearing: `check:conflicts` runs first so an unresolved merge-conflict marker fails in seconds instead of after a full build. `check:tdz-bootstrap` sits beside it for the same reason: it refuses a browser module whose top-level bootstrap call runs above the `let`s that call writes. JavaScriptCore checks an assignment target's temporal dead zone before evaluating the right-hand side and V8 does not, so that ordering ships green on Chrome and throws "Cannot access uninitialized variable." on every Safari, which is how `/avatars/:id` went dead on iOS and macOS while every desktop check passed. `build:lib:full` writes `dist-lib/agent-3d.js`, `build:avatar-sdk` copies that bundle into `avatar-sdk/dist/index.mjs`, and the frontend `vite build` resolves `avatar-sdk/src/agent.js` against it, so both must come BEFORE `build`; skipping them shipped whatever stale `avatar-sdk/dist` the build machine happened to hold, and in a fresh worktree failed the build outright with `Could not resolve "../dist/index.mjs"` (2026-08-17). The frontend `vite build` runs with `emptyOutDir`, so it WIPES `dist/` and everything that writes into `dist/` must come after it: that is why `publish:lib`, which mirrors the UMD lib into `dist/`, follows `build` rather than sitting next to `build:lib:full`, and `check:dist` fails without that bundle present. `ensure:avatar-studio` consumes `character-studio/build` and `build:chat` consumes `chat/node_modules`, which is exactly why step 1 stages worktree artifacts. `docs:freshness` measures documentation drift against git history and writes `public/docs-freshness.json` plus its summary, so it must run before `build` copies `public/` into `dist/`; running it here is what keeps `/docs/freshness` and every docs-page freshness badge describing the commit actually deployed instead of whenever someone last ran it by hand. Do NOT hand-run `build:vercel` as the frontend build: it builds the SDK/lib sub-artifacts, NOT the static HTML pages, so `dist/` ends up without `/`, `/create`, etc. and `check:dist` fails.3. **Submit: `npm run deploy:gcp:submit`.** That is `db:check` (exit 4 if any migration is pending), then `check:gcloudignore`, then `audit:deploy` (no committed symlinks, no unsatisfied peer deps, no undeclared `api/` imports, decoder assets present), then the same `gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5`. `check:gcloudignore` simulates the upload and fails when a file the server imports at runtime would be excluded from the build context: an omitted `services/home-relay/src/token.js` shipped revision 00412 answering `/api/healthz` with `ERR_MODULE_NOT_FOUND` on every request (2026-09-04). Do NOT hand-run the bare `gcloud builds submit`: it is the only step that would have caught new code shipping over an old schema, and skipping it is how production ended up serving handlers that query columns their migration never applied (`column "blocks_behind" does not exist`, live on 2026-08-14). If the gate says migrations are pending, apply them first (`npm run db:status`, then `npm run db:migrate`); if it says `DATABASE_URL is not set`, step 1 did not copy `.env.local`. EVERY cloudbuild config must pin `serviceAccount: .../three-ws-build@...` (the default compute SA was deleted), and manual submits need `--substitutions=SHORT_SHA=manual$(date +%s)` when the config tags images with `$SHORT_SHA`.4. **Purge CDN: `npm run deploy:gcp:purge-cdn`.** The purge is synchronous on purpose. Do not re-add `--async`, or post-deploy checks read stale edge content and report phantom failures.5. **Verify the deploy landed.** `curl -s https://three.ws/api/version` returns the live commit SHA + Cloud Run revision, and `npm run smoke:prod` sweeps every page declared in `data/pages.json` against the live site (`deploy:gcp` runs it automatically after the purge).@@ -311,7 +311,7 @@ The whole build + submit + purge in one command: `npm run deploy:gcp:full`.- Frontend: vanilla JS modules + Vite (`npm run dev`, port 3000).- 3D: Three.js with glTF/GLB.- Backend touchpoints: serverless-style handlers in `api/`, workers in `workers/`.-- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (119 as of 2026-09-17, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.+- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (120 as of 2026-09-17, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.- **Env-var trap:** `vercel env pull` returns EMPTY for secret-type vars. Never trust a Vercel env export as complete. Production env lives on the Cloud Run service (`gcloud run services describe/update three-ws-api --region us-central1`).- Solana/agent SDKs in `sdk/`, `solana-agent-sdk/`, `agent-payments-sdk/`.- Real APIs in use: Pump.fun feed, Solana RPC, OpenAI/Anthropic via worker proxies. Never mock these.diff --git a/data/docs-freshness-reviews.json b/data/docs-freshness-reviews.jsonnew file mode 100644index 000000000..8c86745da--- /dev/null+++ b/data/docs-freshness-reviews.json@@ -0,0 +1,5 @@+{+ "$doc": "/docs/freshness",+ "$comment": "Review baselines for `npm run docs:freshness`. Without this file the only clock a doc has is its own last commit, so a page someone read end to end and found correct still measures as drifting, and the only way to clear it is a cosmetic edit that lies about what happened. A stamp here says a human or an agent checked this doc against the repo at that commit. Freshness is then measured from whichever is newer, the doc's last edit or its last review. Write stamps with `npm run docs:review -- <doc> [more docs] --note \"...\"`, never by hand: the tool resolves the commit, refuses a doc that does not exist, and keeps the ordering stable. kind `verified` means the prose was checked against the code and matched. kind `snapshot` means the doc is a dated record (an audit, an incident writeup, a finished work order) that documents a moment and must not be rewritten to match today's code, so it is never counted as drift.",+ "reviews": {}+}diff --git a/docs/doc-freshness.md b/docs/doc-freshness.mdnew file mode 100644index 000000000..30f1d983d--- /dev/null+++ b/docs/doc-freshness.md@@ -0,0 +1,131 @@+# Doc freshness: keeping documentation true to the code++Documentation rots quietly. Nobody edits a doc to make it wrong; the code it describes just+moves, and the page keeps saying what used to be true. The only signal that used to exist was+a confused reader.++This is the system that measures that rot and drains it. It runs on every doc in the+repository, needs no annotations, and publishes what it finds at+[three.ws/docs/freshness](https://three.ws/docs/freshness).++## What it measures++A doc already tells you what it is about. It names files, `npm run` commands, and `/api/`+routes in its own text. [scripts/doc-freshness.mjs](../scripts/doc-freshness.mjs) reads those+references, resolves the ones that point at real source files, and treats them as that doc's+dependencies. Then it asks git one question per dependency: was this file committed to after+the doc was last written or last reviewed?++Code that moved after the page was last checked is code the page has never been checked+against. That is the whole measurement.++Two refinements keep the ranking honest:++- **Weight by exclusivity.** `vercel.json` is named by dozens of docs. If every one of them+ lit up whenever it changed, the ranking would be red everywhere and nobody would read it. A+ file only one doc names counts fully; a file forty docs name counts for a fortieth. The doc+ that is uniquely responsible for a file surfaces above the doc that happened to mention a+ busy one.+- **Ignore generated output.** The changelog gaining an entry is not evidence that a tutorial+ went wrong, so build artifacts and the machine-translated locale tree are excluded from the+ dependency graph entirely.++## The five statuses++| Status | Meaning |+|---|---|+| **Verified** | Nothing it documents has changed since it was written or reviewed. |+| **Watch** | Some movement, below the threshold. Worth a skim, not urgent. |+| **Stale** | The equivalent of one file only this doc documents has changed. Someone should re-read it. |+| **Conceptual** | Names no code, so there is nothing to check. Not a problem, and not counted as drift. |+| **Record** | A dated record of a moment. Code moving under it is not drift. |++## Recording a review++The measurement has one blind spot that a timestamp cannot cover: reading a page carefully,+checking every claim, and finding it already correct. That is real work with no diff to show+for it. Before review stamps existed, the only ways to record it were a cosmetic edit, which+lies about what happened in the history, or leaving a permanent false positive, which teaches+people to ignore the dashboard. The last full sweep ended with eight docs stuck in exactly+that state.++A stamp is the second clock:++```bash+# You read the doc, checked it against the code, and it was right.+npm run docs:review -- docs/forge-pipeline.md --note "lanes, timeouts and failover verified"++# Several at once, against the commit you actually reviewed.+npm run docs:review -- docs/a.md docs/b.md --at 53f2a200f --note "swept with the x402 pass"++# A dated record that must not be rewritten to match today's code.+npm run docs:review -- docs/security/review-2026-06-24.md --snapshot++npm run docs:review -- --list # every stamp, newest first+npm run docs:review -- --prune # drop stamps for docs that no longer exist+```++Stamps live in [data/docs-freshness-reviews.json](../data/docs-freshness-reviews.json).+Freshness is then measured from whichever is newer, the doc's last commit or its last review.+A stamp naming a commit this repository does not have is a hard error, not a silent skip: a+baseline nobody can check would quietly suppress real drift.++Use `--snapshot` only for a doc that documents a moment rather than current behavior: a dated+audit, an incident writeup, a finished work order, an upstream issue draft, a test log.+Rewriting one of those to match today's code destroys the record it exists to keep.++## Working the queue++```bash+npm run docs:freshness # rank everything, write the report+npm run docs:freshness -- --top 40 # show more rows+npm run docs:freshness -- --doc docs/forge.md # one doc, with the exact commits to read+npm run check:docs-freshness # the gate: fail when drift exceeds the budget+```++`--doc` is the one to reach for. It prints every drifted file, the commits behind it, and+their subjects, which is the reading list for refreshing that page:++```+docs/terminal.md++ status stale (signal 1.063)+ last edited 2026-09-01 (b6194ae82), 15d ago+ documents 14 file(s)++ 2 of them changed after this doc was last edited:++ src/mission-control/index.js (1 commit)+ 2026-09-01 ab5034ed9 fix(terminal): make Mission Control honest signed out and reachable on a phone+```++Read those commits. Fix what the doc gets wrong. Then stamp it, whether or not it needed an+edit.++## Where it runs++- **`npm run gate`** runs `check:docs-freshness`, which fails when the number of stale docs+ exceeds `maxStale` in [data/docs-freshness-budget.json](../data/docs-freshness-budget.json).+ The budget is a ratchet: it goes down as docs are refreshed, and never up without a reason+ recorded in the file's own history. Normal weekly churn has headroom; a regression does not.+- **`npm run build:gcp`** runs `docs:freshness` before the frontend build, so+ `public/docs-freshness.json` and its summary are regenerated at the commit being deployed+ and copied into `dist/`. Without that step the published dashboard would show whatever the+ last person to run the command by hand happened to measure.++## What readers see++Every docs page renders a small freshness badge above the article, mounted from+[public/doc-freshness.js](../public/doc-freshness.js). It reads a compact summary+(`/docs-freshness-summary.json`, four or five fields per doc) rather than the full report,+because the full report is about a megabyte of evidence and belongs only to the dashboard.++A verified page gets a quiet line. A page whose code has moved says so plainly, names how many+files moved, and links to the evidence on [/docs/freshness](https://three.ws/docs/freshness).+It never scolds and never blocks the content: the reader came for the doc, and the honest+thing is to tell them how much to trust it while they read.++## Related++- [Guard wiring](./ops/guard-wiring.md): which checks actually run, and why this one is in `gate`+- [STRUCTURE.md](../STRUCTURE.md): where every product surface livesdiff --git a/docs/ops/guard-wiring.md b/docs/ops/guard-wiring.mdindex 617ffbc8b..d1746f4c9 100644--- a/docs/ops/guard-wiring.md+++ b/docs/ops/guard-wiring.md@@ -58,6 +58,7 @@ belongs on the deploy path, in `npm test`, or in an operator's hands.| `check:doc-media` | Every doc figure exists, matches its manifest hash, has alt text, and is actually embedded by the doc that claims it | 0 | 6.3s | `gate` || `check:images` | Every JS-rendered `<img>` in `src/` declares a `loading` attribute | 0 | 10.6s | `gate` || `audit:route-shadowing` | No `api/**` handler is unreachable behind a broader route rule | 0 | 9.3s | `gate` |+| `check:docs-freshness` | Whether each doc's prose still matches the code it names, against the budget in `data/docs-freshness-budget.json` | 0 | 11s | `gate` || `audit:deploy` | Committed symlinks, unsatisfied peers, undeclared api imports, and the Draco/KTX2 decoder assets in `dist/` | 0 | 5.2s | `deploy:gcp:submit` |`audit:deploy` is the one that is not a `gate` guard despite being green, repo-only and fast.@@ -113,6 +114,7 @@ They belong to an operator, or to a post-deploy check.|---|---|---|---|---|| `check:runnable-docs` | Executes every runnable sample in `docs/` against the live API | 1 | 15s | **manual (post-deploy).** One finding left: `/api/v1/hood-portfolios/universe` 404s because `api/v1/hood-portfolios/universe.js` landed 2026-09-07 and production runs the 2026-09-05 image. Declaring `404` would be wrong the moment it deploys. Re-run after the next deploy. || `audit:seo` | Titles, descriptions, canonicals and sitemap agreement, fetched as Googlebot | 0 | 17.2s | **manual (post-deploy).** Fetches `https://three.ws`. |+| `check:asset-encoding` | The largest compressible files under `public/`, fetched from the live site with a browser's exact `Accept-Encoding`, checking the bytes received against what the response promised | 0 | 8.4s | **manual (post-deploy).** Requests `https://three.ws`, so it measures the CDN rather than the diff: it exists because a brotli body served under an uncompressed `content-length` hung `/create/selfie` for every Chrome and Edge on 2026-09-11, and a page check never reads the largest binary on the site. Re-run after a deploy that changes a large asset. || `audit:ibm-hosted` | The IBM-hosted page against a local publisher plus live three.ws | 1 | 15.7s | **manual.** Its 6 findings are all CORS refusals of `https://three.ws/*.js` from a `127.0.0.1` publisher origin, which is the harness's origin, not a page defect. Needs the real IBM origin to mean anything. || `audit:mcp-reviewer` | Drives the published stdio MCP server the way a Connectors reviewer's host does | 0 | 11.7s | **manual (pre-submission).** Spawns the published server and hits live x402 endpoints; run before a directory submission. || `check:cron-drift` | vercel.json `crons` against what Cloud Scheduler is really running | 0 | 3.5s | **manual (needs live gcloud).** Owned by [fix-queue](../../prompts/finish/_context/fix-queue-00-INDEX.md). |@@ -160,7 +162,6 @@ viewports. They are pre-event, pre-release and incident tools.| Guard | What it checks | Exit | Runtime | Verdict ||---|---|---|---|---|| `check:docs-search` | The docs search index against `docs/**/*.md` | 1 | 11.6s | **manual (local convenience).** `public/docs-search-index.json` is gitignored on purpose (~2 MB, rewritten by every docs edit) and regenerated by `prebuild` and `postinstall`, so the shipped copy is never stale and there is nothing to commit. Its error message used to say "commit the result", which was impossible; that message is fixed. In this shared worktree it also flips red within seconds of a peer editing a doc. |-| `check:docs-freshness` | Whether a doc's prose still matches the code it names | 1 | 10.2s | **not wired: red, and the fix is large.** Over the `data/docs-freshness-budget.json` budget by 70 docs. Wiring it would block every agent on someone else's stale doc. Refresh with `npm run docs:freshness -- --doc <path>`, or raise `maxStale` with a stated reason. |### Wired, but not through another npm scriptdiff --git a/docs/start-here.md b/docs/start-here.mdindex 396fa5fd0..73703fc26 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -109,6 +109,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ- **Your agent needs market data?** → [Market Data API](./market-data-api.md) — the live feeds behind every /markets page (prices, TVL, yields, stablecoins, gas, derivatives, exploits) as 17 pay-per-call x402 endpoints from $0.001 USDC, plus the one-call `market-pulse` bundle; start at the free index [/api/x402/market](https://three.ws/api/x402/market)- **Trading Robinhood Chain?** → [Robinhood Chain on three.ws](./robinhood-chain-markets.md) — the 24/7 tokenized-equity board (live Chainlink NAV vs. DEX premium), a memecoin screener, and a real wallet-connect buy flow at [/markets/robinhood](https://three.ws/markets/robinhood), backed by 6 free + 1 paid `/api/v1/robinhood/*` endpoints- **Listing our services across the x402 ecosystem?** → [x402 distribution](./x402-distribution.md) — the operating playbook for x402scan, the CDP Bazaar, agentic.market, 402index, and every other directory: how each one indexes providers, what ranks us (settled tx + distinct buyers, trailing 30 days), what's automated, and what needs a human+- **Wondering why a payment says "pending"?** → [Pending settlement](./x402-settlement-pending.md): a Solana settle has three outcomes, not two: broadcast-but-unconfirmed is `settlement_pending`, not a failed payment. Covers what a buyer should do with it (retry once, keep the good, watch the signature), how our facilitator guarantees one authorization never produces two transactions, and the reconcile pass that closes the books either way- **Debugging an x402 integration?** → [x402 developer tools](./x402-dev-tools.md) — a free test bench: echo your payment envelope (signatures redacted), debug a failed 402 exchange into an ordered fix list, and verify a receipt's attestation and on-chain settlement, all against a live server without spending anything- **Paying from the BNB ecosystem?** → [BNB Chain payments](./bnb-payments.md) — three.ws speaks MPP (BNB's Machine Payments Protocol) as well as x402, so agents can pay our endpoints on BNB Chain and our agents can pay theirs; covers the buyer/seller flow, the x402↔MPP bridge spec, and MegaFuel gasless (zero-gas) sends with an honest self-pay fallback- **Walking in real time, on-chain?** → [The on-chain world](./bnb-world.md) — `/agora`'s Play mode has an opt-in toggle that commits your walk to a real BNB Chain contract at its live ~0.45s block cadence, gaslessly, and renders every other on-chain player as a live ghost marker; covers why this only works on BNB Chain, the architecture, and a reproducible two-wallet proof@@ -212,6 +213,7 @@ Deeper references that don't fit a track above but answer real questions:- [Use cases and example workflows](./content/use-cases/README.md): five audience-specific walkthroughs tying shipped features to concrete outcomes- [UX Flow Atlas](./ux-flows/01-onboarding-creation.md): screen-by-screen traces of the platform's core flows, starting with onboarding and creation- [Demo routes](./demo-routes.md): the canonical map of every `/demo/*` and `/demos/*` route+- [Doc freshness](./doc-freshness.md): how every doc is bound to the code it names, how drift is measured and ranked at [/docs/freshness](https://three.ws/docs/freshness), and how to record that you checked a page- [Agent trading spec](./specs/agent-trading.md): the proposed agent trading capability contract- [ERC-8004 validation attestation](./erc8004/validation-attestation.md): the attestation written when an agent registers on-chain- [zauth](./zauth/index.md): the vendored security infrastructure docs our agent auth builds ondiff --git a/package.json b/package.jsonindex 9efef5274..be87aa453 100644--- a/package.json+++ b/package.json@@ -229,6 +229,7 @@"audit:upstreams": "node scripts/audit-upstreams.mjs","audit:upstreams:map": "node scripts/audit-upstreams.mjs --map","docs:freshness": "node scripts/doc-freshness.mjs",+ "docs:review": "node scripts/docs-review.mjs","check:docs-freshness": "node scripts/doc-freshness.mjs --check","tutorials:media": "node scripts/capture-tutorial-media.mjs","tutorials:media:check": "node scripts/capture-tutorial-media.mjs --check",@@ -236,7 +237,7 @@"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs","audit:handlers": "node scripts/audit-empty-handlers.mjs","audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",- "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run audit:docs && npm run check:docs-freshness && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing","test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js","audit:mcp-golden": "node scripts/audit-mcp-golden.mjs","audit:mcp-safety": "node scripts/audit-mcp-safety.mjs",@@ -410,7 +411,7 @@"test:assets-cli": "node --test packages/assets-cli/test/*.test.js","build:info": "node scripts/write-build-info.mjs","build:info:snapshot": "node scripts/write-build-info.mjs --snapshot",- "build:gcp": "npm run check:conflicts && npm run check:browser-graph && npm run check:tdz-bootstrap && npm run ensure:avatar-studio && npm run build:info:snapshot && npm run build:lib:full && npm run build:avatar-sdk && npm run build:chat && npm run build && npm run publish:lib && npm run build:info && npm run check:dist && npm run check:pages",+ "build:gcp": "npm run check:conflicts && npm run check:browser-graph && npm run check:tdz-bootstrap && npm run ensure:avatar-studio && npm run build:info:snapshot && npm run docs:freshness && npm run build:lib:full && npm run build:avatar-sdk && npm run build:chat && npm run build && npm run publish:lib && npm run build:info && npm run check:dist && npm run check:pages","ensure:avatar-studio": "test -f character-studio/build/index.html || npm run build:avatar-studio","deploy:gcp": "npm run check:dist && npm run check:pages && npm run deploy:gcp:submit && npm run deploy:gcp:purge-cdn && npm run smoke:prod","deploy:gcp:full": "npm run build:gcp && npm run deploy:gcp",diff --git a/pages/docs-freshness.html b/pages/docs-freshness.htmlindex 83baf44d0..f54fac82b 100644--- a/pages/docs-freshness.html+++ b/pages/docs-freshness.html@@ -51,8 +51,9 @@<p class="df-lede">Every doc names the files, npm scripts, and API routes it is about. That makes each pagemeasurable: bind it to the source it names, then ask git whether that source was committed- to after the doc was last written. Code that moved since is code the page has never been- checked against.+ to after the doc was last written or last reviewed. Code that moved since is code the page+ has never been checked against. Reading a page and finding it already correct counts too:+ that check is recorded as a review, so real work never has to be faked with a cosmetic edit.</p><p class="df-meta" id="df-meta">Loading the report…</p>@@ -107,8 +108,12 @@label: 'Conceptual',blurb: 'Name no code, so nothing to check. Not a problem.',},+ snapshot: {+ label: 'Records',+ blurb: 'Dated records of a moment. Code moving under them is not drift.',+ },};- const ORDER = ['stale', 'watch', 'fresh', 'unverifiable'];+ const ORDER = ['stale', 'watch', 'fresh', 'unverifiable', 'snapshot'];let report = null;let filters = new Set();@@ -186,10 +191,38 @@return list.slice().sort(by[sort]);}+ /**+ * Who last checked this page against the code, and when.+ *+ * Drift alone cannot say whether anyone is looking after a page: a doc+ * nobody has ever opened and a doc someone read yesterday and found+ * correct both show zero drift right after an edit. The stamp is the+ * difference, so it is stated plainly rather than folded into the score.+ */+ function reviewHtml(d) {+ if (!d.review) {+ if (d.status === 'fresh' || d.status === 'unverifiable') return '';+ return `<p class="df-review">No one has recorded a check of this page against the code.+ After reading it, run <code>npm run docs:review -- ${esc(d.path)}</code>.</p>`;+ }+ const kind =+ d.review.kind === 'snapshot'+ ? 'Kept as a dated record'+ : 'Checked against the code';+ return `<p class="df-review">+ <b>${kind}</b> on ${fmtDate(d.review.date)} by ${esc(d.review.by)}+ at <code>${esc(d.review.sha)}</code>${d.review.note ? `. ${esc(d.review.note)}` : ''}+ </p>`;+ }+function rowHtml(d) {const gh = 'https://github.com/nirholas/three.ws/blob/main/' + d.path;const commands = `npm run docs:freshness -- --doc ${d.path}`;- const evidence = d.drift.length+ const evidence = d.status === 'snapshot'+ ? `<p class="df-empty-deps">This page records a moment: an audit, an incident, or a finished+ piece of work. Rewriting it to match today's code would destroy the record, so it is+ never counted as drift.</p>`+ : d.drift.length? d.drift.map((dep) => `@@ -246,6 +279,7 @@<a class="df-btn" href="${esc(gh)}" rel="noopener">Edit on GitHub</a><button class="df-btn df-copy" type="button" data-copy="${esc(commands)}">Copy the explain command</button></div>+ ${reviewHtml(d)}${evidence}</div></details>diff --git a/public/doc-freshness.js b/public/doc-freshness.jsindex 39073c4d8..b724c2fc2 100644--- a/public/doc-freshness.js+++ b/public/doc-freshness.js@@ -70,6 +70,11 @@ const TONE = {icon: '·',title: 'Conceptual page',},+ snapshot: {+ cls: 'is-record',+ icon: '#',+ title: 'A record of a moment',+ },};function fmtDate(iso) {@@ -88,13 +93,21 @@ function fmtDate(iso) {function describe(entry) {const when = fmtDate(entry.d);const files = entry.f;+ // A page someone read and confirmed is a stronger promise to the reader than+ // one that merely has not drifted yet, so the review date leads when there is+ // one. `v` is absent until a doc is stamped.+ const checked = entry.v ? `Checked against the code ${fmtDate(entry.v)}` : null;switch (entry.s) {case 'fresh':- return `Last written ${when}. None of the ${entry.n} source file${entry.n === 1 ? '' : 's'} this page documents has changed since.`;+ return checked+ ? `${checked}. None of the ${entry.n} source file${entry.n === 1 ? '' : 's'} it documents has changed since.`+ : `Last written ${when}. None of the ${entry.n} source file${entry.n === 1 ? '' : 's'} this page documents has changed since.`;case 'watch':- return `Last written ${when}. ${files} file${files === 1 ? '' : 's'} it documents changed since, so a detail here may have moved.`;+ return `${checked || `Last written ${when}`}. ${files} file${files === 1 ? '' : 's'} it documents changed since, so a detail here may have moved.`;case 'stale':- return `Last written ${when}. ${files} file${files === 1 ? '' : 's'} it documents changed since, and nobody has re-checked the page against them.`;+ return `${checked || `Last written ${when}`}. ${files} file${files === 1 ? '' : 's'} it documents changed since, and nobody has re-checked the page against them.`;+ case 'snapshot':+ return `Written ${when}. This page records what was true at that point, so it is kept as written rather than updated to match today's code.`;default:return `Last written ${when}. This page explains concepts rather than specific files, so there is nothing to check it against.`;}@@ -120,6 +133,8 @@ function injectStyle() {.doc-freshness.is-stale{border-color:rgba(255,143,107,0.34);background:rgba(255,143,107,0.07)}.doc-freshness.is-stale .doc-freshness-chip{color:#ff8f6b}.doc-freshness.is-conceptual .doc-freshness-chip{opacity:0.62}+.doc-freshness.is-record{border-color:rgba(157,184,255,0.3);background:rgba(157,184,255,0.06)}+.doc-freshness.is-record .doc-freshness-chip{color:#9db8ff}.doc-freshness-text{flex:1 1 240px;min-width:0;opacity:0.78}/* The link is a control, not prose, so it cannot be dimmed the way.doc-freshness-text is: at 0.72 it measured 4.01:1 against the banner@@ -131,6 +146,7 @@ function injectStyle() {:root[data-theme="light"] .doc-freshness.is-fresh .doc-freshness-chip{color:#0a8f66}:root[data-theme="light"] .doc-freshness.is-watch .doc-freshness-chip{color:#a16207}:root[data-theme="light"] .doc-freshness.is-stale .doc-freshness-chip{color:#c2410c}+:root[data-theme="light"] .doc-freshness.is-record .doc-freshness-chip{color:#3556a8}:root[data-theme="light"] .doc-freshness-mark span{color:#fbfbfd}@media (max-width:520px){.doc-freshness{font-size:0.76rem;padding:9px 11px}}`;diff --git a/public/docs-freshness.css b/public/docs-freshness.cssindex 7824b02f0..508270d00 100644--- a/public/docs-freshness.css+++ b/public/docs-freshness.css@@ -23,6 +23,9 @@--df-watch: #ffd166;--df-fresh: #7cf6c4;--df-unver: rgba(242, 244, 248, 0.34);+ /* Dated records: a distinct, calm hue, because a snapshot is neither a pass+ nor a warning. It is a doc that measurement does not apply to. */+ --df-record: #9db8ff;--df-radius: 14px;--df-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace;}@@ -41,6 +44,7 @@--df-watch: #a16207;--df-fresh: #0a8f66;--df-unver: rgba(13, 16, 23, 0.38);+ --df-record: #3556a8;}* {@@ -219,6 +223,9 @@ body {.df-bar .k-unverifiable {background: var(--df-unver);}+.df-bar .k-snapshot {+ background: var(--df-record);+}/* ── Controls ─────────────────────────────────────────────────────────────── */@@ -347,6 +354,34 @@ body {[data-status='unverifiable'] .df-dot {background: var(--df-unver);}+[data-status='snapshot'] .df-dot {+ background: var(--df-record);+}++/* The review line sits under the evidence: who last checked this page against+ the code, and when. It is the answer to "is anyone looking after this page?",+ which the drift number alone cannot give. */+.df-review {+ display: flex;+ flex-wrap: wrap;+ gap: 6px 10px;+ align-items: baseline;+ margin: 0 0 14px;+ padding: 9px 12px;+ border: 1px solid var(--df-line);+ border-radius: 10px;+ background: var(--df-panel);+ font-size: 0.82rem;+ color: var(--df-dim);+}+.df-review b {+ color: var(--df-text);+ font-weight: 600;+}+.df-review code {+ font-family: var(--df-mono);+ font-size: 0.94em;+}.df-name {min-width: 0;diff --git a/scripts/doc-freshness.mjs b/scripts/doc-freshness.mjsindex 93f31ca3b..eb5094415 100644--- a/scripts/doc-freshness.mjs+++ b/scripts/doc-freshness.mjs@@ -13,12 +13,18 @@* 1. Read every doc and extract the repo paths, `npm run <script>` targets,* and /api/ routes it mentions. Anything that resolves to a real file is a* DEPENDENCY of that doc: source it claims to describe.- * 2. Ask git when the doc was last edited, and whether any dependency has been- * committed to SINCE. Code that moved after the doc was last touched is- * code the doc has never been checked against.+ * 2. Ask git when the doc was last edited, take the newer of that and its last+ * recorded review (data/docs-freshness-reviews.json), and ask whether any+ * dependency has been committed to SINCE. Code that moved after a doc was+ * last written or verified is code nobody has checked the doc against.* 3. Rank by how much moved. That ranking is a work queue, and every entry* names the exact commits a writer needs to read.*+ * The review baseline is what makes the queue drainable. Reading a page and+ * finding it already correct is real work with no diff to show for it, and+ * without a stamp the only ways to record it were a cosmetic edit or leaving a+ * permanent false positive. `npm run docs:review -- <doc>` records it instead.+ ** Nothing has to be annotated: this works on all 460 existing docs today,* because it reads the references authors already write.*@@ -46,6 +52,7 @@ const OUT = path.join(ROOT, 'public/docs-freshness.json');// reader download the whole report to render one chip.const SUMMARY = path.join(ROOT, 'public/docs-freshness-summary.json');const BUDGET = path.join(ROOT, 'data/docs-freshness-budget.json');+const REVIEWS = path.join(ROOT, 'data/docs-freshness-reviews.json');const argv = process.argv.slice(2);const has = (n) => argv.includes('--' + n);@@ -227,6 +234,10 @@ function buildHistory() {).toString();const byFile = new Map();+ // Review stamps name a commit that need not have touched any doc dependency,+ // so the timestamp of every commit is indexed too, by the same abbreviation+ // `git rev-parse --short=9` produces.+ const byCommit = new Map();for (const chunk of raw.split('\x1e')) {if (!chunk.trim()) continue;const newline = chunk.indexOf('\n');@@ -234,6 +245,7 @@ function buildHistory() {const [sha, ts, ...subjectParts] = header.split('|');if (!sha) continue;const commit = { sha: sha.slice(0, 9), ts: Number(ts), subject: subjectParts.join('|') };+ byCommit.set(commit.sha, commit);if (newline === -1) continue;for (const file of chunk.slice(newline + 1).split('\n')) {if (!file) continue;@@ -242,7 +254,42 @@ function buildHistory() {list.push(commit);}}- return byFile;+ return { byFile, byCommit };+}++// ── Review baselines ─────────────────────────────────────────────────────────++/**+ * Load the review stamps and resolve each one to the commit it was taken at.+ *+ * A stamp naming a commit this repository does not have is a hard error rather+ * than a silent skip: it means someone hand-edited the store or stamped against+ * a branch that never landed, and either way the baseline it claims is fiction.+ */+function loadReviews(byCommit) {+ const store = JSON.parse(readFileSync(REVIEWS, 'utf8'));+ const reviews = new Map();+ const problems = [];+ for (const [docPath, entry] of Object.entries(store.reviews || {})) {+ if (!existsSync(path.join(ROOT, docPath))) {+ problems.push(`${docPath}: stamped, but the doc no longer exists`);+ continue;+ }+ const commit = byCommit.get(entry.commit);+ if (!commit) {+ problems.push(`${docPath}: stamped at ${entry.commit}, which is not a commit in this repo`);+ continue;+ }+ reviews.set(docPath, {+ sha: commit.sha,+ ts: commit.ts,+ date: new Date(commit.ts * 1000).toISOString().slice(0, 10),+ kind: entry.kind === 'snapshot' ? 'snapshot' : 'verified',+ by: entry.by || 'agent',+ note: entry.note || null,+ });+ }+ return { reviews, problems };}// ── Scoring ──────────────────────────────────────────────────────────────────@@ -285,7 +332,8 @@ function classify(deps, signal) {}function analyze() {- const history = buildHistory();+ const { byFile: history, byCommit } = buildHistory();+ const { reviews, problems: reviewProblems } = loadReviews(byCommit);const docs = collectDocs();const now = Math.floor(Date.now() / 1000);@@ -310,12 +358,17 @@ function analyze() {const results = [];for (const doc of parsed) {const { path: docPath, markdown, deps, lastTouched } = doc;+ const review = reviews.get(docPath) || null;+ // The baseline is whichever clock is newer. A doc edited after its last+ // review is measured from the edit; a doc verified after its last edit is+ // measured from the review.+ const baselineTs = Math.max(lastTouched?.ts || 0, review?.ts || 0);const drift = [];let commitCount = 0;let signal = 0;- if (lastTouched) {+ if (baselineTs) {for (const dep of deps) {- const since = (history.get(dep) || []).filter((c) => c.ts > lastTouched.ts);+ const since = (history.get(dep) || []).filter((c) => c.ts > baselineTs);if (!since.length) continue;commitCount += since.length;const weight = specificity(share.get(dep) || 1);@@ -349,7 +402,20 @@ function analyze() {ageDays: Math.floor((now - lastTouched.ts) / DAY),}: null,- status: classify(deps, signal),+ review: review+ ? {+ sha: review.sha,+ date: review.date,+ kind: review.kind,+ by: review.by,+ note: review.note,+ ageDays: Math.floor((now - review.ts) / DAY),+ }+ : null,+ // A snapshot documents a moment, so today's code cannot make it wrong.+ // Its dependencies stay visible (the evidence is still useful) but it is+ // never ranked as work.+ status: review?.kind === 'snapshot' ? 'snapshot' : classify(deps, signal),deps: deps.length,depFiles: deps.slice().sort(),driftFiles: drift.length,@@ -361,7 +427,7 @@ function analyze() {}results.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));- return results;+ return { results, reviewProblems };}/** The published URL a doc reads at, so the dashboard can link straight to it. */@@ -408,39 +474,81 @@ function explain(results, docPath) {console.log(` last edited ${r.lastTouched?.date} (${r.lastTouched?.sha}), ${r.lastTouched?.ageDays}d ago`,);+ if (r.review) {+ const note = r.review.note ? `: ${r.review.note}` : '';+ console.log(+ ` last reviewed ${r.review.date} (${r.review.sha}) by ${r.review.by}, ` ++ `${r.review.kind}${note}`,+ );+ }console.log(` documents ${r.deps} file(s)`);+ if (r.status === 'snapshot') {+ console.log(+ `\n A dated record, not a description of current behavior, so code moving under it ` ++ `is not drift. Stamped with \`npm run docs:review -- ${r.path} --snapshot\`.\n`,+ );+ return;+ }if (!r.drift.length) {console.log(`\n Nothing it documents has changed since. This doc is verified.\n`);return;}- console.log(`\n ${r.driftFiles} of them changed after this doc was last edited:\n`);+ const clock =+ r.review && r.review.date >= (r.lastTouched?.date || '') ? 'reviewed' : 'edited';+ console.log(`\n ${r.driftFiles} of them changed after this doc was last ${clock}:\n`);for (const d of r.drift) {const shared = d.sharedWith ? `, also documented by ${d.sharedWith} other doc(s)` : '';console.log(` ${d.file} (${d.total} commit${d.total === 1 ? '' : 's'}${shared})`);for (const c of d.commits) console.log(` ${c.date} ${c.sha} ${c.subject}`);console.log('');}+ console.log(+ ` Read those commits, fix anything the doc gets wrong, then record the check:\n` ++ ` npm run docs:review -- ${r.path} --note "<what you checked>"\n`,+ );}// ── Entry ────────────────────────────────────────────────────────────────────-const results = analyze();+const { results, reviewProblems } = analyze();const totals = {docs: results.length,stale: results.filter((r) => r.status === 'stale').length,watch: results.filter((r) => r.status === 'watch').length,fresh: results.filter((r) => r.status === 'fresh').length,unverifiable: results.filter((r) => r.status === 'unverifiable').length,+ snapshot: results.filter((r) => r.status === 'snapshot').length,+ reviewed: results.filter((r) => r.review).length,trackedFiles: new Set(results.flatMap((r) => r.depFiles)).size,};+/**+ * A broken stamp is worse than no stamp: it claims a baseline nobody can check,+ * and it silently suppresses drift for the doc it names. Both modes report it,+ * and the gate refuses to pass with one outstanding.+ */+function printReviewProblems() {+ if (!reviewProblems.length) return;+ console.error(`\n${reviewProblems.length} broken review stamp(s):`);+ for (const problem of reviewProblems) console.error(` ${problem}`);+ console.error(+ `Fix data/docs-freshness-reviews.json, or drop the dead entries with ` ++ `\`npm run docs:review -- --prune\`.`,+ );+}+if (has('check')) {const budget = JSON.parse(readFileSync(BUDGET, 'utf8'));const over = totals.stale - budget.maxStale;console.log(`docs freshness: ${totals.stale} stale / ${totals.watch} watch / ${totals.fresh} fresh ` +- `/ ${totals.unverifiable} unverifiable (budget ${budget.maxStale} stale)`,+ `/ ${totals.unverifiable} unverifiable / ${totals.snapshot} snapshot ` ++ `(budget ${budget.maxStale} stale)`,);+ if (reviewProblems.length) {+ printReviewProblems();+ process.exit(1);+ }if (over > 0) {printTable(results, 15);console.error(@@ -485,11 +593,19 @@ writeFileSync(totals,// Short keys: this file is fetched by every docs page that renders a// badge, so its bytes are on the reader's critical path.- // s status, g signal, d date last edited, f files drifted, n deps known+ // s status, g signal, d date last edited, f files drifted, n deps known,+ // v date last reviewed (absent when the doc has never been stamped)docs: Object.fromEntries(results.map((r) => [r.path,- { s: r.status, g: r.signal, d: r.lastTouched?.date || null, f: r.driftFiles, n: r.deps },+ {+ s: r.status,+ g: r.signal,+ d: r.lastTouched?.date || null,+ f: r.driftFiles,+ n: r.deps,+ ...(r.review ? { v: r.review.date } : {}),+ },]),),},@@ -501,7 +617,9 @@ writeFileSync(console.log(`Analyzed ${totals.docs} docs against ${totals.trackedFiles} source files.\n` +` fresh ${totals.fresh} watch ${totals.watch} stale ${totals.stale} ` +- `unverifiable ${totals.unverifiable}`,+ `unverifiable ${totals.unverifiable} snapshot ${totals.snapshot}\n` ++ ` ${totals.reviewed} doc(s) carry a review stamp.`,);+printReviewProblems();printTable(results, Number(opt('top', 20)));console.log(`\nWrote ${path.relative(ROOT, OUT)} (read by /docs/freshness).`);diff --git a/scripts/docs-review.mjs b/scripts/docs-review.mjsnew file mode 100644index 000000000..bd49228ae--- /dev/null+++ b/scripts/docs-review.mjs@@ -0,0 +1,176 @@+#!/usr/bin/env node+/**+ * Record that a doc was read against the code and found correct.+ *+ * `npm run docs:freshness` measures drift from the doc's last commit, which is+ * the only clock git gives it. That clock is wrong in one common case: someone+ * reads a page end to end, checks every claim against the source, and finds+ * nothing to fix. The work happened, the doc is verified, and the measurement+ * still says stale. The last full sweep ended with 8 docs in exactly that state,+ * and the only ways out were a cosmetic edit (a lie in the history) or leaving a+ * permanent false positive that teaches people to ignore the dashboard.+ *+ * A review stamp is the missing clock. It records WHO checked WHAT against WHICH+ * commit, and freshness is then measured from whichever is newer, the doc's last+ * edit or its last review.+ *+ * Usage:+ * npm run docs:review -- docs/forge.md --note "checked lanes and timeouts"+ * npm run docs:review -- docs/a.md docs/b.md --at 1a2b3c4d5 stamp at a specific commit+ * npm run docs:review -- docs/security/review-2026-06-24.md --snapshot+ * npm run docs:review -- --list what is stamped, newest first+ * npm run docs:review -- --prune drop stamps for docs that no longer exist+ *+ * `--snapshot` is for a doc that records a moment rather than describing current+ * behavior: a dated audit, an incident writeup, a finished work order, an+ * upstream issue draft. Rewriting one to match today's code would destroy the+ * record, so it is never counted as drift.+ *+ * Writes data/docs-freshness-reviews.json, read by scripts/doc-freshness.mjs.+ */++import { execFileSync } from 'node:child_process';+import { existsSync, readFileSync, writeFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const STORE = path.join(ROOT, 'data/docs-freshness-reviews.json');++const argv = process.argv.slice(2);+const has = (name) => argv.includes('--' + name);+const opt = (name) => {+ const i = argv.indexOf('--' + name);+ return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : null;+};++const git = (args) => execFileSync('git', args, { cwd: ROOT }).toString().trim();++function loadStore() {+ const raw = JSON.parse(readFileSync(STORE, 'utf8'));+ raw.reviews ||= {};+ return raw;+}++/** Stable on disk: sorted by path, so two agents stamping different docs never fight. */+function saveStore(store) {+ const sorted = {};+ for (const key of Object.keys(store.reviews).sort()) sorted[key] = store.reviews[key];+ store.reviews = sorted;+ writeFileSync(STORE, JSON.stringify(store, null, '\t') + '\n');+}++function commitInfo(ref) {+ try {+ const [sha, ts] = git(['show', '-s', '--format=%h|%ct', '--abbrev=9', ref]).split('|');+ return { sha, date: new Date(Number(ts) * 1000).toISOString().slice(0, 10) };+ } catch {+ console.error(`Not a commit in this repository: ${ref}`);+ process.exit(2);+ }+}++function list(store) {+ const rows = Object.entries(store.reviews).map(([docPath, r]) => ({+ docPath,+ ...r,+ ...commitInfo(r.commit),+ }));+ if (!rows.length) {+ console.log('No doc has been stamped yet. Stamp one with `npm run docs:review -- <doc>`.');+ return;+ }+ rows.sort((a, b) => b.date.localeCompare(a.date) || a.docPath.localeCompare(b.docPath));+ console.log(`${rows.length} stamped doc(s):\n`);+ for (const row of rows) {+ console.log(` ${row.date} ${row.kind.padEnd(9)} ${row.docPath}`);+ if (row.note) console.log(` ${row.note}`);+ }+}++function prune(store) {+ const gone = Object.keys(store.reviews).filter((p) => !existsSync(path.join(ROOT, p)));+ if (!gone.length) {+ console.log('Every stamped doc still exists. Nothing to prune.');+ return;+ }+ for (const p of gone) delete store.reviews[p];+ saveStore(store);+ console.log(`Pruned ${gone.length} stamp(s) for deleted docs:\n ${gone.join('\n ')}`);+}++const store = loadStore();++if (has('list')) {+ list(store);+ process.exit(0);+}+if (has('prune')) {+ prune(store);+ process.exit(0);+}++// Everything that is not a flag or a flag's value is a doc to stamp.+const flagValues = new Set([opt('note'), opt('at'), opt('by')].filter(Boolean));+const docs = argv.filter((a) => !a.startsWith('--') && !flagValues.has(a));++if (!docs.length) {+ console.error(+ 'Nothing to stamp. Usage: npm run docs:review -- <doc.md> [more docs] [--note "..."] ' ++ '[--at <commit>] [--snapshot]\n' ++ ' npm run docs:review -- --list | --prune',+ );+ process.exit(2);+}++const missing = docs.filter((d) => !existsSync(path.join(ROOT, d)));+if (missing.length) {+ console.error(`No such doc:\n ${missing.join('\n ')}`);+ process.exit(2);+}++const notMarkdown = docs.filter((d) => !d.endsWith('.md'));+if (notMarkdown.length) {+ console.error(`Only markdown docs can be stamped:\n ${notMarkdown.join('\n ')}`);+ process.exit(2);+}++const at = commitInfo(opt('at') || 'HEAD');+const kind = has('snapshot') ? 'snapshot' : 'verified';+const note = opt('note');+const by = opt('by') || 'agent';++// A doc with uncommitted edits is stamped against the commit the reviewer read,+// which is what `--at` is for, but the edit itself is not in that commit yet.+// Freshness takes the newer of the doc's last commit and its review, so the+// stamp cannot mask the pending edit. Saying so keeps the reviewer honest about+// which one they are recording.+const dirty = docs.filter((d) => {+ try {+ return git(['status', '--porcelain', '--', d]).length > 0;+ } catch {+ return false;+ }+});++for (const docPath of docs) {+ store.reviews[docPath] = {+ commit: at.sha,+ kind,+ by,+ ...(note ? { note } : {}),+ };+}+saveStore(store);++console.log(+ `Stamped ${docs.length} doc(s) as ${kind} at ${at.sha} (${at.date}):\n ${docs.join('\n ')}`,+);+if (dirty.length) {+ console.log(+ `\n${dirty.length} of them have uncommitted edits. Commit those too: freshness reads the ` ++ `newer of the doc's last commit and this stamp, so an uncommitted fix still measures as ` ++ `pending work.`,+ );+}+console.log('\nRe-measure with `npm run docs:freshness`.');diff --git a/tests/guard-wiring.test.js b/tests/guard-wiring.test.jsindex 7a7016411..0fae3f79c 100644--- a/tests/guard-wiring.test.js+++ b/tests/guard-wiring.test.js@@ -30,6 +30,10 @@ const GATE_GUARDS = {'audit:motion': 'scripts/build-motion-signatures.mjs','audit:tour-global': 'scripts/sync-tour-global.mjs','audit:route-shadowing': 'scripts/audit-route-shadowing.mjs',+ // Wired once the stale backlog was refreshed and review baselines existed. Its+ // budget (data/docs-freshness-budget.json) is what keeps it green in a shared+ // worktree: normal code churn has headroom, a real regression does not.+ 'check:docs-freshness': 'scripts/doc-freshness.mjs',};describe('guards wired into npm run gate', () => {