I2941 — A fresh init leaves doctor clean: a README that does not name AGENTS.md gains one paragraph that does
Make the adopter's clean-install path (init, update, the two hook lines) doctor-clean: a shared init appends one paragraph naming AGENTS.md to an existing README.md that does not mention it, once, leaving the rest of the README byte for byte, and lists it with what it created; it creates no README and a personal layer leaves the project's README alone.
DONE wave 0 · p1 · implementation profile · parallel safe
Objective
Make the adopter's clean-install path (init, update, the two hook lines) doctor-clean: a shared init appends one paragraph naming AGENTS.md to an existing README.md that does not mention it, once, leaving the rest of the README byte for byte, and lists it with what it created; it creates no README and a personal layer leaves the project's README alone.
Why
The alpha-contract run on released v0.29.0 (2026-10-17) found that a fresh `majordomus init` + `update` + hooks in a scratch repository with a README fails `doctor` once: 'README.md does not name AGENTS.md; a reader cannot find the agent bootstrap' (majordomus.bootstrap-integrity, lib/doctor.sh mj_validate_bootstrap), and init never says so. Every first adopter with a README met one unexplained FAIL. The rule requires the README to name AGENTS.md; nothing forbids init from adding it in a shared layer (init already appends to .gitignore the same way, and region projections exist so that a hand-written file is adopted, not replaced), while the personal layer's own rule keeps the project's README out of reach, as doctor already skips it there. So init writes the paragraph rather than printing a step.
Current state
init leaves README.md untouched; doctor then fails bootstrap on it.
Desired state
init, update and the hook lines leave doctor with 0 FAIL in a repository with a README, with none, and with one that already names AGENTS.md.
Scope
- lib/init.sh
- share/install/INSTALL.md.in
- docs/INSTALL.md
- test/cases/3340_a_fresh_init_leaves_doctor_clean.sh
Dependencies
None. This issue is a root of the graph.
Acceptance criteria
- A scratch repository with a README that names nothing gets init, update and the hook lines, and doctor exits 0 with no FAIL
- A rerun adds nothing; a README that names AGENTS.md is untouched; no README is created; a personal init leaves the README alone
Validation
- bash test/run.sh 3340_a_fresh_init_leaves_doctor_clean 01_init 02_doctor_basic 03_update 19_end_to_end 2979_a_personal_layer_changes_nothing_shared
Evidence required
- fresh_adoption_case
Evidence
| covers | type | command | result | at commit |
|---|---|---|---|---|
| fresh_adoption_case | test | MJ_TEST_JOBS=3 bash test/run.sh 3340_a_fresh_init_leaves_doctor_clean 01_init 02_doctor_basic 03_update 19_end_to_end 2979_a_personal_layer_changes_nothing_shared | tests: 6 passed, 0 failed, 0 skipped at 4f3b3490d6c (3340 also passes with MJ_ROOT exported); mutation: without the mj_init_readme call, 3340 fails on doctor exit 10, the alpha-contract finding | 4f3b349 |
Timeline
- started
- 2026-10-17T20:38:14Z
- verified
- 2026-10-17T20:38:24Z
- completed
- 2026-10-17T20:38:39Z
Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.
Canonical record: .ai/repo/project/issues/I2941.yaml. Read it back with majordomus plan show I2941.