docs(repo-hygiene): surface reset --hard non-atomicity caveat on exit-5 gate (#485)

[kyle-sexton]

Summary

The exit-5 gate bullet in plugins/repo-hygiene/skills/clean/context/git-tree-reset.md accurately described the gating contract but was incomplete relative to the runtime stderr message: it did not tell a doc-only reader that a failed reset --hard may have partially modified tracked files before it failed. This is a one-line doc-consistency fix (patch bump 0.4.1 → 0.4.2).

Fix

Added a parenthetical to the exit-5 bullet so the context doc is consistent with the exit-5 stderr message the script already emits.

Verification

Doc — before (git-tree-reset.md):

• Aborts the apply if reset --hard fails (exit 5) — clean and the restore guard never run, so a failed reset can never leave the tree cleaned but not reset.

Doc — after:

• Aborts the apply if reset --hard fails (exit 5) — clean and the restore guard never run, so a failed reset can never leave the tree cleaned but not reset (the reset itself may have partially modified tracked files, since reset --hard is not atomic).

Script stderr it stays consistent with (skills/clean/scripts/git-tree-reset.sh, exit-5 path):

if ! git reset --hard "$UPSTREAM"; then
  printf 'FAILED: git reset --hard %s exited non-zero — aborting apply; git clean skipped. Note: reset --hard is not atomic and may have partially modified tracked files.\n' "$UPSTREAM" >&2
  ...
  exit 5

The added parenthetical ("the reset itself may have partially modified tracked files, since reset --hard is not atomic") mirrors the script's stderr wording ("reset --hard is not atomic and may have partially modified tracked files"). No behavioral change; docs only.

Closes #485

Related

• Follow-up to docs(repo-hygiene): git-tree-reset context doc omits reset --hard non-atomicity caveat (exit 5) #485 (this issue).
• Deferred from PR fix(repo-hygiene): gate git-tree-reset clean on reset success #460 (fixes fix(repo-hygiene): git-tree-reset runs clean -fdx even when reset --hard failed (partial destructive op) #394) — the parenthetical was flagged in the fix(repo-hygiene): gate git-tree-reset clean on reset success #460 review but left unfixed to preserve that PR's merge-ready head SHA (745def6, the commit that added the stderr caveat).

🤖 Generated with a Claude Code implementation subagent (issue #485)

[claude]

Claude finished @kyle-sexton's task in 1m 9s —— View job

---

PR Review

• Gather context and understand the request
• Review PR diff
• Read changed files
• Verify consistency with referenced script
• Post review findings

---

Summary: This is a clean, minimal, docs-only patch. No behavioral changes. Three files touched: a version bump, a CHANGELOG entry, and a one-line documentation update.

---

git-tree-reset.md — exit-5 bullet

Line 39

The added parenthetical is factually correct and precisely mirrors the existing stderr message in git-tree-reset.sh at line 218:

FAILED: git reset --hard %s exited non-zero — aborting apply; git clean skipped.
Note: reset --hard is not atomic and may have partially modified tracked files.

Doc (after): (the reset itself may have partially modified tracked files, since reset --hard is not atomic)

The two phrasings convey identical semantics — just sequenced differently. The parenthetical placement is structurally correct: the original bullet describes the gating contract (clean and the restore guard never run), and the parenthetical scopes the caveat specifically to what the failed reset itself may have done before bailing. That's the right level of precision — it doesn't weaken or contradict the gating guarantee, it surfaces the orthogonal pre-failure state concern.

plugin.json — version bump

0.4.1 → 0.4.2 is the correct semver tier for a docs-only change.

CHANGELOG.md

The [0.4.2] entry is thorough, well-written, and accurately describes what changed and why. Uses ### Fixed which is appropriate for a doc-consistency fix.

Minor observation (pre-existing, not introduced here): Keep a Changelog spec recommends date suffixes on version headers (## [0.4.2] - 2026-07-20). The entire changelog omits dates — this PR is consistent with prior entries, so no regression, but worth noting if the project ever wants to align with the spec more strictly.

---

Verdict: Looks good. The change is correct, minimal, and consistent with the script. No issues to block merge.

[claude]

Claude finished @kyle-sexton's task in 58s —— View job

---

PR Review

• Gather context and understand the request
• Review PR diff
• Read changed files
• Verify consistency with referenced script
• Post review findings

---

This is a clean, minimal, docs-only patch. Three files touched: a one-line documentation update, a version bump, and a CHANGELOG entry.

git-tree-reset.md — exit-5 bullet

Line 39

The added parenthetical is factually correct and precisely mirrors the script's existing stderr at git-tree-reset.sh line 218:

Note: reset --hard is not atomic and may have partially modified tracked files.

Doc (after): (the reset itself may have partially modified tracked files, since reset --hard is not atomic)

The two phrasings are semantically identical — sequenced differently but conveying the same information. The parenthetical placement is structurally correct: it scopes the caveat to what the failed reset itself may have done before bailing, without weakening or contradicting the gating guarantee (clean and the restore guard never run on exit 5).

plugin.json — version bump

0.4.1 → 0.4.2 is the correct semver tier for a docs-only patch.

CHANGELOG.md

The [0.4.2] entry is accurate and well-structured. Uses ### Fixed — appropriate for a doc-consistency fix. The description correctly characterizes both what was omitted (the partial-modification caveat) and why the original wasn't wrong (the gating contract remains intact).

Minor observation (pre-existing, not introduced here): Keep a Changelog spec recommends date suffixes on version headers (## [0.4.2] - 2026-07-20). The entire changelog omits dates and this PR is consistent with prior entries — no regression, but worth aligning if the project ever wants to follow the spec strictly.

---

Verdict: Looks good. The change is correct, minimal, and fully consistent with the script. No issues to block merge.