plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md

@@ -96,19 +96,25 @@ Constraints:
   `validate.sh` emits it through `suggest()` and the run still exits 0.
 - **A Gotcha that paraphrases a step in the body below it is a FAIL.** It has no independent
   content, and it teaches the agent that Gotchas can be skimmed because the real instruction is
-  coming. This one is the auditor's call — no script detects it.
+  coming. This one is the auditor's call — no script detects it. The Fix is conditional: delete the
+  Gotcha only if the surviving copy is reachable from every branch that needs it — see the
+  reachability precondition below.
 - **A Gotchas section exceeding 25% of the body is a SUGGESTION** — the body has been inverted into
   a preamble. Same tier and same reasoning as the entry count, and independent of it: either can
   fire without the other.
 - Place the section near the top. A gotcha read after the mistake is worthless, which is also why
   Gotchas is the one construct exempt from moving to `references/`.
 
-Worked negative example — `git-commits` carries twelve entries, of which four restate content
+Worked negative example — **`git-commits` v0.1.2 at commit `5e23250`, a fixed pre-retrofit
-that already appears below or in the description:
+snapshot, not the current file.** The live skill is v0.1.3 and matches none of the citations below;
+they are quoted as they stood before the ADR-0020 retrofit, and are not to be refreshed against
+`HEAD`. Read the snapshot with
+`git show 5e23250:plugins/git/.apm/skills/git-commits/SKILL.md`. That body carried
+twelve Gotchas, four of which restated content already below them or already in the description:
 
 | Gotcha | Restates |
 |---|---|
-| `:31` "Communicates SemVer impact" | the description |
+| `:31` "SemVer mapping is not optional" | the description |
 | `:32` "Confirmation gates are mandatory for destructive operations" | step 9 at `:52` |
 | `:33` "Never skip hooks with `--no-verify`" | step 9 at `:52` |
 | `:36` "Never commit secrets" | step 2 at `:45` |
@@ -118,6 +124,25 @@ All four are FAILs under the paraphrase rule. The entry count and the section's
 fails the run on its own. What makes this worth auditing directly is that the four paraphrase FAILs
 pass every word gate there is; only reading the construct finds them.
 
+### The paraphrase rule has a reachability precondition
+
+**A Gotcha that restates a step may be deleted only when the surviving copy is reachable from every
+branch that needs it.** In a dispatch body it usually is not: each flow file is loaded alone, so a
+step in one is invisible to an invocation that took another branch. When the restated rule is a
+safety gate more than one flow needs, the Fix is to **move it into the body's common-gates section**,
+never to drop it in favour of the per-flow copy.
+
+Row four is the case that proves it. Following the rule literally, the retrofit deleted the
+always-loaded secrets Gotcha and kept step 2 of `references/create-commit.md` — but `git-commits`
+dispatches to exactly one flow file, and `references/rewrite-history.md` stages changes and runs
+`--amend`, which commits newly staged content exactly as a fresh commit does. A grep for `secret`
+across the skill in that state returned one hit, on a path two of three branches never reach: that
+branch could commit a credential with no check anywhere in its loaded context, against this repo's
+governance hard prohibition. v0.1.3 carries the rule as gate 2 of "Gates on every flow" instead.
+
+So check reachability before writing the Fix. Rows one to three are unaffected — the description is
+loaded on every invocation, and confirmation is likewise a common gate rather than a per-flow step.
+
 ## Calibrating control
 
 **Be prescriptive** when operations are fragile, consistency matters, or a specific sequence must be
@@ -153,7 +178,8 @@ Flag as FAIL if:
 - A sentence answers "no" to the core test — it is padding
 - The body exceeds 900 words counted body-only (`validate.sh` reports it)
 - Two or more mutually exclusive flows are inlined instead of dispatched
-- A Gotcha paraphrases a step in the body below it
+- A Gotcha paraphrases a step in the body below it that every branch reaching the Gotcha also
+  reaches
 - A decision point presents a menu of options with no default
 - An instruction repeats content already in the description
 - A prescriptive sequence is used where flexibility is fine, or the reverse

