feat: harden /coding:self-improve placement — discovery, ladder, admission argument

CHANGELOG.md

@@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/).
 * MINOR version when you add functionality in a backwards-compatible manner, and
 * PATCH version when you make backwards-compatible bug fixes.
 
+## Unreleased
+
+- feat: `/coding:self-improve` Step 5 becomes an adversarial placement procedure — (5a) mandatory discovery (semantic search + Glob/Grep) that must name 2–3 concrete candidate homes before any routing, with query discipline (search the workflow/domain name, not the rule text; guides often live outside the repo) and a no-forfeit rule (empty discovery never routes to a CLAUDE.md — a memory target must beat a named alternative), (5b) a 5-rung placement ladder (repair misfiring artifact → extend point-of-mistake artifact → point-of-use guide/runbook → project CLAUDE.md → global CLAUDE.md) where descending requires naming the rung's STRONGEST discovery candidate — quoting a heading from the guide/runbook candidate to prove it was opened — and why it can't own the fix, and (5c) a 4-part global-CLAUDE.md admission argument (always-on with dead-weight counter-test, unowned, behavioral-not-procedural, one stable line) plus a de-generalization test (a rule whose un-generalized wording names a workflow step is procedural — rewording it to sound behavioral is the tell of a misroute) with auto-demotion to the best discovered home when any argument fails; Step 2 records candidates as incidents and forbids drafting rule wording before placement; output's `Artifacts checked:` line replaced by a `Placement:` ladder trace; adds `mcp__semantic-search__search_related` to allowed-tools. Hardens the v0.30.0 artifact-first routing after a session where a PR-workflow rule was still proposed for global CLAUDE.md despite a domain guide with exact neighboring bullets being one search away.
+
 ## v0.30.2
 
 - fix: migrate MacPorts paths to Homebrew across `shellcheck-assistant` (`/opt/local/bin/shellcheck` → `/opt/homebrew/bin/shellcheck` in allowed-tools + docs, drop `port install`), `license-assistant` (`gdate` for current year), and the toolchain-preflight/scaling/findings scenarios (`ast-grep` → `/opt/homebrew/bin/ast-grep`) — MacPorts was removed in the local MacPorts→Homebrew migration.

commands/self-improve.md

@@ -1,6 +1,6 @@
 ---
 description: Review THIS session and propose at most two durable improvements to the Claude Code environment (commands, agents, skills, guides, runbooks, memory/CLAUDE.md rules). Default outcome is "nothing worth keeping."
-allowed-tools: Read, Edit, Glob, Grep
+allowed-tools: Read, Edit, Glob, Grep, mcp__semantic-search__search_related
 ---
 
 # Self Improve
@@ -35,6 +35,11 @@ Scan the transcript for:
 
 Ignore anything that happened once with no cost. One-offs never graduate.
 
+Record each candidate as an **incident** — what happened, what it cost — not
+as a rule. Do NOT draft rule wording or a diff sketch until Step 5 has chosen
+the home: wording drafted early comes out CLAUDE.md-shaped (a terse imperative
+bullet) and biases placement toward memory files.
+
 ### 3. Rate each candidate
 Gate first, then grade — the same shape as `/vault-cli:reflect`'s significance filter.
 
@@ -50,7 +55,7 @@ Passers get a **worth-it score**:
 | Generality — the fix applies beyond this one task / project / file | +1 |
 | Repair — fixes a tool that misfired, not a new rule bolted on | +1 |
 | Obvious-anyway — the "fix" is just doing the naturally obvious thing | −2 |
-| Routes to a `CLAUDE.md` though an existing artifact could own it (judged after Step 5 routing) | −1 |
+| Routes to a `CLAUDE.md` though an existing artifact could own it (judged after Step 5 placement) | −1 |
 
 Tier by score:
 - **≥ 3 → propose** (ranked, max two)
@@ -65,31 +70,81 @@ Does an existing rule / command / agent / skill almost cover this? If yes,
 propose a small edit to it. Only propose a NEW artifact when nothing existing
 is close.
 
