feat(prompts): change-oriented "what to watch when editing" guidance on map nodes

src/templates-source/prompts/proposal-extract.md

@@ -1,7 +1,7 @@
 # Proposal Extraction Prompt
 
 <!--
-  Version: 4
+  Version: 5
   Used by: the kk-proposal-drain hook (via a headless harness session)
   Owner contract: produces the structured `proposals.practice` and `proposals.map` arrays
   for a session log. Must emit one JSON object on stdout as the final message.
@@ -111,6 +111,8 @@ These describe the entities, features, vocabulary, and locations of the project:
 
 **Map nodes can be extracted from either `[USER]:` or `[AGENT]:` turns.** Sometimes the agent surfaces a module name or file location during exploration that's worth recording. Both roles are valid sources.
 
+**Optional change-oriented clause (evidence-gated).** When the transcript actually surfaces what an editor must watch for when changing this entity — a check to run, an invariant to preserve, a related rule that constrains edits — you may end the map body with one short "When changing this, verify…" sentence that captures it. Include it only when the session evidenced the guidance; never invent a watch-out to fill a template. If nothing in the transcript speaks to editing the entity, omit the clause entirely.
+
 ---
 
 ## What you are NOT looking for

src/templates-source/skills/kk-bootstrap/SKILL.md.hbs

@@ -3,7 +3,7 @@ name: kk-bootstrap
 description: First-time bootstrap of the project knowledge base from existing markdown documentation. Surveys docs, follows cross-references, and writes new node files directly under `.ai/kenkeep/nodes/`. Supervised by the user, who reviews each node on disk before accepting or deleting it. Use when the user wants to seed an empty knowledge base from the project's existing docs.
 ---
 
-<!-- Version: 5 -->
+<!-- Version: 6 -->
 
 # kk-bootstrap
 
