Skip to content

docs: correct claims contradicted by the committed code - #43

Merged
alloevil merged 1 commit into
masterfrom
fix/claim-audit
Sep 11, 2026
Merged

alloevil merged 1 commit into
masterfrom
fix/claim-audit

Conversation

@alloevil

Copy link
Copy Markdown
Owner

Docs-only PR applying the corrections that survived re-derivation from the committed code. Every claim was re-checked in this checkout (master 6f820ae) before editing; nothing outside README.md, README.zh-CN.md, assets/readme/hero.svg and docs/ROADMAP.md changed.

Changed (claim -> evidence)

Log locations (both READMEs, format table)

Claim Now Evidence
Codex ~/.codex/sessions/{id}.jsonl ~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{uuid}.jsonl (id = trailing UUID) lib/platforms/codex.js:17 ("Walk the YYYY/MM/DD tree"), lib/platforms/index.js:141-156; fixture test/fixtures/home/.codex/sessions/2026/01/15/rollout-2026-01-15T10-00-00-01900000-0000-7000-8000-000000000001.jsonl
Claude Code ~/.claude/projects/*/sessions/*/session.jsonl ~/.claude/projects/{project-slug}/{sessionId}.jsonl (+ {sessionId}/subagents/agent-*.jsonl) lib/platforms/claude.js:23-39; fixtures under .claude/projects/-fixtures-project-beta/; no sessions/ level anywhere

Commands: find test/fixtures/home/.codex/sessions -name '*.jsonl', find test/fixtures/home/.claude -name '*.jsonl'.

Privacy / outbound traffic (both READMEs, three places each) — "nothing leaves your machine" / "the only outbound traffic …" was contradicted by the Fabric import: lib/library.js:199-200 fetches api.github.com + raw.githubusercontent.com, reachable unconfigured through lib/routes/library.js:276 and :293. grep -rn "fetch(" lib/ lists only lib/llm.js:90 and lib/library.js:213. The text now names both outbound features, what they download and when.

Badges / heroframework-None contradicted by package.json (express) + frontend/package.json (react ^19.2.8) → relabelled stack-Express + React. build-size~70KB / ~70KB build unsupported (grep -rn "70KB" matched only those two spots, no script produces it) → removed.

docs/ROADMAP.md:11 — "46 tests" → "130 tests (npm test, 2026-09-12)": npm test prints # tests 130 / # pass 130 / # fail 0 (126 top-level test() declarations + 4 nested t.test subtests). Note this differs from the audit's 126, which counted declarations only; I used the runner's own figure.

Scope/behaviour wording — archived sessions are OpenClaw-only (grep -rn includeArchived lib/openclaw.js:141,148); backup covers Codex/Claude Code/OMP/dsh/Gemini (lib/backup.js:9,128-141); trace bars open the span sidebar, purple = child transcript (TraceView.tsx:4-5,82-89); ledger renders from two user turns on (TurnLedger.tsx:42) with tool counts inline / error counts in the row title (:92-99); Analyze uses the configured LLM backend with the claude CLI as fallback and reports llmError (lib/llm.js:7-14, PromptsAnalysis.tsx:72-74); CI runs four steps (.github/workflows/test.yml); the demo serves frontend/src/demo/fixtures.json generated by scripts/build-demo-fixtures.mjs (router.ts:15-17); Langfuse is self-hostable.

Gate (Node v22.23.2)

npm test
# tests 130
# pass 130
# fail 0

node scripts/build-legacy-pure.mjs && git diff --exit-code public/js/pure.js
wrote public/js/pure.js
DRIFT: clean (public/js/pure.js matches TS sources)

npx biome check .
Checked 50 files. exit 0 (91 warnings / 159 infos — identical to the pre-change baseline)

No formatters were run; diffs are minimal and matched to each file's language.

Deliberately NOT applied

  • npm-version-drift (package.json 1.17.2 vs npm latest 1.17.1): real, but no README/doc claim states a version, and fixing it means publishing a release (credentials + release automation), not a docs edit. Left unresolved.
  • when-not-node-wording (README:63 / zh:40): re-read against package.json engines.node >= 22.13. The bullet sits under "When NOT to use it", so "You cannot run Node.js ≥ 22.13" and "你无法使用 Node.js ≥ 22.13" state the correct exclusion condition and do not misstate behaviour. Left unchanged.
  • ledger-row-visibility (code half): I reworded the README instead of changing TurnLedger.tsx's rows.length < 2 gate — altering UI behaviour is outside a claim-fix PR. The hero legend strip is a drawn illustration, so its alt text still describes the image accurately.
  • docs/ROADMAP.md "5 platforms": the section is labelled "Where we are (v1.12)" and the platform list is a historical snapshot; only the explicitly stale test figure was corrected.

