Docs review — 2026-05-11 (9b16676)

- [ ] **[MAJOR]** `CLAUDE.md:75` — `npm run demo:dev` comment claims "build library then run" but the script does not build the library 
  <details><summary>details</summary>

  **Drift:** `CLAUDE.md` key-commands section annotates `npm run demo:dev` with `# build library then run examples/product-demo via Vite`. The actual script is `cd examples/product-demo && npm run dev`, which only starts the Vite dev server — no library build. A contributor running this command without a prior `npm run build` gets a broken demo because the demo resolves `agentonomous` via `../../dist/` aliases that require a pre-built `dist/`.

  **Evidence:** `jq '.scripts["demo:dev"]' package.json` → `"cd examples/product-demo && npm run dev"`. `README.md` (Running the example) explicitly states: "You must build the library before the example resolves it."

  **Fix:**

  ```diff
  -npm run demo:dev      # build library then run examples/product-demo via Vite
  +npm run demo:dev      # start examples/product-demo Vite dev server (run `npm run build` first)
  ```

  </details>

Counter-argument to my own [MAJOR]: The comment could be read as compressed prose describing the assumed workflow context — "having built the library, then run the demo" — rather than claiming the command itself builds. That interpretation doesn't hold: shell annotation conventions (`command  # description`) universally mean the annotation describes the command's action, not a prerequisite. The README reinforces that the build is a separate prerequisite step. Finding kept.

---

- [ ] **[MAJOR]** `CLAUDE.md:90` — architecture map places needs policies in `src/cognition/`, they live in `src/needs/` 
  <details><summary>details</summary>

  **Drift:** The architecture map entry for `src/cognition/` reads: "`UrgencyReasoner`, `DirectBehaviorRunner`, needs policies (`Expressive`, `Active`, `Composed`)." The three needs policies (`ExpressiveNeedsPolicy`, `ActiveNeedsPolicy`, `ComposedNeedsPolicy`) live in `src/needs/`, not `src/cognition/`.

  **Evidence:** `ls src/needs/` → `ActiveNeedsPolicy.ts`, `ComposedNeedsPolicy.ts`, `ExpressiveNeedsPolicy.ts`, `Need.ts`, `Needs.ts`, `NeedsPolicy.ts`. `ls src/cognition/` → only `Intention.ts`, `IntentionCandidate.ts`, `adapters/`, `behavior/`, `learning/`, `personaBias.ts`, `reasoning/`, `tuning.ts`.

  **Fix:**

  ```diff
  -- `src/cognition/` — `UrgencyReasoner`, `DirectBehaviorRunner`, needs policies (`Expressive`, `Active`, `Composed`). Tuning constants in `src/cognition/tuning.ts`.
  +- `src/cognition/` — `UrgencyReasoner`, `DirectBehaviorRunner`. Tuning constants in `src/cognition/tuning.ts`.
  +- `src/needs/` — homeostatic needs + three needs policies (`ExpressiveNeedsPolicy`, `ActiveNeedsPolicy`, `ComposedNeedsPolicy`).
  ```

  (The existing `src/needs/` bullet only says "homeostatic needs, categorical mood" — the policies should be listed there.)

  </details>

---