-### 5. Route the fix — artifact first, CLAUDE.md last
-
-Before routing anything to a `CLAUDE.md`, check whether an existing artifact
-could own the fix: slash command, skill, agent, guide, runbook. The fix belongs
-in the artifact that is already loaded when the mistake happens.
-
-| The fix is a… | It belongs in… |
-|---|---|
-| Misfire OR gap in an existing command / agent / skill | that artifact (repair / extend it) |
-| Step missing from an operational procedure | the runbook that documents it |
-| Knowledge gap in a documented system | the guide that owns the topic |
-| The exact same prompt, retyped | a slash command |
-| An independent responsibility | an agent |
-| Reusable multi-step capability with scripts/state | a skill |
-| Project convention no artifact can enforce | that project's `CLAUDE.md` |
-| Global habit no artifact could ever own | global `CLAUDE.md` (last resort) |
-
-**CLAUDE.md is the last resort, not the default.** Memory files must stay short
-and precise — every rule added there is prompt overhead in every future session.
-A proposal targeting a `CLAUDE.md` must name which artifacts were checked and
-why none could own the fix (the `Artifacts checked:` output line). A rule that
-merely restates what an artifact should enforce itself, or tells the operator to
-work around a broken tool, is a symptom patch — repair the tool instead; fall
-back to a `CLAUDE.md` rule only when the tool genuinely can't be changed
-(external constraint).
+### 5. Place the fix — discover, walk the ladder, argue the exception
+
+Placement is a search problem, not a routing decision. The reasoning that
+generated a proposal is biased toward memory files (always loaded, zero
+discovery cost) — counter that bias with mandatory discovery and a burden of
+proof on the CLAUDE.md target.
+
+**5a. Discovery (mandatory, before any routing).** Search for existing homes:
+semantic search over the vault(s) when available
+(`mcp__semantic-search__search_related "<topic>"`), plus Glob/Grep over
+`commands/`, `skills/`, `agents/`, and the project's guide/runbook dirs. List
+the top 2–3 candidate homes found, as file paths. No named candidates means
+you haven't searched — do not route yet.
+
+Query discipline: search the **workflow/domain name** ("development guide PR
+workflow", "deploy runbook"), not the rule text you have in mind — rule-text
+queries return junk and fake an empty result. Minimum two queries. Note that
+guides and runbooks often live OUTSIDE the repo (e.g. an Obsidian vault), so
+semantic search is the primary channel and Glob/Grep over the cwd alone is
+insufficient evidence that no home exists.
+
+**Empty discovery never routes to a CLAUDE.md.** If no home is found, propose
+creating/extending a guide in the domain's knowledge dir, or output "no home
+found — operator decides". A CLAUDE.md target must BEAT a named alternative;
+it never wins by forfeit.
+
+**5b. The ladder.** Work down the rungs. To descend past a rung you must NAME
+the concrete candidate at that rung and give a one-line reason it cannot own
+the fix. "Nothing fits" without a filename is not a reason. The candidate you
+name must be the STRONGEST discovery hit for that rung — not a straw man you
+can safely reject — and for the guide/runbook rung you must quote one heading
+or line from the candidate file to prove it was actually opened.
+
+1. The artifact that misfired → repair it.
+2. The artifact already loaded at the moment of the mistake (command / skill /
+   agent step) → extend it.
+3. The guide or runbook read at point-of-use for that workflow → add the rule
+   where it is read in context.
+4. Project `CLAUDE.md` → only for a project convention no artifact can enforce.
+5. Global `CLAUDE.md` → the exception. Requires the admission argument below.
+
+New artifacts (slash command for a retyped prompt, agent for an independent
+responsibility, skill for a multi-step capability with scripts/state) sit on
+rungs 2–3: create one only when discovery proves nothing existing is close.
+
+**5c. Global CLAUDE.md admission argument.** A proposal may target the global
+memory only if ALL FOUR hold, argued one line each in the output:
+
+- **Always-on:** matters in sessions unrelated to its domain. Counter-test:
+  name one plausible session type where the line is dead weight — if you can
+  name one, it fails.
+- **Unowned:** name the closest artifact/guide from discovery and why it is
+  not (and cannot be) loaded at the moment the rule applies.
+- **Behavioral, not procedural:** shapes conduct everywhere ("be terse",
+  "English only") — not a step in any workflow. Workflow steps always have a
+  point-of-use home.
+- **One stable line:** expressible as one terse imperative bullet that will
+  not churn when tools change.
+
+**De-generalization test** (apply before grading Always-on): state the rule
+with its workflow named — "when opening a PR, run X"; "when deploying, check
+Y". If the un-generalized version names a workflow step, the rule is
+procedural and belongs at that step's point-of-use home. Generalizing the
+wording until it sounds behavioral is the tell of a misroute, not a pass —
+gates test the incident, not the phrasing.
+
+Any argument missing or hand-wavy → auto-demote the proposal to the best named
+home from discovery. If the target memory file already feels long, also
+nominate one existing line to demote to a guide (soft one-in-one-out).
+
+Memory files are prompt overhead in every future session. A rule that merely
+restates what an artifact should enforce itself, or tells the operator to work
+around a broken tool, is a symptom patch — repair the tool instead; fall back
+to a `CLAUDE.md` rule only when the tool genuinely can't be changed (external
+constraint).
 
 ### 6. Output
 Short. Max two proposals, ranked.
@@ -100,7 +155,7 @@ Per proposal:
 - **Change:** what, and where (exact target file / artifact)
 - **Worth-it:** <score> (e.g. recurrence +2, cost +1)
 - **Evidence:** verbatim quote(s) + how often
-- **Artifacts checked:** which existing artifacts were considered; mandatory when targeting a `CLAUDE.md` (name why none could own the fix)
+- **Placement:** discovery hits (top candidate homes as file paths) + the ladder walk (rung → named candidate → one-line why-not), ending at the chosen home; global-`CLAUDE.md` targets append the four admission-argument lines
 - **Edit or new:** if new, why nothing existing fit
 - **Diff sketch:** the concrete line(s) to add or change
 
@@ -128,5 +183,6 @@ Never edit beyond the approved proposals. Never expand scope while applying.
 - Default to zero. Two is the ceiling.
 - Edit existing before creating new.
 - No quote, no proposal.
+- Placement is discovered, not assumed — a `CLAUDE.md` target must survive the admission argument.
 - Fix the cause (missing rule/tool), not the symptom (one bad turn).
 - Every permanent rule you add, someone maintains forever.