Docs review — 2026-05-04 (0f72ad7)

[Luis85]

• [MAJOR] PUBLISHING.md:86 — npm run size described as checking 2 dist entries; package.json has 5

  details

  Drift: Doc says npm run size runs "against the built dist/index.js and dist/integrations/excalibur/index.js (gzip)" but package.json#size-limit has 5 entries: also dist/cognition/adapters/mistreevous/index.js (2 KB), dist/cognition/adapters/js-son/index.js (2 KB), dist/cognition/adapters/tfjs/index.js (9 KB).

  Evidence: cat package.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('size-limit'))" → 5 entries. grep -n "dist/index.js\|dist/integrations/excalibur" PUBLISHING.md → line 86-88 names only two.

  Fix:

  -`npm run size` runs the `size-limit` budget against the built
  -`dist/index.js` and `dist/integrations/excalibur/index.js` (gzip). Budgets
  -live in the `size-limit` field of `package.json`.
  +`npm run size` runs the `size-limit` budget against all five entries in
  +`package.json#size-limit` (core, excalibur adapter, and the three cognition
  +adapters: mistreevous, js-son, tfjs). Authoritative limits live in that field.

Counter-argument to my own [MAJOR]: The doc's very next sentence says "Budgets live in the size-limit field of package.json" — so the authoritative source is correctly identified. A developer running npm run size sees all 5 results regardless of the prose. The two named entries were the only ones when the doc was written. → Counter doesn't hold: the doc uses "runs…against the built X and Y" as a concrete factual claim about which paths are checked. Someone adding a fourth adapter subpath would not know to look for a budget entry here, and the cognition adapter caps (2–9 KB) are real enforcement points.

---

• [MAJOR] .claude/skills/verify/SKILL.md:9 — skill says verify has "five stages", missing lint:demo and docs

  details

  Drift: The skill's frontmatter, body header, stage list, and reporting line all say "five stages" and enumerate only format:check, lint, typecheck, test, build. The actual npm run verify script (confirmed via package.json) runs seven stages: format:check && lint && lint:demo && typecheck && test && build && docs. CLAUDE.md:52 correctly lists all 7. The skill's isolation-command section omits npm run lint:demo and npm run docs entirely.

  Evidence: cat package.json | python3 -c "…; print(d['scripts']['verify'])" → npm run format:check && npm run lint && npm run lint:demo && npm run typecheck && npm run test && npm run build && npm run docs

  Fix:

  -description: Runs the full agentonomous pre-PR gate — format:check, lint,
  -typecheck, tests, and build — and reports failures concisely.
  +description: Runs the full agentonomous pre-PR gate — format:check, lint,
  +lint:demo, typecheck, tests, build, and docs — and reports failures concisely.
  ...
  -The underlying npm script runs all five stages
  +The underlying npm script runs all seven stages
  ...
   1. `npm run format:check` — Prettier
   2. `npm run lint` — ESLint flat config
  +3. `npm run lint:demo` — ESLint on the demo workspace (DDD + determinism rules)
  -3. `npm run typecheck` — `tsc --noEmit` …
  +4. `npm run typecheck` — `tsc --noEmit` …
  -4. `npm test` — Vitest
  +5. `npm test` — Vitest
  -5. `npm run build` — Vite library mode → `dist/`
  +6. `npm run build` — Vite library mode → `dist/`
  +7. `npm run docs` — typedoc → `docs/`
  ...
  -**Pass:** one-line confirmation (`All 5 stages green — ready to PR.`).
  +**Pass:** one-line confirmation (`All 7 stages green — ready to PR.`).

  And add to the isolation-commands block:

  +npm run lint:demo   # if the demo ESLint check is the issue
  +npm run docs        # if typedoc generation is the issue

