Plan: every repo's records on the site, and checked in its CI

Complete · updated 2026-10-31 · branes-ai/architecture#8 · architecture/docs/plan/records-coverage/README.md

Approved 2026-10-29 (architecture#8). Amended the same day: the three repos with docs/plans/ rename it to docs/plan/, so every repo uses the singular names (see One folder convention). Amended 2026-10-30: acceptance 5 allows the paths that R1 updated. Complete: every PR is merged (see Progress), R1 by reflex’s own docs-site plan.

Follows the records-site plan, which published the ADRs and plans of the stack repos and checked them in anatomy, racing-drone and cortex.

Goal

1. Every repo whose records the site collects checks them in its CI, strict, with the check-records action: synapse, reflex, and the five drone repos (scout-drone, isr-drone, nano-drone, interceptor-drone, counter-uas).
2. The repos with plans that the site doesn’t list yet join it: auto-drone, embodied-ai-architect and graphs.
3. reflex gets a docs/ like anatomy’s and racing-drone’s. docs/ becomes the source of the docs site, generated by a sync-docs.mjs. It gains adr/, plan/, sessions/, assessments/ and benchmarks/:
   • adr/ and plan/ go to the architecture site;
   • sessions/ is published nowhere;
   • assessments/ and benchmarks/ are published on the reflex site.
4. One folder convention: every repo keeps its records in docs/adr/ and docs/plan/.

What the survey found

Of the 41 source repos in branes-ai, these have ADRs or plans as files. The scan covered adr/, adrs/, decisions/, plan/ and plans/ folders at any depth.

Repo	Folder	Files	Listed in sources.yaml	Records check in CI
anatomy, racing-drone, cortex	docs/adr/, docs/plan/		yes	yes
synapse	docs/plan/	1, with front matter	yes	no
reflex	none (docs/ holds a README)	0	yes	no
scout-drone, isr-drone, nano-drone, interceptor-drone, counter-uas	none	0	yes	no CI at all
auto-drone	docs/plans/	3	no	no
embodied-ai-architect	docs/plans/	57: 54 records, plus 3 notes in crew-ai/	no	no
graphs	docs/plans/	15	no	no

The three new repos:

• Front matter: nearly none of their plans has it. Some have a prose status, such as “Initial Design” or “Revised”.
• Dry run: a strict check-records run over the three repos found 4 errors, and none of them are links:
  • three embodied-ai-architect files have no # title (two crew-ai/ notes and roadmap-phase-3.md);
  • one auto-drone file starts with a byte-order mark before its title. That one is a collector bug.

The collector:

• Folder names: it takes a record’s kind from its folder’s name. A plans/ folder would therefore publish its files as kind plans, with no status check.
• Byte-order mark: it doesn’t strip a byte-order mark.

reflex:

• Pages: its 27 pages are written in docs-site/src/content/docs/.
• Imports: the MDX pages import the trace player and their traces by relative paths (../../../components/..., ../../../traces/...). Those paths still resolve when the sync keeps the layout.
• The animation plan: its p0–p3 (#37–#48) lives inside the standards page standards/animation.md, together with its assessment and its rules.
• Other references: one header comment names the content path (tools/trace/.../writer.hpp).

The changes

One folder convention

The records folders are docs/adr/ and docs/plan/, singular, in every repo:

• Most repos already use them: anatomy, architecture, cortex, docs-kit, racing-drone and synapse, and reflex’s new folders (R2). Only auto-drone, embodied-ai-architect and graphs use docs/plans/, and none of them has an ADR folder.
• So does everything else: cortex’s ADR template, the records job, the site’s routes (/cortex/adr/...) and this plan.
• One convention keeps the site consistent. Without it, /graphs/plans/x/ would sit next to /cortex/plan/y/, and a link’s author would have to know which repo uses which.

The three repos rename docs/plans/ to docs/plan/ in E1–E3, which edit every plan anyway. A1 had taught the collector the plural names; A2 takes that out again (below).

The collector (architecture)

A1, merged as #9:

• Folder names: a folder named plans holds plans and one named adrs holds ADRs. The route keeps the folder’s name (/graphs/plans/<name>/), so it still follows from the path. A2 replaces this: sources.yaml and --folders reject plans and adrs with an error that names plan and adr.
• Byte-order mark: stripped before parsing.
• The check-records action gets a folders input. It overrides sources.yaml for a repo whose CI runs the check before the repo is listed.
• Tests cover each change.

The check in each repo

Each repo gets the same CI job as anatomy (Architecture records, pinned to the architecture commit with the changes above, strict):

• synapse and reflex: added to ci.yml.
• The five drone repos: a new .github/workflows/records.yml. Each has no records yet, so the job passes at 0 records until one lands.

auto-drone, embodied-ai-architect, graphs

One PR per repo:

• Rename: docs/plans/ becomes docs/plan/, in a commit of its own, so git records each file as renamed.
• References: every mention of the old path follows: links between plans, code and workflow comments, .claude/decisions/*.yaml, CHANGELOG entries, and any instruction to tools or agents that names docs/plans/.
• Front matter: each plan gets front matter. The status comes from its own text, its commit history, and the issues and PRs it names. It’s draft where the evidence doesn’t show approval.
  • Any prose Status: line goes, as in the stack repos.
  • A plan with a date line keeps it.
• The PR body has a table: plan, status, evidence. Your review of that table is the check on each inferred status.
• Missing titles: the files with no # title get one.
• Notes inside plan/: files that aren’t plans (the three crew-ai/ notes) stay where they are, published as attachments, with no status.
• CI: the records job, with the default folders.

Then sources.yaml adds the three repos with folders: [adr, plan], like the others.

Out of scope: those repos’ own docs sites. None publishes docs/plans/; each PR checks that its site’s configuration doesn’t name the old path.

reflex

Two PRs.

R1, docs/ becomes the source.

• Pages: every page moves from docs-site/src/content/docs/ to docs/, at the same paths.
• Generation: a sync-docs.mjs copies docs/ into the content folder, which is then gitignored. It’s anatomy’s script with REPO = 'reflex'. It runs on prebuild and predev, so the deploy workflow, the CI docs job and local builds all generate the site.
• Workflow triggers: the deploy workflow’s paths gain docs/**.
• Edit links: they point at docs/.
• References: the writer header comment, and the paths in building-blocks.md, follow the move.
• No content changes.

R2, the new folders and their first content.

• docs/adr/, docs/sessions/, docs/benchmarks/: a README each, saying what goes in the folder and how files are named. The ADR README points at cortex’s template.
• docs/plan/animation/README.md: the plan part of standards/animation.md, that is, its infrastructure and order of work. Front matter in-progress, because p3 parts 1–3 merged (#43, #45, #48) and the plan names more.
• docs/assessments/animation.md: the page’s “Assessment” section.
• standards/animation.md: keeps the rules (the four pages, provenance, the SITL boundary) and links to the plan and the assessment.
• The sync: skips adr/, plan/ and sessions/. A link from a user page to a record goes to its page on the architecture site, as in anatomy.
• The site: assessments/ and benchmarks/ get sidebar groups, and so does a “Plans and decisions” link.
• CI: the records job.

The PRs, in order

PR	Repo	Content
A1	architecture	The plans/adrs folders, the byte-order mark, the action’s folders input, tests; this plan. Merged as #9
S	synapse	The records job
D1–D5	the five drone repos	records.yml
E1–E3	auto-drone, embodied-ai-architect, graphs	docs/plans/ renamed to docs/plan/; front matter with the evidence table, titles, the records job
R1	reflex	docs/ is the source, generated by sync-docs.mjs
R2	reflex	The new folders; the animation plan and assessment; the records job
A2	architecture	sources.yaml adds the three repos; the plural folder names are rejected; this plan is complete

Acceptance (stated before any test is run)

1. Every repo in sources.yaml runs the records check in its CI, strict, and it passes on its default branch: 15 repos, including architecture’s own and docs-kit (listed by #11 after this plan was written; it was 14).
2. The site lists every .md file under the listed folders of the 15 repos, checked by check-coverage.sh against a find of the clones. That’s 75 more files from the three new repos (auto-drone 3, embodied-ai-architect 57, graphs 15; this criterion said 72, leaving out auto-drone’s 3) and 2 more from reflex.
3. The strict build is green, and no record shows unknown.
4. Every status inferred in E1–E3 has its evidence in the PR’s table.
5. R1 changes no published page. The reflex site built after R1 has the same 27 routes as before. Each page’s HTML is identical except for the edit link and the paths that the move updated. (Amended 2026-10-30, after R1’s check: as first written, it allowed only the edit link.)
6. After R2:
   • the reflex site has no page from adr/, plan/ or sessions/;
   • assessments/animation is published there;
   • the animation plan is on the architecture site, with status in-progress;
   • every link from a reflex page to a record reaches the architecture site.
7. CI is green, and commitlint is clean, in every repo touched.
8. One folder convention (added with the amendment, before E1–E3): after A2, no repo in sources.yaml has a docs/plans/ or docs/adrs/ folder, no file in the three repos names docs/plans/, and the collector rejects the plural names: plans and adrs, each in sources.yaml and in check-records --folders, fail with an error naming plan or adr. A test covers each of the four.

Progress

PR	Merged as
A1	architecture #9
S	synapse #72
D1–D5	scout-drone#1, isr-drone#1, nano-drone#1, interceptor-drone#1, counter-uas#1
E1	auto-drone#24, after auto-drone#25 fixed its macOS build
E2	graphs#353
E3	embodied-ai-architect#240
R1	Done another way: reflex#51, reflex’s own docs-site plan, moved the 27 pages to docs/ and generates the site with docs-kit v0.2.1 instead of a sync-docs.mjs. Its check: 25 pages byte-identical and 2 differing only by updated paths, every old route kept
A2	sources.yaml lists auto-drone, embodied-ai-architect and graphs; plans and adrs are rejected
R2	reflex#56

The acceptance after R2, built from each repo’s main on 2026-10-30:

1. All 15 repos run the records check in CI, and it passes for what is on main. In 13 repos it ran on main’s head. In docs-kit and synapse, main’s head is a release commit, which runs no CI. The check passed on the commit before it, and the release commit changes only the version files and the CHANGELOG: docs/ and ci.yml are the same trees. The strict collect in 2, which makes the same checks, read both repos at main’s head.
2. collect.mjs --strict: 128 pages (121 records) from 15 repos. check-coverage.sh matches every repo, the three new ones at 3, 57 and 15, and reflex at 3: its docs-site plan, plus R2’s ADR README and animation plan.
3. The strict build is green, with 0 warnings, and no record shows unknown. The site builds, and check-site-links.mjs finds 0 broken internal links in 20969.
4. The evidence tables are in auto-drone#24, graphs#353 and embodied-ai-architect#240.
5. Met, as amended. reflex#51’s check, above, found every route kept and 25 of the 27 pages byte-identical; the other 2 differ by updated paths.
6. Met. On the reflex site:
   • /reflex/adr/ and /reflex/plan/animation/ are redirects to the architecture site, not pages, and /reflex/sessions/ doesn’t exist;
   • /reflex/assessments/animation/ is published;
   • the animation plan is collected with status in-progress (the site lists it from its next deploy);
   • the two links from a reflex page to a record (the standards page to the plan, the overview to the ADRs) go to the architecture site.
7. Green in every repo touched.
8. No repo in sources.yaml has a docs/plans/ or docs/adrs/ folder, and no file in the three repos names either path. plans and adrs fail in sources.yaml and in check-records --folders, each with an error naming plan or adr, with a test for each of the four.

Risks

• An inferred status can be wrong. The evidence table makes each one reviewable, and changing a status later is a one-line edit.
• Repos outside the stack (embodied-ai-architect, graphs, auto-drone) have their own maintainers. Their PRs rename one folder and otherwise touch only front matter, the references to the old path, three titles and one CI job.
• The rename breaks links from outside the repos. GitHub doesn’t redirect a renamed file, so a blob/main/docs/plans/... link in an old issue, PR or other repo returns 404. Links inside the repos are updated; outside ones can’t be, and that’s accepted for one convention.
• R1 moves 27 files. Acceptance 5 checks that the published site is unchanged.