Breadway/bread
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix README CLI reference drift, correct stale module-sandboxing claim, document check-docs' current gaps

Browse source 
README's CLI reference had drifted from Documentation.md exactly the
way Workstream F exists to prevent: bread modules audit (Workstream D),
bread hooks install-shell/install-git, and bread events --tree
(Workstream B) were all documented in Documentation.md but missing
here, since this section is hand-copied rather than generated or
linked out.

Also found and fixed while auditing: the Module system section still
said modules "are not sandboxed" -- false since Workstreams D and G
added opt-in capability-scoped, Landlock-sandboxed execution.

Documented in CONTRIBUTING.md that check-docs (Workstream F, scoped
down to a drift detector rather than a generator -- see api-schema.toml's
header) is deliberately not yet wired into CI pending a separate review
pass on the workflow-file change, and that its scope doesn't cover the
CLI-reference-vs-README drift this commit just fixed by hand -- both
previously tracked only in conversation history, not durably in the repo.
This commit is contained in:
Breadway 2026-08-05 09:28:27 +08:00
parent 2485e1af1f
commit 81fbc46e4f
2 changed files with 34 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

16
CONTRIBUTING.md
View file

@ -85,6 +85,22 @@ Whenever you add, rename, or remove a `bread.*` Lua binding
undocumented, stale in the schema, or missing a doc heading/row — if
`api-schema.toml`, the code, and `Documentation.md` don't all agree.
`check-docs` is **not yet wired into CI** — it's a local, manually-run
check today, not an enforced gate. That's a deliberate, still-open gap
(not an oversight): CI pipeline changes get a separate review pass before
landing, same as any other workflow-file edit. Wiring `cargo run -p xtask
-- check-docs` into `dev-release.yml` (fail the build on drift) is the
natural next step whenever that review happens — until then, discipline
running it before committing is what keeps `api-schema.toml`, the code,
and `Documentation.md` in sync, not anything automatic.
Also note `check-docs`'s scope: it covers `bread.*` Lua bindings and IPC
methods against `Documentation.md` only. It does not cover the `bread`
CLI's subcommands against `README.md`'s hand-written CLI reference —
that's a separate, currently-unguarded copy of information (see
`README.md`'s "CLI reference" section) and has drifted before for exactly
the same reason `Documentation.md` used to.
## CI
- `dev-release.yml` — triggered on push to `main`.