@@ -79,6 +79,8 @@ Triggers in docs: imperative verbs ("use," "do," "avoid," "always," "never," "mu
 
 Triggers in docs: section headers naming components ("## Bravo Cards Module"); definition patterns ("X is our service for Y"); explicit file-path references ("`modules/custom/x/`").
 
+**Optional change-oriented clause (evidence-gated).** When the source doc states what to watch for when changing this entity — a check to run, an invariant to preserve, a related rule that constrains edits — you may end the map body with one short "When changing this, verify…" sentence that captures it. Add it only when the doc evidences it; never invent watch-out guidance to fill a template. If the doc says nothing about editing the entity, omit the clause.
+
 When a piece of content has both aspects (e.g. "Use bravo_analytics.dispatcher, our service for tracking events"), split it: practice owns "use the dispatcher"; map owns "what the dispatcher is."
 
 **Skip** (content judgement only; filename-pattern skips are already handled by `finddocs`):

src/templates-source/skills/kk-curate/SKILL.md.hbs

@@ -3,7 +3,7 @@ name: kk-curate
 description: Curate pending session logs into kenkeep nodes by reading sessions in-host, drafting curator actions, then deduping and persisting via the kenkeep primitives. Resolves any surfaced contradictions interactively with the user. Use when the user wants to process accumulated session captures, or when the SessionStart nudge reports pending session logs.
 ---
 
-<!-- Version: 10 -->
+<!-- Version: 11 -->
 
 # kk-curate
 
@@ -184,7 +184,7 @@ Use when the candidate should not result in any change. Reasons to drop:
 The knowledge base is a nested topical folder tree under `nodes/`: a root index node, branch index nodes, and leaves at any depth. For every `add`, run a single reasoning pass that produces two outputs at once: the cross edges and the home branch. Do not make a second pass.
 
 1. **Descend the tree.** Start from the root index node (`nodes/index.md`) and follow it into the branch index nodes whose summaries are relevant to the candidate. The index nodes list their child folders and leaves, so you can walk toward the nearest existing notes the same way discovery does.
-2. **Set the cross edges.** From the nearest existing leaves, set `kk_relates_to` (and `kk_depends_on` where one node genuinely depends on another) by id. Edges resolve by id and are independent of where the leaf lives.
+2. **Set the cross edges.** From the nearest existing leaves, set `kk_relates_to` (and `kk_depends_on` where one node genuinely depends on another) by id. Edges resolve by id and are independent of where the leaf lives. For a **map** node in particular, prefer `kk_relates_to` edges to the practice nodes that govern changing that entity — the "watch out when editing this" knowledge lives in those practices, and the edge is what lets an agent reach it from the map node. When the candidate or its session evidenced a concrete edit-time check, also keep a short optional "When changing this, verify…" clause in the map body; never invent one to fill a template.
 3. **Rank the home branch.** From the same descent, rank the existing index nodes (folders) by how well their subtree fits the candidate's topic, and pick the single best-fitting existing folder. Record it on the action as `home_folder` (a topical path relative to `nodes/`, e.g. `cli` or `knowledge-base/index`). Identity is the id and never depends on the chosen folder.
 4. **Root fallback.** If no existing folder clears your relevance bar, leave `home_folder` unset/null/empty. The writer then places the leaf at the `nodes/` root. This is a deliberate, visible outcome, not an error; a later rebalance pass relocates it. Never force a weak fit just to avoid the root.
 

src/templates-source/skills/kk-curate/batch-agent-prompt.md

@@ -11,6 +11,7 @@ Read this before dispatching a drafting sub-agent on the parallel path (Step 2).
 >     - **modify**: an existing node covers the same scope and the candidate refines it without negating it; verify `target_node_id` exists on disk first; rewrite the merged body in present-tense end-state (no "previously…" prose). Apply the shared modification-restraint criteria in `.ai/kenkeep/.config/prompts/knowledge-admission.md`: prefer a minimal in-place edit over a rewrite, never churn an accurate node, trace every edit to the specific proposal/conflict that caused it (impact-plan style: source change → node affected → edit needed → why), and never make formatting-only edits — a tidy-only change is a `drop`.
 >     - **contradict**: candidate directly negates an existing valid node (both cannot be true at the same scope); set `target_node_id` to the tightest-scope match.
 >     - **drop**: near-rephrasing, low-signal, general programming knowledge, change-oriented framing, non-productive provenance signals, or anything ruled out by the shared knowledge admission criteria (maintenance/lifecycle actions, project story or any plan/ticket/issue reference, incidental one-off facts dressed up as practices — full criteria and the six-months keep test in `.ai/kenkeep/.config/prompts/knowledge-admission.md`); `target_node_id: null`, `proposed_node: null`.
+> - For a **map** candidate, set `kk_relates_to` to the practice nodes that govern changing that entity (the "watch out when editing this" knowledge lives there), and keep a short optional "When changing this, verify…" clause in the body only when the session evidenced a concrete edit-time check — never invent one.
 > - Hard constraints: never cross the practice/map boundary; `proposed_node` keys are `title|type|tags|description|body|kk_confidence|kk_relates_to|kk_depends_on` (any other key will be rejected downstream). Validate your output array with `npx --yes kenkeep@latest validate curator-output <DRAFT_PATH>` if you can; the host re-validates and skips a malformed batch.
 > - Write the actions as a JSON array (top-level) to the absolute path `<DRAFT_PATH>`. The file must contain exactly the JSON array, nothing else.
 > - Return the path on success.

tests/skills/root-discovery.test.ts

@@ -10,8 +10,8 @@ const skillsDir = join(here, '../../templates/skills');
 
 const skills = [
   ['kk-add', '7'],
-  ['kk-bootstrap', '5'],
-  ['kk-curate', '10'],
+  ['kk-bootstrap', '6'],
+  ['kk-curate', '11'],
   ['kk-migrate', '7'],
   ['kk-session-extract', '6'],
 ] as const;