@codyswann/lisa 2.349.1 → 2.351.0

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

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

package/plugins/lisa-cursor/rules/derived-branch-plan-reference.mdc

@@ -0,0 +1,117 @@
+---
+description: "Derived Branch Plan — reference"
+alwaysApply: false
+---
+
+# Derived Branch Plan — reference
+
+The full body behind the `derived-branch-plan` eager head. It defines one vendor-neutral contract consumed by the three tracker writers (`lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`), the three validators (`lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`) via gate **S19**, and `lisa-implement` at claim time. Each surface cites this slug rather than growing its own prose, exactly as the vendor arms cite `leaf-only-lifecycle` and `repo-scope-split`. One slug is what keeps a branch plan rejected on JIRA from being accepted on Linear.
+
+## The problem this solves, and the one it must not create
+
+An operator reading a work item cannot see which branch the work starts from or which branch the PR lands in. Both facts are knowable, but only by resolving `.lisa.config.json` — which is exactly the kind of engineering step the factory model says a non-technical operator standing at the gate should not have to take.
+
+The obvious fix — add a "source branch" field and a "PR target" field to the ticket template — is wrong, and it is worth being explicit about why, because it will look like the simple answer every time someone revisits this. Those fields would be **a second source of truth** for a fact Lisa already derives authoritatively from `## Target Backend Environment` + `deploy.branches`. Two authorities do not stay equal. They drift the first time an environment is corrected on a ticket whose branch fields nobody updated, or the first time `deploy.branches` is remapped. And the consequence of that drift is not a stale label: it is an agent branching from, and merging into, the wrong environment's branch — shipping unreviewed code to production, or shipping a production fix into a staging branch where nobody sees it.
+
+So the contract renders the branches **for humans** and recomputes them **for machines**. The rendered section is output. It is never input.
+
+Precedence is therefore not a negotiation: whenever a rendered plan and the resolved environment disagree, **the environment wins** — the authority wins, in every phase, on every vendor, with no exception for a plan a human edited by hand. The only question a disagreement raises is whether to re-render silently (staleness) or stop for a human (a conflict with a confirmed environment or an open PR base). It is never "which branch did they mean?"
+
+## The rendered section
+
+| Vendor | Heading form |
+|---|---|
+| JIRA | `h2. Branch Plan` (ADF heading in live JIRA) |
+| GitHub | `## Branch Plan` |
+| Linear | `## Branch Plan` |
+
+Body, identical on all three:
+
+```
+Branch from: <branch>
+PR into: <branch>
+Derived from: Target Backend Environment <env> via .lisa.config.json deploy.branches
+```
+
+### The derivation provenance line
+
+The third line is load-bearing. It is the discriminator between a section this contract produced and one a human typed, and it is deliberately visible prose rather than an HTML comment — the same reason the `Target Backend Environment` grammar uses visible `Inferred:` / `Assumption:` annotations: JIRA's ADF has no comment node, so a marker that only exists in markdown cannot be a vendor-neutral discriminator.
+
+A `Branch Plan` **without the provenance line is treated as hand-authored**, and hand-authored branches are never obeyed — they are compared against the recomputed plan and, on any disagreement, fail. A provenance line naming an `<env>` that is not an exact configured `deploy.branches` key is itself malformed and fails.
+
+### One branch, two labels
+
+`Branch from` and `PR into` always name the **same branch**. That is not a simplification, it is the invariant `lisa-implement` already implements: the feature branch is cut from `origin/<base>` and the PR targets `<base>`. Both labels exist because operators asked to see both questions answered, and because naming them separately gives the contract somewhere to say they are equal instead of leaving it implicit.
+
+A plan whose two fields name **two different branches** is malformed and fails validation. The case that looks like a counter-example — a bug fixed on a non-integration environment branch that must also reach the integration branch — is handled the way `lisa-implement` already handles it: as a **linked forward cherry-pick follow-up item**, which is its own work item with its own single-branch plan. It is never a divergence inside one plan.
+
+## Derivation algorithm
+
+1. **Resolve the environment.** Use the existing grammar and precedence defined in `config-resolution` and `pre-flight-autofill`: a human-confirmed bare configured key or `Confirmed: <env>` wins; then a validated `Inferred: <env> — evidence: <title|body|reproduction|hostname>`; then `Assumption: <env> — remote default branch <branch>`, or the branch-only `Assumption: remote default branch <branch>` when the reverse-map is not unique. This rule adds no new resolution logic and no new aliases.
+2. **Map forward.** Look the exact configured key up in `deploy.branches`. The key must resolve to exactly one branch.
+3. **Prove the branch.** The mapped branch must exist on the remote.
+4. **Render.** Both fields to that branch, plus the provenance line naming the `<env>` used.
+
+### Stop conditions
+
+| Condition | Behavior |
+|---|---|
+| No environment resolvable and the item is not exempt | Stop — the `Target Backend Environment` gate (S8) already owns this |
+| Environment key absent from `deploy.branches` | Stop |
+| Mapping ambiguous / not unique | Stop |
+| Mapped branch missing on the remote | Stop |
+
+**Never guess.** There is no fallback that quietly substitutes `main`, the remote default branch, or the branch of a sibling environment to keep a write from failing — a silent guess here is the exact failure this contract exists to prevent, and a stopped write is cheap next to a wrong-branch merge. The remote default branch enters only through the `Assumption:` form the environment grammar already defines, and only recorded as an assumption.
+
+## Gate S19 — Branch Plan derivation
+
+Registered in all three validators as `| S19 Branch Plan derivation | technical | false |`. The gate **recomputes** the plan from current config and compares; it never reads the rendered branches as input.
+
+| Case | Verdict |
+|---|---|
+| Exempt work (`runtime_behavior_change = false`, or a container) with no plan | `N/A` |
+| Exempt work **carrying** a plan | **FAIL** — hand-authored branches on work that declared no runtime target |
+| Applicable work, plan present, matches recomputed plan | PASS |
+| Applicable work, plan present, disagrees with recomputed plan | **FAIL** |
+| Applicable work, plan present, missing the provenance line and disagreeing | **FAIL** (hand-authored) |
+| Applicable work, two fields naming different branches | **FAIL** — malformed |
+| Applicable work, derivation hits a stop condition | **FAIL** — same stop as implement |
+| Applicable work, **proposed spec** (pre-write) with no plan | **FAIL** — the writer must render it before the write |
+| Applicable work, **live legacy item** with no plan | `N/A` with a repair note routed to claim time |
+
+The last two rows are the asymmetry that matters. Failing a *proposed* spec is free — the writer just renders the section. Failing every *existing* item would turn a whole legacy queue red overnight for a section no human ever had a way to add, so those are repaired at claim time instead, where the derivation is written onto the item as evidence.
+
+### Failure remediation
+
+Every S19 failure names both plans (rendered and recomputed) and points the fix at **the environment, never the branches**:
+
+> 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.
+
+The gate never silently chooses between the two. Picking one would be a guess wearing a verdict.
+
+## Claim-time behavior (`lisa-implement`)
+
+At claim time the plan is recomputed against **current config and the remote** — never trusted from the item — and one of four arms runs:
+
+- **Match** — proceed. The already-existing base-branch validation, feature-branch sync, and `target_branch=<base>` handoff are unchanged.
+- **Legacy (no plan)** — derive it, **write the assumption onto the item as a comment**, then proceed. The comment carries a visible prose line plus a dedupe marker so a re-claim produces no duplicate:
+
+  ```
+  Branch plan derived for this item: branch from `main`, PR into `main` (Target Backend
+  Environment: production via .lisa.config.json deploy.branches).
+  <!-- [lisa-branch-plan] key=<work-item-ref>::<branch> -->
+  ```
+
+  Marker-dedupe is on `<work-item-ref>::<branch>`, so the comment reappears only if the derived branch actually changes. Where a vendor cannot host an HTML comment, the visible line alone carries it. If the comment cannot be written, that is a stop, not a shrug — proceeding would make it exactly the silent guess this rule forbids.
+- **Conflict with a human-confirmed environment, or with an existing open PR's base** — **stop under the existing confirmation rules**. `lisa-implement` already surfaces a PR-base mismatch and re-targets only with confirmation, on the stated grounds that the ticket's environment is the source of truth; a branch plan never overrides that, and never supplies the confirmation itself.
+- **Stale (config changed since the plan was rendered)** — **current config wins**. Re-render the section onto the item, record the change, and never follow the stale plan. A stale plan is not a conflict to escalate; it is output that fell behind its input.
+
+## Why the gate is `technical` / not product-relevant
+
+S19 is categorized `technical`, `product_relevant: false`, matching S8 — the fact it checks is a deployment-topology fact, and a PRD-intake comment aimed at a product author cannot act on it. The operator-facing value of the section is that it is *visible on the item*, not that its failures are routed to product.
+
+## What this rule deliberately does not do
+
+- It defines **no new environment resolution**, no new aliases, and no new provenance grammar. All of that stays in `config-resolution` / `pre-flight-autofill`, and this rule reads the result.
+- It does **not** let a branch plan influence which environment is chosen, in any direction, at any phase.
+- It does **not** introduce branch fields on PRDs. PRDs are not built directly; their generated leaves carry the plan.

package/plugins/lisa-cursor/rules/derived-branch-plan.mdc

@@ -0,0 +1,50 @@
+---
+description: "Derived Branch Plan (load-bearing)"
+alwaysApply: true
+---
+
+# 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](derived-branch-plan-reference.mdc).

package/plugins/lisa-cursor/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-cursor/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-cursor/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-cursor/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.