mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-08-28 19:20:41 +08:00
Alex Verkhovsky
c4ec1837b8
* feat(project-context): adopt handwritten instructions via a ledger A non-empty instruction file without a managed block now routes to a new adopt intent — the migration form of refresh — never to setup. Every existing instruction enters a retention ledger (retain, rewrite, relocate, automate, delete) presented in full before anything is written; a deletion needs one of four grounds, and one without hard grounds is held for line-item approval that block approval never grants. Best practices replace the derivability test with a retrieval-cost test, admit compact architecture and toolchain pins, and gate nested AGENTS.md files on loading verified for every harness in use, falling back to path-qualified root lines. The explanation and how-to docs follow the same reframing. * fix(project-context): scope splice preservation to the block itself Step 5's byte-identical clause read as forbidding any change outside the markers, which contradicted the ledger's approved rewrites, relocations, and deletions of handwritten instructions there. The splice still touches nothing outside the markers; outside text changes only through a settled ledger entry or a proposed fix the user has seen. Also from review: the how-to routing sentence now distinguishes adopt from refresh, template section 4 includes pyproject.toml, and the theory doc qualifies the source-recovery claim to implementation behavior. * docs(project-context): plain-language pass on how-to and explanation The reader-facing pages had absorbed the skill's internal vocabulary — the disposition taxonomy, approval tiers, harness loading mechanics — and metaphors that mean nothing to a casual reader. Replace them with the user-level promise: you see what happens to every existing instruction before anything is written, and nothing is deleted without your sign-off. The theory page keeps its technical depth by design. * docs(project-context): drop behavior sentence from skill description The description is a routing trigger; the adopt verb already carries the cue, and the preservation behavior is documented where it runs. * refactor(project-context): move intent-conflict rule from Args to detection The Args line declares the interface; the guard against silently obeying a supplied intent that contradicts the detected state belongs in step 4, where detection happens. * docs(project-context): trim Args platitude, mark conflict case as example * docs(project-context): replace canonical/toolchain-pin jargon with plain terms Right commands to use, required tool versions, cross-component rules - same meaning, readable by anyone. * docs(project-context): plain-language the cross-component admission rule * docs(project-context): rewrite the adopted-content budget paragraph readably