v0.17.2 — generate-docs: insert/remove inverses, ownership-marker contract test
Re-run testing of /architect:generate-docs against the scaffold-mode output found that its marked regions were not stable across cycles. This release fixes that and locks the contract down with an executable test.
Fixed
Region insert and remove are now exact inverses. The whitespace around a marked region was unspecified, so remove → re-insert did not reproduce the file, and repeated cycles left whitespace-only diff noise — in a file whose whole point is being reviewable. The rule is now explicit:
- exactly one blank line separates a region from its neighbours, or it sits flush against start/end of file
- removing a region takes the region plus the single blank line that follows it — or, at end of file, the one that precedes it
- the file ends with exactly one newline, and no run of two or more blank lines is introduced
Verified before the rule was written: under it, remove → re-insert reproduces the file byte-for-byte for both a mid-file and an EOF-adjacent region, and five remove/append cycles produce zero drift.
Added
skills/generate-docs/marker-mechanics.test.py — the ownership-marker contract asserted as behaviour, so a later edit to the prose rules cannot quietly break re-run safety. 17 checks over five properties:
| Suite | Property |
|---|---|
| A | in-place update leaves human prose byte-identical, duplicates nothing, touches no other region |
| B | re-applying the same content is a no-op |
| C | removal takes the region without altering other content |
| D | keys outside the stable list are refused for both update and removal, and survive unrelated updates |
| E | insert/remove round-trip byte-for-byte, with no drift over repeated cycles |
Self-contained via an embedded fixture, or pass a path to check a real README:
python3 skills/generate-docs/marker-mechanics.test.py # embedded fixture
python3 skills/generate-docs/marker-mechanics.test.py FILE.md # a real READMEExit 1 on failure, matching the hooks/*.sh CLI convention. Passes against both the fixture and the README produced by the scaffold-mode test run.
Changed
CLAUDE.md's verification note lists the new test and no longer pins a plugin version number that had gone stale; it now states that the three plugins share one version and records the tag + GitHub release steps in the release flow.
Full changelog: CHANGELOG.md · CHANGELOG_ja.md