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
test(docs-freshness): guard the review store and add the sweep workflow
nirholasb958d6d1574c
diff --git a/.claude/workflows/docs-freshness.js b/.claude/workflows/docs-freshness.jsnew file mode 100644index 000000000..91281e2b5--- /dev/null+++ b/.claude/workflows/docs-freshness.js@@ -0,0 +1,110 @@+export const meta = {+ name: 'docs-freshness',+ description: 'Refresh the docs that describe code which moved, then record each review so the check stays drainable',+ whenToUse: 'Run when `npm run check:docs-freshness` is over budget, or on a routine pass to keep the corpus true. Invoke with: run the docs-freshness workflow. Optional args: { limit: number } for how many stale docs to take this run (default 12), { paths: string[] } to review specific docs instead of the ranked queue.',+ phases: [+ { title: 'Queue', detail: 'one agent ranks the stale docs and splits them into review batches' },+ { title: 'Review', detail: 'one agent per batch, each checking its docs against the commits that drifted' },+ { title: 'Stamp', detail: 'one agent records every verdict with npm run docs:review' },+ ],+}++// The queue agent reads the ranked report rather than guessing which docs matter:+// scripts/doc-freshness.mjs already weights each drifted file by how exclusively+// a doc claims it, so its order is the work order.+const QUEUE_SCHEMA = {+ type: 'object',+ required: ['batches'],+ properties: {+ batches: {+ type: 'array',+ description: 'review batches, each a related group of docs so one agent can share context across them',+ items: {+ type: 'object',+ required: ['area', 'docs'],+ properties: {+ area: { type: 'string', description: 'what these docs are about, e.g. "forge and avatars"' },+ docs: { type: 'array', items: { type: 'string' }, description: 'repo-relative doc paths' },+ },+ },+ },+ },+}++// EDITED / VERIFIED / SNAPSHOT is the whole vocabulary. A doc that was read and+// found correct is as finished as one that needed a fix, which is the point of+// the review baseline: without VERIFIED the queue can only be drained by editing.+const REVIEW_SCHEMA = {+ type: 'object',+ required: ['verdicts'],+ properties: {+ verdicts: {+ type: 'array',+ items: {+ type: 'object',+ required: ['path', 'verdict', 'note'],+ properties: {+ path: { type: 'string' },+ verdict: { type: 'string', enum: ['EDITED', 'VERIFIED', 'SNAPSHOT'] },+ note: { type: 'string', description: 'one sentence: what was wrong, or why it is still right' },+ },+ },+ },+ },+}++const RULES = `Rules that apply to every doc you touch:+- Read /workspaces/three.ws/CLAUDE.md "Tone" and "Documentation" first. The em-dash and en-dash characters are banned everywhere you write.+- \`node scripts/doc-freshness.mjs --doc <path>\` lists every drifted file and the commits behind it. Read those commits (\`git show <sha> -- <file>\`) AND the current source before deciding anything.+- Check every concrete claim: routes, env vars, script and function names, behavior, numbers, fees, file paths, UI copy. Fix what is wrong or materially missing. Keep the doc's structure and voice, correct rather than rewrite, never pad. Every path and link you write must resolve.+- A doc that records a moment (a dated audit, an incident writeup, a finished work order, an upstream issue draft, a test log) must NOT be rewritten to match today's code. That is a SNAPSHOT.+- This worktree is shared with other agents. Edit only the docs you were given. Never run git add/commit/checkout/stash/reset. Never edit source code. Never execute a transaction or spend.+- When done, run \`npm run check:rules -- --paths <docs you edited>\` and fix what it flags.`++phase('Queue')+const limit = (args && args.limit) || 12+const paths = (args && args.paths) || null++const queue = await agent(+ paths+ ? `Group these docs into batches of at most 5, by subject area, so one reviewer per batch can share context: ${paths.join(', ')}. Return the batches.`+ : `Run \`npm run docs:freshness\` in the repository root, then read public/docs-freshness.json. Take the ${limit} docs with status "stale" and the highest signal. Group them into batches of at most 5 by subject area (docs about the same product surface belong together, so one reviewer reads that surface's code once). Return the batches. Do not edit any file.`,+ { label: 'queue:stale-docs', schema: QUEUE_SCHEMA }+)++const reviewed = await parallel(+ queue.batches.map(batch => () =>+ agent(+ `Refresh these stale three.ws docs (${batch.area}): ${batch.docs.join(', ')}.\n\n${RULES}\n\nReturn one verdict per doc, covering every doc listed above exactly once.`,+ { label: `review:${batch.area}`, phase: 'Review', schema: REVIEW_SCHEMA }+ ).then(r => r.verdicts)+ )+)++const verdicts = reviewed.flat().filter(Boolean)+if (!verdicts.length) return { reviewed: 0, note: 'no doc came back with a verdict' }++// Stamping is centralized in one agent on purpose: data/docs-freshness-reviews.json+// is a single file, and several agents writing it at once would lose stamps to a+// last-write-wins race.+phase('Stamp')+const verified = verdicts.filter(v => v.verdict !== 'SNAPSHOT').map(v => v.path)+const snapshots = verdicts.filter(v => v.verdict === 'SNAPSHOT').map(v => v.path)++await agent(+ `Record these doc reviews in the three.ws repo, one command per group, from the repository root:\n` ++ (verified.length+ ? `1. \`npm run docs:review -- ${verified.join(' ')} --note "freshness sweep: checked against the drifted commits"\`\n`+ : '') ++ (snapshots.length+ ? `2. \`npm run docs:review -- ${snapshots.join(' ')} --snapshot --note "dated record, kept as written"\`\n`+ : '') ++ `Then run \`npm run check:docs-freshness\` and report its output verbatim. Do not edit any doc, and do not run any git command that writes (no add, commit, checkout, stash, reset).`,+ { label: 'stamp:reviews', phase: 'Stamp' }+)++return {+ edited: verdicts.filter(v => v.verdict === 'EDITED'),+ verified: verdicts.filter(v => v.verdict === 'VERIFIED'),+ snapshots: verdicts.filter(v => v.verdict === 'SNAPSHOT'),+}diff --git a/tests/docs-freshness-reviews.test.js b/tests/docs-freshness-reviews.test.jsnew file mode 100644index 000000000..7d967a96c--- /dev/null+++ b/tests/docs-freshness-reviews.test.js@@ -0,0 +1,79 @@+// Pins the review-baseline half of the doc freshness system.+//+// Drift used to be measured from one clock, the doc's last commit, so reading a+// page and finding it correct could not be recorded: the only ways to clear it+// were a cosmetic edit or a permanent false positive. data/docs-freshness-reviews.json+// is the second clock, and it only works while every stamp in it is real. A stamp+// for a deleted doc, or one naming a commit this repo does not have, silently+// suppresses drift for that page, which is the exact failure the dashboard exists+// to prevent.+//+// The full measurement lives in scripts/doc-freshness.mjs and takes ~10s over all+// of git history, so it runs in `npm run gate` rather than here. This file guards+// the store's integrity and the wiring, which is cheap and catches the cases a+// `git add -A` sweep or a hand edit would introduce.++import { describe, it, expect } from 'vitest';+import { execFileSync } from 'node:child_process';+import { readFileSync, existsSync } from 'node:fs';+import { fileURLToPath } from 'node:url';+import path from 'node:path';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const store = JSON.parse(readFileSync(path.join(ROOT, 'data/docs-freshness-reviews.json'), 'utf8'));+const pkg = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8'));+const reviews = Object.entries(store.reviews || {});++describe('the review store stays honest', () => {+ it('every stamped doc still exists', () => {+ const missing = reviews.filter(([docPath]) => !existsSync(path.join(ROOT, docPath)));+ expect(+ missing.map(([p]) => p),+ 'drop dead stamps with `npm run docs:review -- --prune`',+ ).toEqual([]);+ });++ it('every stamp names a markdown doc', () => {+ expect(reviews.filter(([p]) => !p.endsWith('.md')).map(([p]) => p)).toEqual([]);+ });++ it('every stamp names a commit this repository has', () => {+ const unknown = reviews.filter(([, entry]) => {+ try {+ execFileSync('git', ['cat-file', '-e', `${entry.commit}^{commit}`], {+ cwd: ROOT,+ stdio: 'ignore',+ });+ return false;+ } catch {+ return true;+ }+ });+ expect(+ unknown.map(([p, e]) => `${p} -> ${e.commit}`),+ 'a stamp at an unknown commit claims a baseline nobody can check',+ ).toEqual([]);+ });++ it('every stamp declares a kind the analyzer understands', () => {+ const bad = reviews.filter(([, e]) => e.kind !== 'verified' && e.kind !== 'snapshot');+ expect(bad.map(([p, e]) => `${p} -> ${e.kind}`)).toEqual([]);+ });+});++describe('the freshness system stays wired', () => {+ it('docs:review points at the stamping script', () => {+ expect(pkg.scripts['docs:review']).toContain('scripts/docs-review.mjs');+ expect(existsSync(path.join(ROOT, 'scripts/docs-review.mjs'))).toBe(true);+ });++ it('build:gcp regenerates the report before the frontend build copies public/', () => {+ const chain = pkg.scripts['build:gcp'] ?? '';+ expect(chain).toContain('npm run docs:freshness');+ // `vite build` runs with emptyOutDir and copies public/ into dist/, so a+ // report written after it would never reach the deployed site.+ expect(chain.indexOf('npm run docs:freshness')).toBeLessThan(+ chain.indexOf('npm run build &&'),+ );+ });+});