- [ ] **[MAJOR]** `README.md:316` and `examples/llm-mock/README.md:4` — `LlmReasoner` is referenced as a named class but does not exist in `src/` 
  <details><summary>details</summary>

  **Drift:** `README.md` line 316 says "A full end-to-end runnable example — `MockLlmProvider` → `LlmReasoner` → `createAgent`". `examples/llm-mock/README.md` line 4 says "Wires a `MockLlmProvider` (deterministic, no network) into a tiny `LlmReasoner`". Neither the library nor the example defines a class named `LlmReasoner`. The example (`examples/llm-mock/index.ts`) builds an inline `Reasoner` implementation directly; `grep -rn "LlmReasoner" src/` returns nothing.

  **Evidence:** `grep -rn "LlmReasoner" src/` → no results. `grep -rn "LlmReasoner" examples/llm-mock/index.ts` → no results (the index.ts imports `Reasoner` type and implements one inline).

  **Fix (README.md):**

  ```diff
  -A full end-to-end runnable example — `MockLlmProvider` →
  -`LlmReasoner` → `createAgent` under `SeededRng` + `ManualClock`,
  +A full end-to-end runnable example — `MockLlmProvider` →
  +inline `Reasoner` → `createAgent` under `SeededRng` + `ManualClock`,
  ```

  **Fix (examples/llm-mock/README.md):**

  ```diff
  -Wires a `MockLlmProvider` (deterministic, no
  -network) into a tiny `LlmReasoner` and runs a `createAgent`-built agent
  +Wires a `MockLlmProvider` (deterministic, no
  +network) into a tiny inline `Reasoner` and runs a `createAgent`-built agent
  ```

  </details>

---

