@codyswann/lisa 2.349.1 → 2.351.0

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

@@ -112,6 +112,21 @@ Linear descriptions are markdown (NOT Jira wiki markup — no `h2.` headings, us
  Human confirmation replaces the automated annotation with a bare key or
  `Confirmed: <env>`. Skip only for doc/config/type-only items.]
 
+## Branch Plan
+[GENERATED, never hand-authored. Render only when the item has a Target
+ Backend Environment; omit entirely when `runtime_behavior_change = false`
+ (doc-only / config-only / type-only) or for a Project/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 to sign in as, where to get the credentials

package/plugins/lisa-agy/skills/lisa-secrets-access/SKILL.md

@@ -116,9 +116,11 @@ Every provider has a description field — Bitwarden `note`, 1Password notes, AW
 
 These are two different rules and should not be conflated:
 
-- **Rule A — the note must exist and be well-formed.** Universal: every secret, every provider, every surface. Enforced **statically** by `verify` and by `doctor`. Nothing to do with agents.
+- **Rule A — the note must exist and be well-formed.** Universal: every secret, every provider, every surface. Enforced **statically** by `verify` and by `doctor`, and it **blocks** — a malformed note is an error, not a warning. Nothing to do with agents.
 - **Rule B — an agent must read the note before first use.** Runtime, and **only in lanes where a consumer has latitude**. An agent could do anything with a write-scoped token, and the note is what bounds it. A reviewed workflow step resolving one credential by exact name has no latitude, so gating it there is ceremony that can only fail-closed and never inform.
 
+Rule A blocks because a warning enforced nothing. Both checks previously tested only whether a note was *present*, and reported a warning either way, so a vault of empty notes reported clean — which is precisely why the notes stayed empty. A check that cannot fail is a check nobody acts on.
+
 Format — first line prose, then `key: value` lines:
 
 ```text
@@ -129,6 +131,22 @@ ci: yes - injected by <mechanism>
 docs: <path>
 ```
 
+### What "well-formed" means, exactly
+
+`scripts/note-format.mjs` is the one validator; `verify` and `doctor` both call it, so they cannot reach different verdicts about the same note. It **blocks** on:
+
+| Defect | Why it blocks |
+| --- | --- |
+| `missing-note` | No note at all, empty, or only whitespace. |
+| `no-prose` | Every line is a `key: value` line, so nothing states what the credential *is*. |
+| `empty-field` | A field with nothing after the colon — it promises a fact the reader cannot find. |
+| `empty-tool-line` | A `tool:` line naming no tool: it asks for an install and supplies nothing. |
+| `bad-tool-name` | A `tool:` entry that is not a bare name, so the reader drops it silently. |
+
+It **warns**, without blocking, on `stray-separator` — a trailing or doubled comma in a tool list. The reader handles it; failing a vault over punctuation would only teach operators that the check is noise.
+
+Deliberately **not** checked: which fields a note carries, and how informative the prose is. The documented format mandates neither, and enforcing beyond the prose is the same defect as prose beyond the enforcement, pointing the other way. A line is treated as prose unless the text before its colon is a single bare lowercase token — so "Attio CRM: system of record" is a sentence, not a field.
+
 ### `tool:` — the CLI a secret implies
 
 One key is read by more than a human. A credential and the CLI that consumes it belong together — `SONARQUBE_CLI_TOKEN` is only useful with `sonar` — so a `tool:` (or `tools: a, b`) line declares that pairing where it cannot drift from the secret:
@@ -229,7 +247,7 @@ Cache **in-process only**. Never write a resolved value to disk except through t
 
 - Every name in `require` resolves.
 - Every key matches `^[A-Z][A-Z0-9_]*$`.
-- No secret has an empty note.
+- Every secret's note exists and is well-formed, per the table above. This is an **error**, so a vault that was passing on warnings will newly fail until its notes are written.
 - Every name in `rotating` has a resolvable bootstrap, so its replacement could be persisted.
 - **No secret is readable from two stores.** A value present in both the provider and a local cache is not a duplicate — it is **two live credentials**, one of which is untracked. This is the check most worth having: it catches drift before a deletion turns the forgotten copy into an orphan nobody can revoke.
 

package/plugins/lisa-agy/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-agy/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-agy/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-agy/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-agy/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-agy/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-agy/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-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.349.1",
+  "version": "2.351.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.349.1",
+  "version": "2.351.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.349.1",
+  "version": "2.351.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.349.1",
+  "version": "2.351.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.349.1",
+  "version": "2.351.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

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

package/plugins/lisa-copilot/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-copilot/rules/reference/config-resolution.md

@@ -847,6 +847,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 && \