Merge chore/graphify-recovery-doc into develop

.claude/memory/journal.md

@@ -469,3 +469,5 @@ rules:
 - `doctor.sh` gained `check_automode` (missing `$defaults`, foreign-repo scope, both arms tested). `SETTINGS.md` documents the block + a tier-choice table. README's magic-MCP "ask = live confirmation" claim corrected — false under `defaultMode: auto`.
 - Found, not fixed: `.claude/settings.local.json` = 14.6 KB shadow copy of the global settings at HIGHER precedence, incl. a `config-protection.sh` hook whose script does not exist. Logged F1-F3 in TODO.
 - `make test` 0 RED, `doctor.sh` 0 errors, `shellcheck` clean.
+- graphify skill untracked + gitignored (written by `graphify install --platform claude` since `~/.claude/skills` symlinks to `skills/`). Cost one self-inflicted incident: `git rm --cached` kept the files, `gitflow finish` deleted them at the merge ([[LRN-154]]). Restored at 0.9.61, guarded configs snapshotted and verified untouched.
+- `.claude/settings.local.json` 14.6 KB -> 6.2 KB. It was not just duplication: its local `deny` still carried the 4 rules moved out of global deny, making [[BDR-090]]'s soft_deny a dead letter in this repo, and its `allow` carried `sed *` / `cp *` / `python3 -`, which short-circuit the classifier on the same rules.

.claude/memory/learnings.md

@@ -143,6 +143,7 @@ rules:
 | LRN-151 | 2026-09-15 | Playwright cache truth = union over `.links`, dir name maps `_`→`-`, revisionOverrides exist | shared versioned binary caches |
 | LRN-152 | 2026-09-15 | git `protocol.file=user` blocks submodule fixtures; `-c` misses the code under test, `GIT_CONFIG_*` env does not | tests building git fixtures |
 | LRN-153 | 2026-09-15 | `autoMode` lists replace built-ins without `"$defaults"`; a user-scope block reaches every project | any `autoMode` edit |
+| LRN-154 | 2026-09-15 | `git rm --cached` + merge into a branch that still tracks the file DELETES it from disk | untracking a generated file |
 
 ---
 
@@ -1460,3 +1461,11 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s
 - **Backstop**: `doctor.sh` `check_automode` warns on a list missing `$defaults` and on a user-scope `environment` naming a git repo other than the config repo. Both arms exercised against the defective block before shipping.
 - **Future application**: any `autoMode` edit — check `$defaults` presence and scope before anything else.
 - **Reference**: `doctor.sh`, `templates/settings/SETTINGS.md`. Links [[BDR-090]].
+
+## LRN-154 — Untracking a generated file then merging deletes it from disk
+- **Date**: 2026-09-15
+- **Pattern**: `git rm --cached` removes from the index and KEEPS the working file, which is the whole point when untracking a tool-generated artifact. But `gitflow finish` checks out the target branch first, where the file is still tracked, so git restores it; the merge then applies the deletion to a tracked file and removes it from disk. `.gitignore` does not protect it — it only stops a re-add. Net effect: the file survives the commit and dies at the merge, several minutes later, which reads as unrelated.
+- **Detection**: the working tree is clean and the file is simply absent. Nothing errors. Only a post-merge `ls` catches it.
+- **Future application**: untracking any generated file — know the regeneration command BEFORE merging, and `ls` the path right after `finish`. If nothing regenerates it, keep it tracked.
+- **graphify specifics**: `graphify install --platform claude` copies the skill and touches nothing else. `graphify claude install` is a different command — it writes the CLAUDE.md section and the `.claude/settings.json` hooks, rewrites both guarded configs, and does NOT copy the skill. Confusing the two wastes a recovery attempt.
+- **Reference**: `CLAUDE.md` machine-owned section, commit 80ccdaf. Links [[BDR-090]].

CLAUDE.md

@@ -37,13 +37,27 @@ or re-run `make plugin`.
 (`install-plugins.sh` STEP graphify), which lands in the repo because
 `~/.claude/skills` is a symlink to `skills/`. They are gitignored: a
 `pipx upgrade graphifyy` used to dirty the tree and cost a
-`chore(graphify): sync vendored skill X -> Y` commit each time. A fresh
-clone gets them back from `make plugin`.
+`chore(graphify): sync vendored skill X -> Y` commit each time.
+
+Two graphify commands, easy to confuse, and only one restores the skill:
+- `graphify install --platform claude` copies SKILL.md + `references/` +
+  `.graphify_version` into `skills/graphify/`. Touches nothing else.
+  This is the recovery command.
+- `graphify claude install` writes the CLAUDE.md graphify section and the
+  `.claude/settings.json` PreToolUse hooks. It **rewrites both guarded
+  configs** (EVAL-020, verified again 2026-09-15), so revert them after. It does NOT copy
+  the skill.
+
+`make plugin` runs both (`install-plugins.sh` STEP graphify) behind the
+guarded-config EXIT trap, so a fresh clone is covered.
 
 Trade-off accepted: an upstream release can now change the skill's prompt
 with no diff to review. `skills/graphify/test-prompts.json` is hand-written
-for darwin and stays tracked. To inspect what upstream changed, read the
-files on disk or diff against a previous `pipx` version.
+for darwin and stays tracked.
+
+Gotcha, learned the hard way: `git rm --cached` keeps the working file,
+but if the branch you merge into still tracks it, the merge deletes it
+from disk. Untrack and merge, then restore with the command above.
 
 ## Transient planning artifacts