- [ ] **[MAJOR]** `examples/product-demo/README.md:150-155` — localStorage key table has 3 stale keys after the Vue pillar refactor and keyspace split (PR #72) 
  <details><summary>details</summary>

  **Drift:** The README's localStorage key layout table shows the pre-refactor key names. After PR #72 (keyspace split) and the Pillar-1 Vue bootstrap (which purges the old `agentonomous/*` namespace and uses `demo.v2.*` for new keys):
  - `agentonomous/whiskers` → snapshot data key is now `agentonomous/__agentonomous/data/whiskers` (keyspace split: `DATA_PREFIX = '__agentonomous/data/'` in `LocalStorageSnapshotStore.ts:16`)
  - `agentonomous/__agentonomous/index__` → meta index is now `agentonomous/__agentonomous/meta/index` (`META_INDEX_KEY = '__agentonomous/meta/index'` in `LocalStorageSnapshotStore.ts:8`)
  - `agentonomous/speed` → now `demo.v2.session.speed` (`SPEED_STORAGE_KEY` in `SpeedPicker.vue:11`); old key is purged by `purgeLegacyDemoKeys()` in `app/main.ts`
  - `agentonomous/whiskers/tfjs-network` — still correct.

  **Evidence:** `grep -n "META_INDEX_KEY\|DATA_PREFIX" src/persistence/LocalStorageSnapshotStore.ts` → lines 8, 16. `grep -n "SPEED_STORAGE_KEY" examples/product-demo/src/components/shell/SpeedPicker.vue` → `'demo.v2.session.speed'`. `grep -n "agentonomous/speed" examples/product-demo/src/app/main.ts` → listed as a legacy key to purge.

  **Fix:**

  ```diff
  -| `agentonomous/whiskers`               | Agent snapshot (auto-save, every 5 s)          |
  -| `agentonomous/__agentonomous/index__` | Snapshot store index                           |
  -| `agentonomous/whiskers/tfjs-network`  | Trained Learning-mode snapshot (Train button)  |
  -| `agentonomous/speed`                  | Speed-picker preference (not part of snapshot) |
  +| `agentonomous/__agentonomous/data/whiskers` | Agent snapshot (auto-save)              |
  +| `agentonomous/__agentonomous/meta/index`    | Snapshot store index                    |
  +| `agentonomous/whiskers/tfjs-network`        | Trained Learning-mode snapshot          |
  +| `demo.v2.session.speed`                     | Speed-picker preference                 |
  ```

  </details>

---

- [ ] **[MAJOR]** `PUBLISHING.md:86-87` — `npm run size` described as checking 2 dist entries; `package.json#size-limit` has 5 
  <details><summary>details</summary>

  **Drift:** PUBLISHING.md lines 86-87 say "`npm run size` runs the `size-limit` budget against the built `dist/index.js` and `dist/integrations/excalibur/index.js` (gzip)." `package.json#size-limit` contains 5 entries: core, excalibur, mistreevous, js-son, and tfjs adapters.

  **Evidence:** `jq '."size-limit" | length' package.json` → `5`. `jq '."size-limit"[].name' package.json` → shows 5 distinct path entries. *(Carried forward from run `0f72ad7.1`; still open.)*

  **Fix:**

  ```diff
  -`npm run size` runs the `size-limit` budget against the built
  -`dist/index.js` and `dist/integrations/excalibur/index.js` (gzip).
  +`npm run size` runs the `size-limit` budget against all five entries in
  +`package.json#size-limit` (core, excalibur, mistreevous, js-son, and tfjs adapters).
  ```

  </details>

---

- [ ] **[MINOR]** `.claude/skills/verify/SKILL.md:3,9` — description and stage list say "five stages", omitting `lint:demo` and `docs` 
  <details><summary>details</summary>

  **Drift:** The skill's frontmatter description lists "format:check, lint, typecheck, tests, and build" (5); the body says "all five stages"; the stage list enumerates only 5. `npm run verify` runs 7: `format:check && lint && lint:demo && typecheck && test && build && docs`.

  **Evidence:** `jq '.scripts.verify' package.json` → confirms 7-stage chain. *(Carried forward from run `0f72ad7.2`; still open.)*

  **Fix:** Update description, count ("five" → "seven"), stage list (add steps 3 and 7 for `lint:demo` / `npm run docs`), isolation-commands block, and pass/fail summary line.

  </details>

---

- [ ] **[MINOR]** `STYLE_GUIDE.md:130` — "all ten default skills" but 11 skill files exist in `src/skills/defaults/` 
  <details><summary>details</summary>

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

  **Evidence:** `ls src/skills/defaults/*.ts | grep -Ev 'effectiveness|index' | wc -l` → `11`. *(Carried forward from run `0f72ad7.6`; still open.)*

  **Fix:**

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

  Or drop the count: `(all default skills)` — removes drift risk.

  </details>

---

- [ ] **[MINOR]** `.claude/memory/feedback_pr_hygiene.md:11` — verify gate listed as "format + lint + typecheck + test + build", omitting `lint:demo` and `docs` 
  <details><summary>details</summary>

  **Drift:** Lines 10-12 say the gate is "`npm run verify` green pre-PR … format + lint + typecheck + test + build". The actual script runs 7 stages; `lint:demo` and `docs` are missing from the enumeration.

  **Evidence:** `jq '.scripts.verify' package.json` → 7 stages. *(Carried forward from run `0f72ad7.7`; still open.)*

  **Fix:**

  ```diff
  -- **`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.
  ```

  </details>

---

- [ ] **[MINOR]** `.claude/memory/project_graphify_usage.md:44-45` — claims `graphify-out/wiki/` is checked in but it is not tracked by git 
  <details><summary>details</summary>

  **Drift:** Lines 44-45 say "**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 — no wiki directory.

  **Evidence:** `git ls-files graphify-out/` → `graphify-out/GRAPH_REPORT.md`, `graphify-out/graph.html`, `graphify-out/graph.json`. *(Carried forward from run `0f72ad7.4`; still open.)*

  **Fix:**

  ```diff
  -**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.
  ```

  </details>

---

- [ ] **[MINOR]** `docs/plans/2026-04-26-quality-automation-routines.md:160` — dead reference to `feedback_one_pr_per_session.md` which does not exist 
  <details><summary>details</summary>

  **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 absent.

  **Evidence:** `ls .claude/memory/feedback_*.md` → no `feedback_one_pr_per_session.md`. *(Carried forward from run `0f72ad7.5`; still open.)*

  **Fix:**

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

  </details>

---

- [ ] **[MINOR]** `docs/specs/mvp-demo.md` — filename is missing the required `YYYY-MM-DD-` date prefix 
  <details><summary>details</summary>

  **Drift:** `CLAUDE.md` specifies: "Specs live in `docs/specs/YYYY-MM-DD-<slug>.md`. Date prefix = first-commit date. Never drop the date." `docs/specs/mvp-demo.md` has no date prefix, unlike every other spec file in the directory.

  **Evidence:** `ls docs/specs/` → `2026-04-24-post-tfjs-improvements.md`, `2026-04-26-pre-v1-demo-evolution-design.md`, `2026-04-26-pre-v1-demo-evolution-spec.md`, `2026-05-06-strategy-ai-modding-review.md`, `mvp-demo.md`. All others have date prefixes.

  **Fix:** `git mv docs/specs/mvp-demo.md docs/specs/YYYY-MM-DD-mvp-demo.md` where the date is the file's first-commit date (`git log --follow --diff-filter=A -- docs/specs/mvp-demo.md` to find it).

  </details>

---

- [ ] **[MINOR]** Four review-bot finding plans still in `docs/plans/` despite all underlying fixes having shipped — should be archived 
  <details><summary>details</summary>

  **Drift:** The four `2026-04-27-review-bot-*.md` plan files describe code fixes for findings `d9b4b85.1–4`. All four fixes have since merged:
  - `d9b4b85.1` — `fix(demo): share seed storage key between PlayView and useAgentSession` (PR #159)
  - `d9b4b85.2` — `fix(demo): wire learner before reasoner on cognition swap` (PR #162)
  - `d9b4b85.3` — `fix(test): move attachResetHandler below static imports` (PR #163)
  - `d9b4b85.4` — `fix(scripts): use Date.getTime() in review-fix sort comparator` (PR #164)

  Per `CLAUDE.md` archive convention, each plan should move to `docs/archive/plans/` after its work ships.

  **Evidence:** `git log --oneline -- examples/product-demo/src/views/PlayView.vue` → includes `fix(demo): share seed storage key…(#159)`. Same pattern confirmed for PRs #162, #163, #164.

  **Fix:**

  ```bash
  git mv docs/plans/2026-04-27-review-bot-minor-hardcoded-seed-storage-key-d9b4b85-1.md docs/archive/plans/
  git mv docs/plans/2026-04-27-review-bot-minor-new-reasoner-active-but-d9b4b85-2.md docs/archive/plans/
  git mv docs/plans/2026-04-27-review-bot-minor-attachresethandler-decl-before-d9b4b85-3.md docs/archive/plans/
  git mv docs/plans/2026-04-27-review-bot-nit-date-implicit-valueof-coercion-d9b4b85-4.md docs/archive/plans/
  ```

  (Per `docs/archive/README.md` convention: add archive banner, no body edits.)

  </details>

---

- [ ] **[MINOR]** `docs/plans/2026-04-26-pre-v1-demo-guided-walkthrough.md` — every slice is `✅ shipped` but plan has not been archived 
  <details><summary>details</summary>

  **Drift:** The plan's roadmap table shows all five slices `✅ shipped` via PRs #140, #146, #150, #153, #158. The evolution-plan tracker table (`docs/product/2026-04-26-pre-v1-demo-evolution-plan.md:378`) also marks row A (Guided walkthrough) as `✅ shipped`. The plan should be archived per `CLAUDE.md` convention.

  **Evidence:** `grep "✅\|not started" docs/plans/2026-04-26-pre-v1-demo-guided-walkthrough.md` → all rows `✅ shipped`.

  **Fix:**

  ```bash
  git mv docs/plans/2026-04-26-pre-v1-demo-guided-walkthrough.md docs/archive/plans/
  ```

  Update `docs/product/2026-04-26-pre-v1-demo-evolution-plan.md:378` link accordingly.

  </details>

---

- [ ] **[MINOR]** Five shipped quality chunk plans have all internal implementation steps still `[ ]` despite the umbrella tracker marking them `[x] shipped` 
  <details><summary>details</summary>

  **Drift:** The umbrella tracker (`2026-04-26-quality-automation-routines.md`) marks rows 1–5 as `[x] shipped` with PR links. But the individual chunk plan files still have every implementation step marked `[ ]` (unchecked). A reader of the chunk plans sees open work for already-shipped features:
  - `quality-codeql.md` — 9 unchecked steps (shipped: tracker row 1)
  - `quality-dep-triage-bot.md` — 8 unchecked steps (shipped: tracker row 2)
  - `quality-actions-bump-bot.md` — 6 unchecked steps (shipped: PR #142, tracker row 3)
  - `quality-plan-recon-bot.md` — 7 unchecked steps (shipped: PR #143, tracker row 4)
  - `quality-bundle-trend.md` — 11 unchecked steps (shipped: PR #144, tracker row 5)

  All five delivered artifacts exist (`codeql.yml`, `dependabot.yml`, `bundle-size-trend.yml`, `docs/actions-bump-bot/`, `docs/dep-triage-bot/`, `docs/plan-recon-bot/`).

  **Evidence:** `grep -c "\- \[ \]" docs/plans/2026-04-26-quality-{codeql,dep-triage-bot,actions-bump-bot,plan-recon-bot,bundle-trend}.md` → 9, 8, 6, 7, 11.

  **Fix:** Per the umbrella tracker's "When to mark this tracker shipped" section: archive all five chunk plans (plus the three unshipped ones can remain in `docs/plans/` until they ship) when every row is `[x]`. For now, consider archiving the five shipped chunk plans individually, or tick their internal steps off before archiving.

  </details>

---

- [ ] **[NIT]** `PUBLISHING.md:38-39` — leaf-job list (labelled "as of d9b4b85") is now also missing `E2E (Playwright)` added in PR #158 
  <details><summary>details</summary>

  **Drift:** The parenthetical "as of d9b4b85" leaf-job list omitted the matrix expansion of `test-core`/`test-tfjs` (flagged in prior run `0f72ad7.8`). Since that run, `E2E (Playwright)` was also added to `ci-gate.needs` (PR #158). The list now lags two changes behind.

  **Evidence:** `grep "e2e" .github/workflows/ci.yml` → `e2e` job defined at line 470, listed in `ci-gate.needs`. *(Prior finding carried forward; drift has grown.)*

  **Fix:** Remove the parenthetical list entirely (the surrounding text already directs readers to wire only "CI gate (required check)"), or update it to note the matrix and E2E job.

  </details>

---

- Reviewed at: `9b166765ba14e21c05987ba5f793d8abd9f1b837` (66 Markdown files audited)
- Blockers: 0
- Majors: 5
- Minors: 9
- Nits: 1
- Counter-argument check: `9b16676.1` (CLAUDE.md demo:dev) — counter tested, not held, finding kept
- Truncated: no
- Not reviewed (partial or skipped): `docs/review-bot/PROMPT.md`, `docs/review-bot/README.md`, `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` (cloud-routine prompt internals — cross-references spot-checked only), `docs/specs/2026-04-26-pre-v1-demo-evolution-design.md`, `docs/specs/2026-04-26-pre-v1-demo-evolution-spec.md` (large specs — headers and external references spot-checked), `docs/plans/2026-04-26-pre-v1-demo-cognition-diff-panel.md`, `docs/plans/2026-04-26-pre-v1-demo-determinism-fingerprint.md`, `docs/plans/2026-04-26-pre-v1-demo-json-preview-commit.md`, `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-determinism-replay.md`, `docs/plans/2026-04-26-quality-mutation-testing.md` (not-started plans; tracker status consistent with open `[ ]` rows), `docs/reviews/2026-04-25-library-review-issue.md` (historical review snapshot — immutable), `docs/specs/2026-04-24-post-tfjs-improvements.md`, `docs/specs/2026-05-06-strategy-ai-modding-review.md` (specs only scanned for symbol/path references)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs review — 2026-05-11 (9b16676) #202

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Docs review — 2026-05-11 (9b16676) #202

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions