Skip to content

docs(internal): correct the Layout block against the real src/ tree - #188

Merged
myselfsiddharth merged 1 commit into
mainfrom
docs/readme-internal-layout
Aug 31, 2026
Merged

docs(internal): correct the Layout block against the real src/ tree#188
myselfsiddharth merged 1 commit into
mainfrom
docs/readme-internal-layout

Conversation

@myselfsiddharth

Copy link
Copy Markdown
Contributor

Summary

Audit of docs/README-internal.md after the npm publish (#185), checking for staleness.

The publication claims were fine — this file's Quick Start is the contributor one (git clone + npm run ci), which publishing does not affect. It makes no npx or registry claims at all.

The Layout block was not fine. It listed six src/ packages:

src/testbed|recorder|compiler|runner|cache|metrics/

ls src/ shows nine directories plus src/cli.ts. Missing: intent/ (#124), session/ (#98 / SC-05), shared/ (#74), and the paragent binary — all landed after the block was written.

That matters more than a typo: a new agent orienting from this file would not learn that the consent gate or the intent resolver exist, and orienting new agents is the one job this section has. Regrouped to match architecture.md's framing — the binary, seven pipeline packages in dataflow order, then the two leaves that are not stages.

Also drops "Content is unchanged" from the header note, which this commit makes false, and records the correction under Open questions so the move-provenance claim stays honest.

Test plan

  • Layout block matches ls -d src/*/ and ls src/*.ts exactly — nine directories plus src/cli.ts
  • Pipeline order matches docs/architecture.md (intent → testbed → recorder → compiler → cache → runner → metrics)
  • shared/ and session/ grouped as leaves, per architecture.md's "not pipeline stages"
  • npm run lint:docs — clean (68 docs)
  • No status, track, verdict, or number changed — verified by diff

Not changed

Two Open-questions bullets remain live and are not mine to close: the owner: B0 guess, and whether coding agents that hardcode README.md now land on the visitor page (the suggested fix there is a root AGENTS.md pointer).

The Layout block listed six packages — testbed, recorder, compiler,
runner, cache, metrics — but `ls src/` shows nine directories plus
src/cli.ts. intent/ (#124), session/ (#98, SC-05) and shared/ (#74) all
landed after the block was written, and the paragent binary after that.

A new agent orienting from this file would not learn that the consent
gate or the intent resolver exist, which is the one job this section
has. Regrouped to match architecture.md: the binary, seven pipeline
packages in dataflow order, then the two leaves that are not stages.

Also drops the "Content is unchanged" claim in the header note, which
this commit makes false, and records the correction under Open
questions. No status, track, or verdict touched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@myselfsiddharth
myselfsiddharth requested a review from a team as a code owner August 31, 2026 23:55
@github-actions github-actions Bot added size/S <= 50 changed lines and removed size/S <= 50 changed lines labels Aug 31, 2026
@github-actions
github-actions Bot requested a review from OM152002 August 31, 2026 23:55
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Aug 31, 2026
@myselfsiddharth
myselfsiddharth merged commit c1822e6 into main Aug 31, 2026
13 checks passed
@myselfsiddharth
myselfsiddharth deleted the docs/readme-internal-layout branch August 31, 2026 23:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant