@codyswann/lisa 2.350.0 → 2.352.0

package/plugins/lisa/skills/lisa-secrets-access/scripts/doctor-secrets.mjs

@@ -19,6 +19,7 @@
 
 import { createHash } from "node:crypto";
 
+import { validateNote } from "./note-format.mjs";
 import { fetchAll, fetchRotatable } from "./providers.mjs";
 import { readMaterialized } from "./resolve-secret.mjs";
 import { readConfig } from "./surfaces.mjs";
@@ -118,20 +119,23 @@ export function checkNaming(provider, report) {
 }
 
 /**
- * Assert every secret carries a usage note.
+ * Assert every secret carries a usage note in the documented format.
+ *
+ * This blocks rather than warns, and the promotion is the point. The contract
+ * has always said the note "must exist and be well-formed", enforced statically
+ * by `doctor` — but a warning enforces nothing, so a vault of empty notes
+ * reported clean and stayed empty. A check that never fails is a check nobody
+ * acts on.
+ *
+ * The grammar lives in `note-format.mjs` so this and `resolve-secret.mjs verify`
+ * cannot disagree about what a well-formed note is.
  * @param {Map<string, object>} provider Provider view.
  * @param {Function} report Finding collector.
  */
 export function checkNotes(provider, report) {
   for (const [name, entry] of provider) {
-    if (!entry.note?.trim()) {
-      report(
-        "warn",
-        name,
-        "has no usage note. An agent cannot learn this credential's scope " +
-          "without one, and inferring it from the name is exactly the guess " +
-          "that writes to the wrong system"
-      );
+    for (const defect of validateNote(entry?.note)) {
+      report(defect.level, name, defect.message);
     }
   }
 }

package/plugins/lisa/skills/lisa-secrets-access/scripts/note-format.mjs

@@ -0,0 +1,179 @@
+/**
+ * Validate a credential's usage note against the format the contract documents.
+ *
+ * The contract states Rule A — "the note must exist and be well-formed",
+ * enforced statically by `verify` and by `doctor`. Only half of that was ever
+ * true. Both consumers tested the note for emptiness and nothing tested its
+ * shape, so a note that promised a scope and delivered a bare colon, or a
+ * `tool:` line naming a URL instead of a CLI, passed every check Lisa had. The
+ * prose described an enforcement that did not exist, which is worse than no
+ * rule: readers stopped checking because they believed something else was.
+ *
+ * This module is that missing half, and it lives in one place on purpose. The
+ * same argument the values file makes for keeping its writer and its parser
+ * together applies here: `tools-from-notes.mjs` decides what a `tool:` line
+ * *is*, and if this validator held a second copy of that pattern, a note could
+ * pass doctor and then be silently ignored at install time with nothing to
+ * reveal the disagreement. So the matcher is defined here once and imported
+ * there.
+ *
+ * Messages are written for the person who has to fix the vault, who is often
+ * not an engineer. Each one names the secret's defect and the edit that clears
+ * it, never only the rule that was broken.
+ * @module note-format
+ */
+
+/**
+ * A `key: value` metadata line.
+ *
+ * The key must be a single bare lowercase token. That is what separates
+ * `scope: read-write` from prose that happens to contain a colon, such as
+ * "Attio CRM: system of record for sales" — a sentence has spaces before its
+ * colon, and a capitalised word opening a sentence is prose, not a field. The
+ * discriminator is deliberately generous: mistaking a field for prose only
+ * loosens a check, while mistaking prose for a field would fail a good note.
+ */
+const FIELD_LINE = /^[ \t]*([a-z][a-z0-9_-]*)[ \t]*:[ \t]*(.*)$/;
+
+/** Matches `tool: name` or `tools: a, b`, case-insensitively, on one line. */
+const TOOL_LINE_SINGLE = /^[ \t]*tools?[ \t]*:[ \t]*(.*)$/i;
+
+/**
+ * The same matcher, global and multiline, for scanning a whole note.
+ *
+ * Derived from the single-line pattern rather than written out again, so the
+ * two can never disagree about what a tool line is.
+ */
+export const TOOL_LINE = new RegExp(TOOL_LINE_SINGLE.source, "gim");
+
+/**
+ * A bare CLI name: what a `tool:` entry is permitted to be.
+ *
+ * Names are matched against Lisa's catalogue and never executed, so this is not
+ * the security boundary — the catalogue is. It is the check that tells an
+ * operator their entry will be silently dropped, which is the failure mode
+ * worth catching: a note asking for `sonar (for CI)` installs nothing, and the
+ * session fails much later for a reason that looks unrelated.
+ */
+const TOOL_NAME = /^[a-z0-9][a-z0-9._+-]*$/;
+
+/**
+ * Whether a line is structured metadata rather than a sentence.
+ * @param {string} line One line of a note.
+ * @returns {boolean} True when the line is a field or a tool line.
+ */
+function isMetadataLine(line) {
+  return FIELD_LINE.test(line) || TOOL_LINE_SINGLE.test(line);
+}
+
+/**
+ * Check the entries on one `tool:` / `tools:` line.
+ * @param {string} value The text after the colon.
+ * @param {object[]} defects Collector to append to.
+ */
+function checkToolLine(value, defects) {
+  if (!value.trim()) {
+    defects.push({
+      level: "error",
+      code: "empty-tool-line",
+      message:
+        "has a `tool:` line that names no tool. Either name the command-line " +
+        "tool this credential is for (for example `tool: sonar`) or delete " +
+        "the line — as written it asks for a tool and supplies none, so " +
+        "nothing gets installed",
+    });
+    return;
+  }
+
+  for (const raw of value.split(",")) {
+    const entry = raw.trim();
+    if (!entry) {
+      // A trailing or doubled comma is sloppy punctuation, not a broken note:
+      // the reader drops the empty entry and installs the rest correctly.
+      // Blocking a vault over a comma would teach operators the check is noise.
+      defects.push({
+        level: "warn",
+        code: "stray-separator",
+        message:
+          "has a `tool:` line with a stray comma. Nothing breaks, but tidy it " +
+          "so the list reads as the tools it actually names",
+      });
+      continue;
+    }
+    if (!TOOL_NAME.test(entry.toLowerCase())) {
+      defects.push({
+        level: "error",
+        code: "bad-tool-name",
+        message:
+          `has a \`tool:\` entry that is not a tool name: "${entry}". Each ` +
+          "entry must be one plain name such as `sonar` or `gh`, separated by " +
+          "commas — no descriptions, links, versions, or punctuation. As " +
+          "written this entry is ignored, so the tool never gets installed",
+      });
+    }
+  }
+}
+
+/**
+ * Report every way a usage note departs from the documented format.
+ *
+ * Returns defects rather than throwing so a caller can list a whole vault's
+ * problems in one pass. An operator fixing a vault wants every edit at once,
+ * not one error per run.
+ * @param {unknown} note The note text stored beside the secret.
+ * @returns {{level: string, code: string, message: string}[]} Defects found.
+ */
+export function validateNote(note) {
+  if (typeof note !== "string" || !note.trim()) {
+    // One cause, one instruction. Also accusing an absent note of lacking a
+    // first line would leave the operator guessing which fix comes first.
+    return [
+      {
+        level: "error",
+        code: "missing-note",
+        message:
+          "has no usage note. Write one in the secret's own description field " +
+          "in the vault: a first line saying what this credential is for and " +
+          "what it can reach, then `key: value` lines such as `scope:`, " +
+          "`owner:`, and `tool:`. Guessing a credential's purpose from its " +
+          "name is exactly the guess that writes to the wrong system",
+      },
+    ];
+  }
+
+  const defects = [];
+  const lines = note.split(/\r?\n/);
+  const populated = lines.filter(line => line.trim());
+
+  if (!populated.some(line => !isMetadataLine(line))) {
+    defects.push({
+      level: "error",
+      code: "no-prose",
+      message:
+        "has no plain-language first line. Add a sentence at the top saying " +
+        "what this credential is for and what it can reach — the `key: value` " +
+        "lines below it list details, but they never say what the thing is",
+    });
+  }
+
+  for (const line of populated) {
+    const tool = TOOL_LINE_SINGLE.exec(line);
+    if (tool) {
+      checkToolLine(tool[1], defects);
+      continue;
+    }
+    const field = FIELD_LINE.exec(line);
+    if (field && !field[2].trim()) {
+      defects.push({
+        level: "error",
+        code: "empty-field",
+        message:
+          `has an empty \`${field[1]}:\` line. Either fill in the value or ` +
+          "delete the line — a field with nothing after the colon promises a " +
+          "fact the reader then cannot find anywhere",
+      });
+    }
+  }
+
+  return defects;
+}

package/plugins/lisa/skills/lisa-secrets-access/scripts/resolve-secret.mjs

@@ -30,6 +30,7 @@
 import { existsSync, readFileSync } from "node:fs";
 
 import { parseEnv } from "./envfile.mjs";
+import { validateNote } from "./note-format.mjs";
 import { ENV_KEY, fetchAll } from "./providers.mjs";
 import { materializedPaths, readConfig } from "./surfaces.mjs";
 
@@ -109,6 +110,19 @@ function sourceOf(name, provider, file) {
   return "         ";
 }
 
+/**
+ * Say what is wrong with a note, not merely that something is.
+ *
+ * "NO NOTE" against a note that exists but is malformed sends the operator
+ * looking for a missing field they already wrote.
+ * @param {object} [fault] The blocking defect, if any.
+ * @returns {string} A status label for the verify table.
+ */
+function noteStatus(fault) {
+  if (!fault) return "noted";
+  return fault.code === "missing-note" ? "NO NOTE" : `NOTE ${fault.code}`;
+}
+
 /**
  * Verify every declared secret, mirroring the ladder's own order.
  *
@@ -119,12 +133,20 @@ function sourceOf(name, provider, file) {
  * This command is read-only. Proving that a rotating credential can actually be
  * written back requires a write, so that check lives in the rotation path
  * rather than here.
+ *
+ * The two views are parameters so a test can supply them. Reaching for the
+ * provider CLI is the one thing in here that cannot run in a test, and a check
+ * nobody can test is how the note rule stayed unenforced for so long.
  * @param {object} cfg Resolved configuration.
+ * @param {Map<string, object>} [provider] Provider view.
+ * @param {Map<string, string>} [file] Materialized view.
  * @returns {number} Count of secrets that failed.
  */
-function verify(cfg) {
-  const provider = fetchAll(cfg);
-  const file = readMaterialized(cfg);
+export function verify(
+  cfg,
+  provider = fetchAll(cfg),
+  file = readMaterialized(cfg)
+) {
   const names = cfg.require ?? [
     ...new Set([...provider.keys(), ...file.keys()]),
   ];
@@ -139,13 +161,17 @@ function verify(cfg) {
       provider.get(name)?.value
     );
     const named = ENV_KEY.test(name);
-    const noted = Boolean(provider.get(name)?.note);
-    if (!resolves || !named || !noted) bad += 1;
+    // Presence is not well-formedness. Testing `Boolean(note)` passed a note
+    // that was a single stray character, which is exactly the note an agent
+    // learns nothing from. Same validator doctor uses, so the two agree.
+    const defects = validateNote(provider.get(name)?.note);
+    const noteFault = defects.find(d => d.level === "error");
+    if (!resolves || !named || noteFault) bad += 1;
     console.log(
       `  ${name.padEnd(30)} ${resolves ? "resolves" : "MISSING "} ` +
         `${sourceOf(name, provider, file)} ` +
         `${named ? "name ok" : "NAME NOT UPPER_SNAKE"}  ` +
-        `${noted ? "noted" : "NO NOTE"}` +
+        `${noteStatus(noteFault)}` +
         `${rotating.has(name) ? "  rotating" : ""}`
     );
   }

package/plugins/lisa/skills/lisa-secrets-access/scripts/tools-from-notes.mjs

@@ -21,11 +21,15 @@
  * its note. Selecting from a known set means the worst a hostile note can do is
  * ask for a CLI Lisa already ships a pinned, checksummed entry for — it can
  * never introduce a URL, a version, or a command.
+ * The matcher itself lives in `note-format.mjs` alongside the validator that
+ * checks these lines, for the same reason the values file keeps its writer and
+ * its parser in one module: two copies of the pattern would let a note pass
+ * `doctor` and then be silently ignored here, with nothing to reveal the
+ * disagreement.
  * @module tools-from-notes
  */
 
-/** Matches `tool: name` or `tools: a, b`, case-insensitively, one per line. */
-const TOOL_LINE = /^[ \t]*tools?[ \t]*:[ \t]*(.+)$/gim;
+import { TOOL_LINE } from "./note-format.mjs";
 
 /**
  * Collect the tool names a set of notes asks for.

package/plugins/lisa/skills/lisa-setup-atlassian/SKILL.md

@@ -77,6 +77,23 @@ read_token() {
   local slug=$(echo "$email" | tr '[:upper:]@.' '[:lower:]__')
   local varname="ATLASSIAN_API_TOKEN_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting. Keep this identical to `atlassian-access`.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get ATLASSIAN_API_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided flow below, for
+  # projects that have not adopted a credentials provider. Reached only when the
+  # chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-atlassian -a "$email" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-atlassian account "$email" 2>/dev/null ;;

package/plugins/lisa/skills/lisa-setup-linear/SKILL.md

@@ -89,6 +89,23 @@ read_linear_key() {  # $1=workspace slug
   local slug; slug=$(echo "$ws" | tr '[:upper:]-' '[:lower:]_')
   local varname="LINEAR_API_KEY_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting. Keep this identical to `linear-access`.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get LINEAR_API_KEY 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided flow below, for
+  # projects that have not adopted a credentials provider. Reached only when the
+  # chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-linear -a "$ws" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-linear account "$ws" 2>/dev/null ;;

package/plugins/lisa/skills/lisa-setup-notion/SKILL.md

@@ -164,6 +164,23 @@ read_notion_token() {
   local slug=$(echo "$workspace" | tr '[:upper:]-' '[:lower:]_')
   local varname="NOTION_API_TOKEN_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting. Keep this identical to `notion-access`.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get NOTION_API_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided flow below, for
+  # projects that have not adopted a credentials provider. Reached only when the
+  # chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-notion -a "$workspace" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-notion account "$workspace" 2>/dev/null ;;

package/plugins/lisa-agy/agents/learnings-synthesizer.md

@@ -44,7 +44,7 @@ Map every finding to exactly one category. When a finding could fit two, pick th
 
 A finding that does not fit any of the eight is itself a signal — surface it under an additional ad-hoc category `Uncategorized` with a note explaining why no category fit. Better to surface than to drop.
 
-The destination column is a **hint for the human triaging the row**, not the routing decision: `lisa-debrief-apply` routes on the category, never on this column. Keep the hint honest anyway — a human decides Accept/Reject partly on where the learning will land. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the committed learnings ledger through the executable contract. Machine-local auto-memory (`project_*.md`, `MEMORY.md`), `PROJECT_RULES.md`, and `AGENTS.md` (whose `CLAUDE.md` is only a `@AGENTS.md` pointer) are **never** destinations — the first is invisible to cloud runs and teammates, and the latter two are human-authored surfaces that agents do not write.
+The destination column is a **hint for the human triaging the row**, not the routing decision: `lisa-debrief-apply` routes on the category, never on this column. Keep the hint honest anyway — a human decides Accept/Reject partly on where the learning will land. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the committed learnings ledger through the executable contract. Machine-local auto-memory (`project_*.md`, `MEMORY.md`), the host-rules directory `.agents/rules/`, and `AGENTS.md` (whose `CLAUDE.md` is only a `@AGENTS.md` pointer) are **never** destinations — the first is invisible to cloud runs and teammates, and the latter two are human-authored surfaces that agents do not write.
 
 ## Dedupe rules
 

package/plugins/lisa-agy/agents/skill-evaluator.md

@@ -18,7 +18,7 @@ Rungs are ordered by context cost and enforcement strength. Decision vocabulary:
 | Rung | Recommendation | Destination | Enters context | Admission policy |
 | --- | --- | --- | --- | --- |
 | 6 | EXECUTABLE-CONTROL | Lint / ast-grep / type / test / hook / `package.lisa.json` force | Never — diagnostic fires on violation | Mechanically decidable + stable + recurred |
-| 5 | EAGER-RULE | Auto-loaded rules tree | Unconditionally, every session | **Earned by failure evidence** (repeated misses despite retrievability); demotion-biased |
+| 5 | EAGER-RULE | Host rules: `.agents/rules/` (project scope) · plugin `rules/eager/` (upstream scope) | Unconditionally, every session | **Earned by failure evidence** (repeated misses despite retrievability); demotion-biased |
 | 4 | SKILL | `.claude/skills/<name>/SKILL.md` | Description eager; body on invoke | Procedural, complex, recognizable trigger |
 | 3 | WIKI | Wiki page + index entry | Only when routed to | Durable reference knowledge |
 | 2 | KEEP-IN-LEDGER | `PROJECT_LEARNINGS.md` (bounded contract projection) | Bounded projection only | Default landing zone; probationary, expiring |

package/plugins/lisa-agy/hooks/block-instruction-file-edits.sh

@@ -117,7 +117,7 @@ WHERE IT GOES INSTEAD — take the first one that fits:
    That is a project rule — but do not write it yourself. Capture it with
    \`/lisa:persist-learning\` so it lands in the learnings ledger with provenance
    and a confidence score. The gardener (\`/lisa:learnings:audit\`) then proposes
-   promotion into \`.claude/rules/PROJECT_RULES.md\` as a human-gated ticket.
+   promotion into the host-rules directory \`.agents/rules/\` as a human-gated ticket.
 
 2. It changes how an existing skill should behave. Edit that skill's SKILL.md.
    Knowledge belongs next to the procedure it modifies, not in a global preamble.

package/plugins/lisa-agy/hooks/block-shell-json-parsing.sh

@@ -3,7 +3,7 @@
 # Text tools (grep/sed/cut/awk) break on valid JSON — multiline values, escaped
 # quotes, reordered keys, nested objects — producing silently wrong output
 # instead of errors. jq is the required tool for structural JSON reads and
-# writes in shell. Promoted from PROJECT_RULES.md prose to an executable
+# writes in shell. Promoted from host-rules prose to an executable
 # control by the learnings gardener (issue #1787).
 #
 # Precision-first: this hook fires only on high-confidence STRUCTURAL parsing

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-debrief/SKILL.md

@@ -72,7 +72,7 @@ A markdown triage document at `./debrief/<initiative-slug>-<YYYY-MM-DD>.md` (or
    - `Summary` — one sentence
    - `Category`
    - `Evidence` — links to the source ticket comment / PR comment / commit / test file (multiple allowed)
-   - `Recommended persistence destination` — the agent's best guess for where this should land if accepted (e.g., "Edge Case Brainstorm checklist → Navigation & URL state", "learnings ledger via the executable contract", "new tooling-gap ticket", "upstream Lisa issue"). Never name machine-local auto-memory, `PROJECT_RULES.md`, or `AGENTS.md` — those are not persistence destinations.
+   - `Recommended persistence destination` — the agent's best guess for where this should land if accepted (e.g., "Edge Case Brainstorm checklist → Navigation & URL state", "learnings ledger via the executable contract", "new tooling-gap ticket", "upstream Lisa issue"). Never name machine-local auto-memory, the host-rules directory `.agents/rules/`, or `AGENTS.md` — those are not persistence destinations.
    - `Disposition` — empty checkbox-style field the human will fill: `[ ] Accept` / `[ ] Reject` / `[ ] Defer` plus a free-text reason
 4. **Source map** — appendix listing every work item and PR walked, so the human can verify completeness.
 

package/plugins/lisa-agy/skills/lisa-debrief-apply/SKILL.md

@@ -18,7 +18,7 @@ A path or URL to a Debrief triage document produced by `lisa-debrief`. The docum
 
 1. **Verify the doc exists and parses.** If the file cannot be read or the expected sections are missing, stop and report — do not guess.
 2. **Confirm dispositions exist.** If every row is unmarked, stop and ask the human to triage first. A pristine doc is a no-op, not an error to silently swallow.
-3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), the committed learnings ledger path (resolve it — never hardcode — via `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md`), tracker for new tickets. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the ledger now; machine-local auto-memory and `PROJECT_RULES.md` / `AGENTS.md` are no longer knowledge destinations (see [Ledger persistence](#ledger-persistence-knowledge-categories)).
+3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), the committed learnings ledger path (resolve it — never hardcode — via `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md`), tracker for new tickets. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the ledger now; machine-local auto-memory and host rules (`.agents/rules/`) / `AGENTS.md` are no longer knowledge destinations (see [Ledger persistence](#ledger-persistence-knowledge-categories)).
 
 ## Routing rules
 
@@ -61,13 +61,13 @@ For each such Accepted row:
    - `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`).
    - `confidence` = **`high`**. A human marking the row **Accept** is corroboration — an independent human judgement that the learning is real — so a debrief-accepted entry starts higher than the learner's single-occurrence auto-capture (which defaults to `low`). The writer re-asserts the entry and token budgets; an over-budget failure means consolidate harder or drop, never truncate by hand.
 
-**Machine-local memory is no longer a knowledge destination.** Auto-memory (`project_*.md`, `MEMORY.md`) remains available only for the assistant's *personal* collaboration notes — it is invisible to cloud runs and to teammates, so it can never hold shared project knowledge. **`AGENTS.md` is human-authored** agent operating instruction — it is the source of truth, and `CLAUDE.md` is only a one-line `@AGENTS.md` pointer — and `PROJECT_RULES.md` is durable human-authored guidance; `apply` never writes to any of the three for these categories.
+**Machine-local memory is no longer a knowledge destination.** Auto-memory (`project_*.md`, `MEMORY.md`) remains available only for the assistant's *personal* collaboration notes — it is invisible to cloud runs and to teammates, so it can never hold shared project knowledge. **`AGENTS.md` is human-authored** agent operating instruction — it is the source of truth, and `CLAUDE.md` is only a one-line `@AGENTS.md` pointer — and the host-rules directory `.agents/rules/` is durable human-authored guidance; `apply` never writes to any of the three for these categories.
 
 ## Idempotency
 
 `apply` is safe to re-run. Each Accepted row carries an evidence link that doubles as a fingerprint. Before writing, check whether the destination already cites that fingerprint:
 
-- **Knowledge categories (gotcha, friction, drift) → ledger.** Parse the ledger once with `parseLearningsFile` from `@codyswann/lisa/learnings` and scan the entries' `provenance` for the row's evidence link. If any entry's provenance already contains it, the row is already persisted — skip the write. This replaces the old scattered-file greps (memory files, `PROJECT_RULES.md`, `AGENTS.md`): provenance in the single governed ledger is now the one fingerprint surface.
+- **Knowledge categories (gotcha, friction, drift) → ledger.** Parse the ledger once with `parseLearningsFile` from `@codyswann/lisa/learnings` and scan the entries' `provenance` for the row's evidence link. If any entry's provenance already contains it, the row is already persisted — skip the write. This replaces the old scattered-file greps (memory files, host rules, `AGENTS.md`): provenance in the single governed ledger is now the one fingerprint surface.
 - **Other categories** keep their existing destination check (the tracker for the ticket marker, the PRD for the defect comment, `intent-routing.md` for the edge-case citation).
 
 If the fingerprint is already present, skip the write and note the row as `already-applied` in the run summary. This lets the human triage a doc incrementally (mark a few, run apply, mark more, run apply again) without producing duplicates.

package/plugins/lisa-agy/skills/lisa-doctor/SKILL.md

@@ -56,7 +56,10 @@ as applicable to the current repo:
    and `source` only. If a required CLI, MCP surface, or auth context is unavailable in the current
    runtime, report that explicitly instead of pretending the repo is ready.
 4. **Runtime distribution surfaces** — confirm the command, skill, hook, and related distribution
-   surfaces relevant to this repo are present where Lisa expects them on the active runtime.
+   surfaces relevant to this repo are present where Lisa expects them on the active runtime, and
+   that the Lisa-owned enforcement artifacts (`scripts/lisa-hooks/*`,
+   `scripts/lisa-enforcement-fallback.sh`) match the installed Lisa version rather than an older
+   copy. Present-but-stale is a finding: a guard whose fix never landed enforces the old behavior.
 5. **Automation readiness** — inspect whether the configured queue source/tracker and scheduling
    prerequisites are observable, but do **not** create, edit, or delete automations during doctor.
 6. **Optional GitHub Project coordination** — when `github.projects.v2` is configured, delegate

package/plugins/lisa-agy/skills/lisa-github-read-issue/SKILL.md

@@ -48,6 +48,7 @@ Walk the markdown body and capture each top-level `## ` section by name. Standar
 - `Acceptance Criteria` (preserve the Gherkin code-fence verbatim)
 - `Out of Scope`
 - `Target Backend Environment`
+- `Branch Plan` (derived output per `derived-branch-plan` — parsed so callers can *compare* it against a recomputation, never so they can use it as the base branch)
 - `Sign-in Required`
 - `Repository`
 - `Source Artifacts`

package/plugins/lisa-agy/skills/lisa-github-validate-issue/SKILL.md

@@ -98,6 +98,7 @@ Per-type content requirements are defined once in the vendor-neutral `work-item-
 | S16 Source Requirement traceability | `product-clarity` | true |
 | S17 Improvement measurability | `acceptance-criteria` | true |
 | S18 Stateless-pickup dry-run | `product-clarity` | true |
+| S19 Branch Plan derivation | `technical` | false |
 | F1 Issue type label exists in repo | `structural` | false |
 | F2 Parent sub-issue exists and is the right type | `structural` | false |
 | F3 Linked issues exist | `structural` | false |
@@ -299,6 +300,26 @@ The autonomy gate, run last, on every build-ready leaf (use the S15 classificati
 
 Zero questions → PASS. Any question → FAIL, with each question listed verbatim as its own remediation line — these are exactly the clarifying comments the caller posts to the source. The structure gates are proxies; this gate checks the readiness property itself: `ready` means a stateless agent can drive this item to its terminal state with zero human clarification (see `work-item-definition-of-ready`).
 
+#### S19 — Branch Plan derivation
+
+Enforces the `derived-branch-plan` rule: the `## Branch Plan` section is **derived only** — recompute it from current config and compare; never trust the rendered branches or read them as input. Resolve the environment under the S8 grammar, map that exact configured key forward through `.lisa.config.json` `deploy.branches`, and require the mapped branch on the remote.
+
+| Case | Verdict |
+|---|---|
+| `runtime_behavior_change = false` (doc-only / config-only / type-only) or an Epic/container, with no plan | `N/A` — absence is correct; never demand one |
+| Exempt work **carrying** a `## Branch Plan` | **FAIL** — hand-authored branches on work that declared no runtime target |
+| Plan matches the recomputed plan | PASS |
+| Plan conflicts with the recomputed plan | **FAIL** |
+| Plan missing the `Derived from:` provenance line and disagreeing | **FAIL** — treated as hand-authored |
+| `Branch from` and `PR into` name two different branches | **FAIL** — malformed; they are the same branch by construction |
+| Derivation hits a stop condition (env absent from `deploy.branches`, ambiguous / non-unique mapping, branch missing on the remote) | **FAIL** — the same stop `lisa-implement` takes; never default to `main` or the remote default |
+| Proposed spec (pre-write) for applicable work with no plan | **FAIL** — `lisa-github-write-issue` must render it before the write |
+| Live **legacy** issue for applicable work with no plan | `N/A` with a repair note — routed to claim time, where `lisa-implement` writes the derived assumption as a comment and proceeds |
+
+Failing a proposed spec is free; failing every existing issue would turn a legacy queue red for a section no human had a way to add, so legacy absence is repaired at claim time instead.
+
+FAIL names both plans (rendered and recomputed) and points the remediation at **the environment, never the branch** — e.g. `"Branch Plan conflicts with the environment mapping. Rendered 'Branch from: release/staging'; recomputed from Target Backend Environment 'production' via deploy.branches → 'main'. Correct the environment, not the branch — the branches are derived. Then re-render."` Never silently choose between the two plans.
+
 ### Feasibility Gates (require GitHub lookups; skip in `--spec-only`)
 
 #### F1 — Issue type label exists in repo
@@ -455,6 +476,7 @@ Output is a single fenced text block. Callers parse it; do not add free-form pro
 - [PASS|FAIL|N/A] S16 Source Requirement traceability — <one-line reason>
 - [PASS|FAIL|N/A] S17 Improvement measurability — <one-line reason>
 - [PASS|FAIL|N/A] S18 Stateless-pickup dry-run — <one-line reason>
+- [PASS|FAIL|N/A] S19 Branch Plan derivation — <one-line reason>
 
 ### Feasibility Gates  (omit this section when --spec-only)
 - [PASS|FAIL|N/A] F1 Issue type label exists in repo — <one-line reason>

package/plugins/lisa-agy/skills/lisa-github-write-issue/SKILL.md

@@ -100,6 +100,21 @@ Scenario: <name>
  Human confirmation replaces the automated annotation with a bare key or
  `Confirmed: <env>`. Skip only for doc/config/type-only issues.]
 
+## Branch Plan
+[GENERATED, never hand-authored. Render only when the issue has a Target
+ Backend Environment; omit entirely when `runtime_behavior_change = false`
+ (doc-only / config-only / type-only) or for an Epic/container — absence is
+ correct there. Derive per the `derived-branch-plan` rule: resolve the
+ environment, map it forward through `.lisa.config.json` `deploy.branches`,
+ and prove the branch exists on the remote. Do not accept caller-supplied
+ branches; recompute them. Exactly three lines:
+   Branch from: <branch>
+   PR into: <branch>
+   Derived from: Target Backend Environment <env> via .lisa.config.json deploy.branches
+ Both fields name the same branch by construction. A missing, ambiguous, or
+ non-unique mapping, or a branch absent from the remote, STOPS the write —
+ never default to `main` or the remote default to keep the write alive.]
+
 ## Sign-in Required
 [Include this section ONLY if the work touches authenticated surfaces.
  Specify: the account/role, where to get the credentials (1Password item,

package/plugins/lisa-agy/skills/lisa-implement/SKILL.md

@@ -107,6 +107,12 @@ Using the general-purpose agent in Team Lead session, **determine the base branc
    - The only normalization is built-in `prod` ↔ `production`, and only when exactly one of those keys exists in `deploy.branches`; normalize to that configured key. No other aliases exist.
    - Never infer from arbitrary branch text, URL paths or query strings, or substrings inside other words or hostname labels. Multiple conflicting signals after normalization **stop** the flow. If there are no signals, resolve the remote default branch (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`, or `git remote set-head origin -a` then `origin/HEAD`). When it reverse-maps uniquely, write the env-bearing `Assumption:` form; when the reverse-map is not unique, write the branch-only form and continue on the remote default without inventing an environment or blocking solely for that ambiguity. Record the fallback assumption in the plan/tracker artifact.
 2. **Map the resolved environment to a base branch** through `.lisa.config.json` `deploy.branches` — the forward direction of the env-keyed `done` resolution. The selected exact configured key must map uniquely, and the mapped branch must exist on the remote. A missing/ambiguous mapping or remote branch **stops** the flow; never guess or silently fall back.
+   - **Reconcile the ticket's `## Branch Plan` (`derived-branch-plan` rule).** The rendered plan is derived output, never input: **recompute** it here from current config and the remote — the mapping you just resolved — and compare. Four arms, no fifth:
+     - **Match** → proceed.
+     - **Legacy (no plan)** → derive it, **write the assumption onto the ticket as a comment**, then proceed. Visible prose plus a dedupe marker, e.g. ``Branch plan derived for this item: branch from `main`, PR into `main` (Target Backend Environment: production via .lisa.config.json deploy.branches).`` followed by `<!-- [lisa-branch-plan] key=<work-item-ref>::<branch> -->` (marker-dedupe on `<work-item-ref>::<branch>`, so a re-claim adds no duplicate; where a vendor cannot host an HTML comment the visible line alone carries it). **No silent guess** — if the comment cannot be written, that is a stop, because proceeding would make the inference invisible.
+     - **Conflict with a human-confirmed environment, or with an existing open PR's base** → **stop under the existing confirmation rules** below. A branch plan never overrides the environment and never supplies the confirmation itself.
+     - **Stale (config changed since the plan was rendered)** → current config wins: re-render the section onto the ticket, record the change, and never follow the stale plan. Staleness is output falling behind its input, not a conflict to escalate.
+   - Exempt work carries no plan and needs none: `runtime_behavior_change = false` (doc-only / config-only / type-only) and containers have no `## Target Backend Environment` to derive from, so **absence is correct** — never demand or invent one.
 3. **Establish the feature branch off the latest base, conflict-free:**
    - `git fetch origin`.
    - Already on a feature branch with an **open PR** → reuse it. If the PR's base ≠ the resolved base branch, surface the mismatch and re-target only with confirmation — the ticket's environment is the source of truth.

package/plugins/lisa-agy/skills/lisa-improve-harness/SKILL.md

@@ -341,7 +341,7 @@ Any durable lesson the loop produced is **submitted** to `lisa-persist-learning`
 only write path per the `project-learnings` rule) as a candidate; its hostile-default judge — not
 this skill, and not the caller — decides the disposition. A dropped candidate is recorded in
 `Known limits`, never reported as routed or owned. This skill never writes the learnings file,
-`PROJECT_RULES.md`, or `CLAUDE.md` itself, and never promotes a learning to a higher rung (that
+host rules (`.agents/rules/`), or `CLAUDE.md` itself, and never promotes a learning to a higher rung (that
 is the gardener's ticket-gated job).
 
 ## Idempotency
@@ -483,5 +483,5 @@ its face, because a single-trajectory loop always has limits.
 - **Bounded claims.** One trajectory supports one trajectory's claim. No comparative,
   longitudinal, or population claims; `Known limits` is never empty.
 - **One write path for learnings.** Durable lessons are submitted to `lisa-persist-learning` for
-  judgment; this skill never edits the learnings ledger, `PROJECT_RULES.md`, or a rules tree,
+  judgment; this skill never edits the learnings ledger or any rules tree (host `.agents/rules/` included),
   and never promotes a learning to a higher rung.