• [MINOR] CLAUDE.md:74 — architecture map omits src/body/ module (exports Appearance, Embodiment, Transform, LocomotionMode)

  details

  Drift: The ## Architecture map section lists src/agent/, src/cognition/, src/skills/, src/modifiers/, src/needs/, src/mood/, src/lifecycle/, src/animation/, src/events/, src/persistence/, src/randomEvents/, src/integrations/excalibur/ — but omits src/body/, which contains Appearance.ts, Embodiment.ts, LocomotionMode.ts, Transform.ts. All four are re-exported from src/index.ts (lines 199–202). src/body/ is flagged as style-relevant in STYLE_GUIDE.md:133 but never explained in the map.

  Evidence: git ls-files src/body/ → 4 files. grep "src/body" src/index.ts → lines 199–202 export public symbols. grep "src/body" CLAUDE.md → no results.

  Fix: Add a bullet to the Architecture map:

  +- `src/body/` — `Appearance`, `Embodiment`, `Transform`, `LocomotionMode`.
  +  Shape/locomotion descriptors consumed by `SpeciesDescriptor` and `Agent`.

• [MINOR] .claude/memory/project_graphify_usage.md:44 — claims graphify-out/wiki/ is checked in; it is not tracked

  details

  Drift: The memory file says "What's checked in: graph.html, graph.json, GRAPH_REPORT.md, and the wiki under graphify-out/wiki/." git ls-files graphify-out/ returns only 3 files — GRAPH_REPORT.md, graph.html, graph.json. No wiki directory.

  Evidence: git ls-files graphify-out/ | wc -l → 3. ls graphify-out/ → GRAPH_REPORT.md graph.html graph.json (no wiki/).

  Fix:

  -**What's checked in:** `graph.html`, `graph.json`, `GRAPH_REPORT.md`,
  -and the wiki under `graphify-out/wiki/`.
  +**What's checked in:** `graph.html`, `graph.json`, `GRAPH_REPORT.md`.
  +The wiki (`graphify-out/wiki/`) is gitignored and not tracked.

• [MINOR] docs/plans/2026-04-26-quality-automation-routines.md:160 — dead reference to feedback_one_pr_per_session.md

  details

  Drift: Line 160 says "(one PR per session — see MEMORY.md → feedback_one_pr_per_session.md)". No such file exists in .claude/memory/. ls .claude/memory/feedback_*.md lists 10 feedback files; feedback_one_pr_per_session.md is not among them.

  Evidence: ls /home/user/agentonomous/.claude/memory/feedback_*.md — no feedback_one_pr_per_session.md. grep "one_pr_per_session" .claude/memory/MEMORY.md — no results.

  Fix:

  -(one PR per session — see `MEMORY.md →
  -feedback_one_pr_per_session.md`),
  +(one PR per session — see `MEMORY.md →
  +feedback_pr_hygiene.md`),

  (The "branch-per-concern / never stack" rule lives in feedback_pr_hygiene.md; alternatively remove the parenthetical entirely.)