Every change below was re-derived in this checkout (master 6f820ae) with the
quoted command; items that did not survive re-derivation were left alone and
are listed in the PR description.

Format table (README.md, README.zh-CN.md)
- Codex: `~/.codex/sessions/{id}.jsonl` -> `~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{uuid}.jsonl` (session id is the trailing UUID).
  Evidence: lib/platforms/codex.js:17 "Walk the YYYY/MM/DD tree"; lib/platforms/index.js:141-156 builds <dir>/YYYY/MM/DD and matches the trailing UUID; committed fixture is
  test/fixtures/home/.codex/sessions/2026/01/15/rollout-2026-01-15T10-00-00-01900000-0000-7000-8000-000000000001.jsonl
  (find test/fixtures/home/.codex/sessions -name '*.jsonl').
- Claude Code: `~/.claude/projects/*/sessions/*/session.jsonl` -> `~/.claude/projects/{project-slug}/{sessionId}.jsonl` (plus `{sessionId}/subagents/agent-*.jsonl`).
  Evidence: lib/platforms/claude.js:23-30 reads <dir>/<slug>/*.jsonl and :35-39 reads <dir>/<slug>/subagents/agent-*.jsonl; no `sessions/` level exists in the adapter or in the fixtures
  (find test/fixtures/home/.claude -name '*.jsonl' -> projects/-fixtures-project-beta/{aaaa1111-....jsonl,aaaa1111-.../subagents/agent-fx001.jsonl}).

Privacy / egress (README.md:38, :54, FAQ; same claims mirrored in README.zh-CN.md)
- "nothing leaves your machine" and "the only outbound traffic it can make is the optional prompt-rewrite feature" were false: lib/library.js:199-200 fetches
  https://api.github.com/repos/danielmiessler/fabric/contents/data/patterns and raw.githubusercontent.com for the Fabric pattern import, reachable with nothing configured via
  lib/routes/library.js:276 (GET /api/library/fabric-patterns) and :293 (POST /api/library/import-fabric). grep -rn "fetch(" lib/ returns only lib/llm.js:90 and lib/library.js:213.
- Both places now name the two real outbound cases, what they download and when.

Badges / hero (README.md:20-21, assets/readme/hero.svg:56)
- `framework-None` ("No framework") is contradicted by package.json express ^4.21.2 and frontend/package.json react ^19.2.8; relabelled `stack-Express + React`.
- `build-size~70KB` (badge) and "~70KB build" (hero) are unsupported: nothing in the tree produces the number (grep -rn "70KB" matched only those two spots); removed both.

docs/ROADMAP.md:11
- "46 tests" -> 130 tests, from the repo's own gate: `npm test` prints "# tests 130 / # pass 130 / # fail 0" (126 top-level test() declarations + 4 nested t.test subtests).

Scope / behaviour fixes
- Archived sessions are OpenClaw-only: grep -rn "includeArchived" lib/ -> lib/platforms/openclaw.js:141,148 only.
- Backup covers Codex, Claude Code, OMP, DeepSeek Harness and Gemini CLI: lib/backup.js:9 comment and :128-141 counters (Hermes and OpenClaw excluded).
- Trace bar click opens the span sidebar (a purple bar loads the child agent's transcript); it does not jump to a message: frontend/src/views/trace/TraceView.tsx:4-5,82-89.
- The per-turn ledger renders from two user turns on (frontend/src/views/sessions/TurnLedger.tsx:42) and shows tool-call counts inline with error counts in the row title (:92-99).
- Analyze prefers the configured LLM backend and falls back to the claude CLI, reporting llmError when neither exists: lib/llm.js:7-14, frontend/src/views/prompts/PromptsAnalysis.tsx:72-74.
- CI runs four steps, not two: .github/workflows/test.yml (npm ci, git diff --exit-code public/js/pure.js, npx biome check ., npm test).
- The demo serves frontend/src/demo/fixtures.json (frontend/src/demo/router.ts:15-17), generated from frontend/demo/sample-logs by scripts/build-demo-fixtures.mjs:3-11.
- Langfuse can be self-hosted, so the comparison table no longer implies a hosted backend is the only deployment.

Gate (this checkout, Node v22.23.2):
- npm test -> # tests 130, # pass 130, # fail 0
- node scripts/build-legacy-pure.mjs && git diff --exit-code public/js/pure.js -> clean
- npx biome check . -> exit 0 (91 warnings/159 infos, identical to the pre-change baseline)
@alloevil
alloevil merged commit 32f9422 into master Sep 11, 2026
3 checks passed
@alloevil
alloevil deleted the fix/claim-audit branch September 11, 2026 18:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant