@codyswann/lisa 2.350.0 → 2.352.0

package/plugins/lisa/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/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/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/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/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/rules/eager/config-resolution.md

@@ -37,9 +37,12 @@ This is the shared slug for the config-bound-transitions policy (the `leaf-only-
 
 ## Project rules and learnings
 
-Resolve hand-authored project rules from `.lisa.config.json`
-`projectRulesFile`, defaulting to `.claude/rules/PROJECT_RULES.md`. Automated
-learnings never append to that file: they use the separate machine-managed
+Host-authored project rules live in the fixed, agent-neutral directory
+`.agents/rules/` — not a configurable file. Every agent reaches it through the
+Lisa-managed pointer block in `AGENTS.md`, so it is read once, on demand. A
+project that still carries the retired `.claude/rules/PROJECT_RULES.md` keeps
+it, untouched and authoritative; the pointer names it too. Automated
+learnings never append to host rules: they use the separate machine-managed
 ledger resolved from `.lisa.config.json` — the optional `learnings.file`
 override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives in the
 cold `.lisa/` tree (never an auto-loaded rules directory) and is consumed only

package/plugins/lisa/rules/eager/derived-branch-plan.md

@@ -0,0 +1,45 @@
+# Derived Branch Plan (load-bearing)
+
+**Every applicable leaf work item shows the branch it will be built from and the branch its PR lands in, as a generated `Branch Plan` section — and that section is derived data, not a second authority.** The authority is `## Target Backend Environment` resolved forward through `.lisa.config.json` `deploy.branches`. A work item that displays branches nobody can trace back to that mapping, or a flow that reads the displayed branches instead of recomputing them, is a contract violation.
+
+**One vendor-neutral contract, cited by** `lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`, `lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`, and `lisa-implement` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-vendor prose).
+
+## Why derived, and not two branch fields
+
+The operator need is real: reading a ticket should not require resolving a config file to learn where the work starts and where it lands. But Lisa already owns that fact. Adding independent literal branch fields would create **a second source of truth that can drift** — and the failure mode of that drift is not a cosmetic mismatch, it is code silently shipped to the wrong environment. So the branches are rendered for humans and recomputed for machines. The rendered branches are **never read as input** by any flow, at any phase — a surface that needs the base branch derives it again from the environment.
+
+## The rendered section
+
+Exactly three lines, identical across vendors (`h2. Branch Plan` in JIRA wiki markup, `## Branch Plan` in GitHub/Linear markdown):
+
+```
+Branch from: <branch>
+PR into: <branch>
+Derived from: Target Backend Environment <env> via .lisa.config.json deploy.branches
+```
+
+The third line is the **derivation provenance line**. It is what marks the section machine-authored: a `Branch Plan` without it is treated as hand-authored, and hand-authored branches are never obeyed.
+
+`Branch from` and `PR into` name the **same branch by construction** — implementation checks the feature branch out of `origin/<base>` and targets the PR back into `<base>`. A plan naming two different branches is malformed and fails validation. (A fix that genuinely lands on one branch and must reach another travels as a linked follow-up work item with its own branch plan, never as a divergence inside one plan.)
+
+## Derivation
+
+1. Resolve the environment under the existing `Target Backend Environment` grammar (`config-resolution`, `pre-flight-autofill`) — human-confirmed wins, then validated `Inferred:`, then `Assumption:`.
+2. Map that exact configured key forward through `deploy.branches`. The key must map uniquely and the mapped branch must exist on the remote.
+3. Render both fields to that branch plus the provenance line.
+
+A missing or **ambiguous** mapping, a key that is **not unique**, or a branch absent from the remote **stops** the flow — exactly as `lisa-implement` already stops. **Never default independently to `main`, to the remote default branch, or to any other branch** to keep a write from failing. The remote default is a legitimate input only through the `Assumption:` fallback the environment grammar already defines, and it must be recorded as such.
+
+## Exemption
+
+Work that declares no runtime behavior change — `runtime_behavior_change = false`, i.e. doc-only, config-only, and type-only items — carries **no `Target Backend Environment`**, therefore has nothing to derive from and **requires no branch plan**. Its **absence is correct**, not a missing section, and no gate may demand one. Containers (an Epic, or a Story/Spike still holding child work) are exempt for the same reason: they are not built directly.
+
+The exemption is one-way. Exempt work that *carries* a branch plan fails validation — branches asserted for work that declared it has no runtime target are hand-authored by definition, which is the second-authority failure this rule exists to prevent.
+
+## Conflict, legacy, and drift
+
+- **Conflict** — a present plan that disagrees with the recomputed plan **fails**; the flow never silently picks a side. The remediation is always to correct the environment, never to edit the branches.
+- **Legacy** — an item written before this rule has no plan. At claim time the implementing agent derives it, **writes the assumption onto the item as a comment**, and proceeds. Never a silent guess.
+- **Drift** — config changed after the plan was rendered. Current config wins; the stale plan is re-rendered and never followed.
+
+Full derivation table, gate S19 semantics, the claim-time arms, and the vendor rendering details: [reference/derived-branch-plan.md](../reference/derived-branch-plan.md).