plugins/kyberforge/skills/skill-audit/references/body-discipline.md

@@ -96,19 +96,25 @@ Constraints:
   `validate.sh` emits it through `suggest()` and the run still exits 0.
 - **A Gotcha that paraphrases a step in the body below it is a FAIL.** It has no independent
   content, and it teaches the agent that Gotchas can be skimmed because the real instruction is
-  coming. This one is the auditor's call — no script detects it.
+  coming. This one is the auditor's call — no script detects it. The Fix is conditional: delete the
+  Gotcha only if the surviving copy is reachable from every branch that needs it — see the
+  reachability precondition below.
 - **A Gotchas section exceeding 25% of the body is a SUGGESTION** — the body has been inverted into
   a preamble. Same tier and same reasoning as the entry count, and independent of it: either can
   fire without the other.
 - Place the section near the top. A gotcha read after the mistake is worthless, which is also why
   Gotchas is the one construct exempt from moving to `references/`.
 
-Worked negative example — `git-commits` carries twelve entries, of which four restate content
+Worked negative example — **`git-commits` v0.1.2 at commit `5e23250`, a fixed pre-retrofit
-that already appears below or in the description:
+snapshot, not the current file.** The live skill is v0.1.3 and matches none of the citations below;
+they are quoted as they stood before the ADR-0020 retrofit, and are not to be refreshed against
+`HEAD`. Read the snapshot with
+`git show 5e23250:plugins/git/.apm/skills/git-commits/SKILL.md`. That body carried
+twelve Gotchas, four of which restated content already below them or already in the description:
 
 | Gotcha | Restates |
 |---|---|
-| `:31` "Communicates SemVer impact" | the description |
+| `:31` "SemVer mapping is not optional" | the description |
 | `:32` "Confirmation gates are mandatory for destructive operations" | step 9 at `:52` |
 | `:33` "Never skip hooks with `--no-verify`" | step 9 at `:52` |
 | `:36` "Never commit secrets" | step 2 at `:45` |
@@ -118,6 +124,25 @@ All four are FAILs under the paraphrase rule. The entry count and the section's
 fails the run on its own. What makes this worth auditing directly is that the four paraphrase FAILs
 pass every word gate there is; only reading the construct finds them.
 
+### The paraphrase rule has a reachability precondition
+
+**A Gotcha that restates a step may be deleted only when the surviving copy is reachable from every
+branch that needs it.** In a dispatch body it usually is not: each flow file is loaded alone, so a
+step in one is invisible to an invocation that took another branch. When the restated rule is a
+safety gate more than one flow needs, the Fix is to **move it into the body's common-gates section**,
+never to drop it in favour of the per-flow copy.
+
+Row four is the case that proves it. Following the rule literally, the retrofit deleted the
+always-loaded secrets Gotcha and kept step 2 of `references/create-commit.md` — but `git-commits`
+dispatches to exactly one flow file, and `references/rewrite-history.md` stages changes and runs
+`--amend`, which commits newly staged content exactly as a fresh commit does. A grep for `secret`
+across the skill in that state returned one hit, on a path two of three branches never reach: that
+branch could commit a credential with no check anywhere in its loaded context, against this repo's
+governance hard prohibition. v0.1.3 carries the rule as gate 2 of "Gates on every flow" instead.
+
+So check reachability before writing the Fix. Rows one to three are unaffected — the description is
+loaded on every invocation, and confirmation is likewise a common gate rather than a per-flow step.
+
 ## Calibrating control
 
 **Be prescriptive** when operations are fragile, consistency matters, or a specific sequence must be
@@ -153,7 +178,8 @@ Flag as FAIL if:
 - A sentence answers "no" to the core test — it is padding
 - The body exceeds 900 words counted body-only (`validate.sh` reports it)
 - Two or more mutually exclusive flows are inlined instead of dispatched
-- A Gotcha paraphrases a step in the body below it
+- A Gotcha paraphrases a step in the body below it that every branch reaching the Gotcha also
+  reaches
 - A decision point presents a menu of options with no default
 - An instruction repeats content already in the description
 - A prescriptive sequence is used where flexibility is fine, or the reverse