• [MINOR] STYLE_GUIDE.md:131 — "all ten default skills" but 11 skill files exist in src/skills/defaults/

  details

  Drift: STYLE_GUIDE.md line 131 says "src/skills/defaults/*.ts (all ten default skills)". ls src/skills/defaults/ shows 11 skill files: CleanSkill.ts, ExpressMeowSkill.ts, ExpressSadSkill.ts, ExpressSleepySkill.ts, ExpressionSkill.ts, FeedSkill.ts, MedicateSkill.ts, PetSkill.ts, PlaySkill.ts, RestSkill.ts, ScoldSkill.ts (plus effectiveness.ts and index.ts).

  Evidence: ls src/skills/defaults/*.ts | grep -v effectiveness | grep -v index | wc -l → 11

  Fix:

  -- `src/skills/defaults/*.ts` (all ten default skills)
  ++ `src/skills/defaults/*.ts` (all eleven default skills)

  Or remove the count: (all default skills) to avoid drifting again.

• [MINOR] .claude/memory/feedback_pr_hygiene.md:10 — verify gate listed as 5 stages, missing lint:demo and docs

  details

  Drift: Line 10-11 says "npm run verify green pre-PR … format + lint + typecheck + test + build". The actual verify script runs 7 stages: format:check && lint && lint:demo && typecheck && test && build && docs. Same omission as the verify skill (finding 0f72ad7.2). CLAUDE.md:52 correctly lists all 7.

  Evidence: cat package.json | python3 -c "…; print(d['scripts']['verify'])" → confirms 7 stages.

  Fix:

  -- **`npm run verify` green pre-PR.** Always. This is the
  -  non-negotiable gate codified in `CLAUDE.md`: format + lint +
  -  typecheck + test + build.
  ++ **`npm run verify` green pre-PR.** Always. This is the
  +  non-negotiable gate codified in `CLAUDE.md`: format + lint +
  +  lint:demo + typecheck + test + build + docs.

• [NIT] PUBLISHING.md:38 — CI leaf-job list labelled "as of d9b4b85" is stale; test matrix has expanded since

  details

  Drift: PUBLISHING.md:38-43 lists Test core (Vitest, ubuntu-latest) and Test tfjs (cpu on ubuntu-latest) as the test leaf jobs. Since PR chore(ci): add OS x tfjs-backend matrix (test-core + test-tfjs split) #113 (row 4, chore/ci-backend-and-os-matrix), both are now matrix jobs: test-core runs across ubuntu/macos/windows and test-tfjs runs across cpu×wasm × the same OS matrix. The label "as of d9b4b85" correctly signals the historical anchor, but the job names are now misleading for anyone configuring branch protection.

  Evidence: grep "name:" .github/workflows/ci.yml → Test core (Vitest, ${{ matrix.os }}) and Test tfjs (${{ matrix.backend }} on ${{ matrix.os }}).

  Fix: Either update the list to note the matrix form or remove it and rely on the "CI gate (required check)" aggregator call-out (which the same paragraph already makes):

  -(For reference, the full leaf-job list as of d9b4b85: `Format (Prettier)`,
  -`Lint (ESLint)`, `Typecheck (tsc --noEmit)`, `Lint workflows (actionlint)`,
  -`Audit production deps (npm audit)`, `API docs (typedoc)`,
  -`Test core (Vitest, ubuntu-latest)`, `Test tfjs (cpu on ubuntu-latest)`,
  -`Build & size budget`, `Demo build (examples/product-demo)`.)
  +(For reference, the leaf jobs as of develop include `Format (Prettier)`,
  +`Lint (ESLint)`, `Typecheck (tsc --noEmit)`, `Lint workflows (actionlint)`,
  +`Audit production deps (npm audit)`, `API docs (typedoc)`,
  +`Test core (Vitest, <os-matrix>)`, `Test tfjs (<backend>×<os> matrix)`,
  +`Build & size budget`, `Demo build (examples/product-demo)`. The list
  +drifts; rely on `CI gate (required check)` as the single required check.)

---

• Reviewed at: 0f72ad7 (65 Markdown files audited)
• Blockers: 0
• Majors: 2
• Minors: 5
• Nits: 1
• Counter-argument check: 0f72ad7.1 (PUBLISHING.md size-limit) — counter tested, not held, finding kept
• Truncated: no
• Not reviewed (partial or skipped): docs/actions-bump-bot/PROMPT.md, docs/actions-bump-bot/README.md, docs/dep-triage-bot/PROMPT.md, docs/dep-triage-bot/README.md, docs/plan-recon-bot/PROMPT.md, docs/plan-recon-bot/README.md, docs/review-bot/PROMPT.md, docs/review-bot/README.md (cloud-routine prompt internals; cross-references were spot-checked), docs/specs/2026-04-26-pre-v1-demo-evolution-design.md, docs/specs/2026-04-26-pre-v1-demo-evolution-spec.md (large spec files; headers and references spot-checked), docs/plans/2026-04-26-pre-v1-demo-second-scenario.md, docs/plans/2026-04-26-quality-demo-smoke.md, docs/plans/2026-04-26-quality-mutation-testing.md (not read; no cross-ref signals found in related files). Generated assets (graphify-out/*.json, graphify-out/*.html) not reviewed — content is regenerated artifact.