package/plugins/lisa/rules/eager/project-learnings.md

@@ -15,7 +15,8 @@ receive the contract's bounded projection, not the full file.
 
 Missing learnings are a silent no-op. Malformed, non-canonical, unsafe, or
 over-budget learnings produce one readable warning, apply no entry, and must not
-block unrelated task work. Never append automated learnings to
-`PROJECT_RULES.md`; project learnings are a separate machine-managed document.
+block unrelated task work. Never append automated learnings to host rules
+(`.agents/rules/`, or a surviving legacy `PROJECT_RULES.md`); project learnings
+are a separate machine-managed document.
 
 Full prose: [reference/project-learnings.md](../reference/project-learnings.md).

package/plugins/lisa/rules/reference/config-resolution.md

@@ -33,7 +33,6 @@ fi
 {
   "tracker": "jira",
   "source":  "notion",
-  "projectRulesFile": ".claude/rules/PROJECT_RULES.md",
 
   "atlassian":  { "cloudId": "<uuid>", "site": "<host>" },
   "jira": {
@@ -179,12 +178,21 @@ fi
 |-------|----------|---------|-------|
 | `tracker` | **yes** | — | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing → fail with instruction to run the matching `/lisa:setup:*` skill. |
 | `source` | no | — | Default PRD source for batch skills (`/lisa:intake`) and arg-less single-PRD skills. One of `"notion"`, `"confluence"`, `"linear"`, `"github"`, `"jira"`. Explicit URLs/keys passed to a skill always win over `source`; this is a default, not a lock. |
-| `projectRulesFile` | no | `.claude/rules/PROJECT_RULES.md` | Safe repo-relative Markdown path for hand-authored project rules. Independent of the learnings ledger — relocating the rules file never moves the ledger. |
+| ~~`projectRulesFile`~~ | — | — | **Retired.** Host-authored rules now live in the fixed, agent-neutral directory `.agents/rules/` — not a configurable file. An existing key is still parsed and preserved so installed projects keep applying, but nothing serves rules from it. See **Host rules** below. |
 | `learnings.file` | no | `.lisa/PROJECT_LEARNINGS.md` | Safe repo-relative Markdown path for the machine-managed learnings ledger, overriding the `.lisa/` default. Rejected if it resolves inside any auto-loaded rules tree (`.claude/rules`, `.cursor/rules`, `.github/instructions`, `.agents/rules`) — the ledger must stay out of eager context. |
 | `health.schedule` | no | `off` | Health cadence contract: `off`, `daily`, or `weekly`. `lisa sync` populates the default with `_lisaSync.populated` provenance and rejects values outside this closed vocabulary. Runtime results live only at the gitignored `.lisa/health/latest.json`, never in either config file. |
 | `usage` | no | — | Optional token/cost pricing metadata consumed by the `usage-accounting` rule. Missing pricing never blocks a lifecycle flow; Lisa records token counts with `estimated_cost: null` when no trustworthy price source is configured. |
 | `wiki` | no | — | Wiki location for the `wiki-knowledge-source` rule. Omit for a local in-repo wiki (`wiki/`). See **Wiki source** below. |
 
+### Host rules (`.agents/rules/`)
+
+Host-authored operating rules live in `.agents/rules/` — **fixed, not configurable**. One directory, every agent.
+
+- **Not a native auto-load tree.** `.claude/rules`, `.cursor/rules`, and `.github/instructions` are; `.agents/rules` deliberately is not. Every agent reaches it through the single Lisa-managed pointer block in `AGENTS.md` (Claude via the `@AGENTS.md` import in `CLAUDE.md`), so no agent loads host rules twice.
+- **Host-owned.** Lisa never writes rule bodies into `.agents/rules/`, and never edits or deletes a file there. Lisa's own rules originate in its plugins and arrive by their own route.
+- **Not the learnings ledger.** `.agents/rules` is reserved in the auto-loaded-tree blocklist, so a `learnings.file` override can never resolve inside it.
+- **Transition.** A project that still has the retired `.claude/rules/PROJECT_RULES.md` keeps it, untouched and authoritative. The pointer block names it so agents whose runtime does not auto-load `.claude/rules/` still find it. Moving that content is a human-gated decision, never an automated rewrite.
+
 ### Wiki source (`wiki`)
 
 Declares **where this repo's LLM Wiki lives** so the query/ingest skills can resolve and (for a remote wiki) mirror it. `wiki.source` has two shapes — **local** (`path`) and **remote** (`url`) — and the block belongs in the **consumer** repo's `.lisa.config.json`, not in `wiki/lisa-wiki.config.json` (which describes a wiki from the inside and is unavailable until a remote wiki is mirrored — chicken-and-egg). The whole `wiki` block is optional; omit it and the resolver falls back to the in-repo `wiki/` convention.
@@ -847,6 +855,22 @@ 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, which owns the one-store rule
+  # and the surface ladder. An agent following this reference must try it before
+  # any keychain — a second reader is how one credential ends up in two places.
+  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 setup flow, for
+  # projects with no 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 && \