v0.17.1 — generate-docs: drift findings home, section removal, non-git targets
Exercising /architect:generate-docs against a real /product:generate-frontend scaffold surfaced three gaps in the skill. This release closes them.
Fixed
Drift findings had nowhere to go in scaffold mode. Step 5 said to report them to the user and append them to the Issue — but scaffold mode has no tracker, so a run had to invent a section key at write time. findings joins the stable key list, and a table now states where drift goes per mode:
| Mode | Where drift findings go |
|---|---|
| Delivery | Appended to the Issue as a comment — the tracker is the record, so nothing is written into the docs |
| Scaffold | Written to the findings section of the root README of the documented tree |
Drift is never resolved in prose either way: the docs must not assert a reconciliation the code has not made.
No removal rule. A marked section a later run no longer justifies — resolved drift, a deleted service, a surface that no longer exists — is now removed together with its markers and listed in the run report; a stale generated section is worse than a missing one. Only keys in the stable list may be removed, so hand-written content is never touched. Inventing a key outside the list is now forbidden, since an unrecognized key makes the region unfindable on the next run.
Non-git targets produced a raw git error. Delivery mode now states plainly that it cannot commit outside a git worktree and offers scaffold mode, which needs no repository.
Validation
Run against a hand-written, unmarked Japanese README in a real project:
- original prose preserved 24/24 lines — every generated region sat inside markers with a stable key
- verification confirmed 6/6 documented commands against
package.jsonand 18/18 cited paths - caught three genuine defects in the existing README: a page-count claim contradicted by the code (7 vs 8), three undocumented npm scripts, and build artifacts left in the scaffold tree
Full changelog: CHANGELOG.md · CHANGELOG_ja.md