fix(kyberforge): resolve PR #144 review and audit round 3

- factory-audit: hook events judged per deployed target after apm's
  rename (Claude/Copilot event sets FAIL, others SUGGESTION); Claude
  plugin layouts accepted as hook sources; interpreter options and
  sh -c strings checked; bats 378 -> 386
- primitive-author: Must 4/5 match the audit; reference hand-back
  points at the right steps; Step 4.2 --target all fallback
- skill-author: new-skill.sh repair only on the template marker line,
  so complete skills stay a no-op; provenance and calibration text
- forge: restore "already named" qualifier; drop false HITL claim
- apm-workflow: token example uses an env var
- docs/hooks.md: the apm-hooks.json sidecar is committed, not ignored

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi

plugins/kyberforge/.apm/skills/skill-author/references/contract.md

@@ -153,9 +153,10 @@ an edit to either belongs in both.
 
 **Dispatch is mandatory at two or more mutually exclusive flows.** The body carries the dispatch
 table and the gates common to every branch; each flow gets its own self-contained `references/`
-file. Exemplar: the `apm-workflow` skill — a **294-word body** dispatching to 3,154 words of
-references across five flow files. Calibrate against 294: that file's whole-file count is 348
-words, and aiming at that number instead overshoots the body budget by ~18%. The 3,154 excludes
+file. Exemplar: the `apm-workflow` skill — a body of roughly 240 words dispatching to over
+3,000 words of references across five flow files. Calibrate against the body-only count
+`factory-audit` reports, not the whole-file count: there the whole file runs about a fifth larger,
+so aiming at it overshoots the body budget by that much. The reference total excludes
 `references/sources.md`, which is a provenance record and is never loaded at runtime.
 
 **Length.** 600 words SUGGESTION, 900 words FAIL, counting the **body only** — everything after

plugins/kyberforge/.apm/skills/skill-author/references/improve.md

@@ -85,8 +85,9 @@ Still over after all four means the skill does two jobs: split it rather than co
 
 **Re-cite what moved.** After content moves between files, update `references/sources.md`'s
 `Contributing files` for every slug whose content moved, and drop any file the edit deleted.
-`factory-audit`'s `scripts/validate-provenance.sh` exits 0 on exactly that drift, so a stale
-provenance claim ships unless you fix it here.
+`factory-audit`'s `scripts/validate-provenance.sh` fails a listed file that no longer exists, but
+exits 0 when content moved out of a file that still exists and still lists the slug, so that stale
+claim ships unless you fix it here.
 
 **Re-check every relocated gate's reachability.** A Gotcha or gate moved out of the body into one
 flow's `references/` file is invisible to every other branch, and the word counts improve either

plugins/kyberforge/.apm/skills/skill-author/scripts/new-skill.sh

@@ -153,39 +153,49 @@ else
   TARGET="$TARGET_INPUT/$SKILL_NAME"
 fi
 
-# Files carrying the SKILL_NAME placeholder token.
+# Files carrying the SKILL_NAME placeholder token, each paired with the exact
+# template line that marks it as still unsubstituted. Only that whole line
+# counts: a finished skill may legitimately mention SKILL_NAME in its prose.
 SUBST_FILES=("SKILL.md" "tests/README.md")
+SUBST_MARKERS=("name: SKILL_NAME" "bats <destination-dir>/SKILL_NAME/tests/")
 
-# Replace SKILL_NAME in each placeholder file under dir $1. `sed -i` is not
-# portable — GNU takes an optional attached suffix, BSD/macOS requires a
-# separate suffix argument and reads the expression as one — so write to a
-# temp file and move it over the original instead.
-substitute_name() {
-  local dir="$1" rel f
-  for rel in "${SUBST_FILES[@]}"; do
-    f="$dir/$rel"
-    [[ -f "$f" ]] || continue
-    sed "s/SKILL_NAME/$SKILL_NAME/g" "$f" > "$f.tmp"
-    mv "$f.tmp" "$f"
-  done
+# Replace SKILL_NAME in one file. `sed -i` is not portable — GNU takes an
+# optional attached suffix, BSD/macOS requires a separate suffix argument and
+# reads the expression as one — so write to a temp file and move it over.
+substitute_file() {
+  local f="$1"
+  sed "s/SKILL_NAME/$SKILL_NAME/g" "$f" > "$f.tmp"
+  mv "$f.tmp" "$f"
 }
 
-# True if any placeholder file under dir $1 still carries the SKILL_NAME token.
-has_placeholder() {
+# Substitute every placeholder file under dir $1 (a fresh template copy).
+substitute_name() {
   local dir="$1" rel
   for rel in "${SUBST_FILES[@]}"; do
-    if [[ -f "$dir/$rel" ]] && grep -q 'SKILL_NAME' "$dir/$rel"; then
-      return 0
+    [[ -f "$dir/$rel" ]] && substitute_file "$dir/$rel"
+  done
+  return 0
+}
+
+# Substitute only the placeholder files under dir $1 that still carry their
+# template marker line; print how many were repaired.
+repair_placeholders() {
+  local dir="$1" i f n=0
+  for i in "${!SUBST_FILES[@]}"; do
+    f="$dir/${SUBST_FILES[$i]}"
+    if [[ -f "$f" ]] && grep -qxF "${SUBST_MARKERS[$i]}" "$f"; then
+      substitute_file "$f"
+      n=$((n + 1))
     fi
   done
-  return 1
+  echo "$n"
 }
 
 if [[ -d "$TARGET" ]]; then
-  # A scaffold left half-built by an earlier failed run still carries the
-  # placeholder token; finish it instead of reporting a silent no-op.
-  if has_placeholder "$TARGET"; then
-    substitute_name "$TARGET"
+  # A scaffold left half-built by an earlier failed run still carries a
+  # template marker line; finish it instead of reporting a silent no-op.
+  # Anything else — including a complete skill — is left untouched.
+  if [[ "$(repair_placeholders "$TARGET")" -gt 0 ]]; then
     echo "Repaired partial scaffold at '$TARGET' — substituted SKILL_NAME." >&2
     exit 0
   fi

plugins/kyberforge/.apm/skills/skill-author/tests/new-skill.bats

@@ -132,6 +132,25 @@ teardown() {
     assert_success
 }
 
+@test "a complete skill whose text mentions SKILL_NAME stays a true no-op" {
+    # Only the template's exact marker lines mark a half-built scaffold. A
+    # finished skill that merely mentions the token must not be rewritten.
+    mkdir -p "$DEST/my-tool/tests"
+    printf -- '---\nname: my-tool\n---\n\nUse `__SKILL_NAME_PLACEHOLDER__` here.\n' \
+        > "$DEST/my-tool/SKILL.md"
+    printf 'Set SKILL_NAME before running.\n' > "$DEST/my-tool/tests/README.md"
+    cp "$DEST/my-tool/SKILL.md" "$DEST/skill.orig"
+    cp "$DEST/my-tool/tests/README.md" "$DEST/readme.orig"
+    run bash "$SCRIPT" my-tool "$DEST"
+    assert_success
+    assert_output --partial "nothing to do"
+    refute_output --partial "Repaired"
+    run cmp "$DEST/skill.orig" "$DEST/my-tool/SKILL.md"
+    assert_success
+    run cmp "$DEST/readme.orig" "$DEST/my-tool/tests/README.md"
+    assert_success
+}
+
 # ---------------------------------------------------------------------------
 # Mode detection: package vs standalone
 # ---------------------------------------------------------------------------