@codyswann/lisa 2.350.0 → 2.352.0

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

@@ -0,0 +1,112 @@
+# 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/rules/reference/intent-routing.md

@@ -223,7 +223,7 @@ Sequence:
    - **PRD defect** — the ticket faithfully captured the PRD, but the PRD itself was wrong, ambiguous, or missing the failing case
    - **Missing tool access** — an agent lacked a tool, credential, environment, or permission the work required
 
-   The three knowledge categories (recurring gotcha, process friction, convention drift) persist to the committed learnings ledger through the executable contract — never to machine-local memory, `PROJECT_RULES.md`, or `AGENTS.md`.
+   The three knowledge categories (recurring gotcha, process friction, convention drift) persist to the committed learnings ledger through the executable contract — never to machine-local memory, host rules (`.agents/rules/`), or `AGENTS.md`.
 4. **Produce the human-triage document** — a markdown file with one row per candidate learning showing: category, summary, evidence (links to the source ticket comment / PR comment / commit), recommended persistence destination, and a checkbox-style disposition field the human will mark (Accept / Reject / Defer). Surface step-1 anomalies (work items missing PRs, etc.) in a separate section. The document is exhaustive — it lists every candidate, even ones the synthesizer rates low confidence — because the human, not the agent, decides what is worth keeping.
 5. **Record Debrief usage on the triage document** — invoke `lisa-usage-accounting` against the generated markdown artifact so the document carries its own direct `debrief` usage entry in the canonical `## Lisa Usage` section. If runtime usage is unavailable, write the entry with `source: unavailable` and nullable token/cost fields rather than skipping it.
 6. **Stop and hand the document to the human.** Debrief does NOT persist accepted learnings itself. The human triages, marks dispositions, and runs the **`/lisa:debrief:apply`** command (skill: `debrief-apply`) to route the accepted items to their destinations.

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

@@ -34,7 +34,7 @@ Each persisted entry has seven fields:
 
 - The **learner agent** at capture time appends or consolidates new entries
   (`persistLearningEntry` / `persistConsolidatedLearning`) from task learnings.
-  It is capture-only: it never appends to `PROJECT_RULES.md`, creates skills, or
+  It is capture-only: it never appends to host rules, creates skills, or
   files upstream issues — promotion is the gardener's ticket-gated job.
 - **`lisa-debrief-apply`** routes accepted debrief findings in the three
   knowledge categories — recurring gotcha, process friction, convention drift —
@@ -42,7 +42,8 @@ Each persisted entry has seven fields:
   `persistConsolidatedLearning`, with consolidation-at-write), provenance drawn
   from the triage row's evidence links and a `high` starting confidence because
   a human Accept is corroboration. It no longer writes to machine-local memory,
-  `PROJECT_RULES.md`, or `AGENTS.md` (the human-authored source of truth, of
+  the host-rules directory `.agents/rules/` (or a surviving legacy
+  `PROJECT_RULES.md`), or `AGENTS.md` (the human-authored source of truth, of
   which `CLAUDE.md` is only a `@AGENTS.md` pointer) for these categories.
 - The **build-intake flows** advance `last_confirmed` at claim time
   (`confirmLearningEntry`, below).
@@ -77,9 +78,10 @@ warning, apply no entry, and do not block unrelated work.
 Precedence:
 
 1. System, developer, user, and repo instructions still outrank learnings.
-2. Committed project rules remain durable human-authored guidance.
+2. Committed host rules (`.agents/rules/`) remain durable human-authored
+   guidance.
 3. Project learnings add recent operational knowledge, but never rewrite or
-   append to `PROJECT_RULES.md`.
+   append to host rules.
 
 ## Task telemetry (MLD) is not context
 

package/plugins/lisa/rules/reference/promotion-contract.md

@@ -121,6 +121,7 @@ and lets reviewers diff against a single source of truth.
 - **The gardener** (`lisa-learnings-audit`): embeds the AC template above into
   EXECUTABLE-CONTROL promotion tickets and applies the eager-tier admission
   policy when auditing.
-- **PROJECT_RULES.md owners**: that file is human-authored only; machine
+- **Host-rules owners** (`.agents/rules/`, plus any surviving legacy
+  `PROJECT_RULES.md`): that surface is human-authored only; machine
   writes go to the learnings ledger, and promotions out of it arrive as
   gardener tickets governed by this contract.

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

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

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

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

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

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

package/plugins/lisa/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/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/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/skills/lisa-implement/SKILL.md

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

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

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

package/plugins/lisa/skills/lisa-jira-validate-ticket/SKILL.md

@@ -95,6 +95,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 valid in project | `structural` | false |
 | F2 Epic parent exists and is an Epic | `structural` | false |
 | F3 Linked tickets exist | `structural` | false |
@@ -301,6 +302,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 (`h2.` / `##` in proposed text, or an ADF heading in live JIRA) 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-jira-write-ticket` must render it before the write |
+| Live **legacy** ticket 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 ticket 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 JIRA lookups; skip in dry-run if requested)
 
 #### F1 — Issue type valid in project
@@ -388,6 +409,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 valid in project — <one-line reason>

package/plugins/lisa/skills/lisa-jira-write-ticket/SKILL.md

@@ -92,6 +92,21 @@ h2. Target Backend Environment
  Human confirmation replaces the automated annotation with a bare key or
  `Confirmed: <env>`. Skip only for doc/config/type-only tickets.]
 
+h2. Branch Plan
+[GENERATED, never hand-authored. Render only when the ticket 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.]
+
 h2. 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/skills/lisa-learnings-audit/SKILL.md

@@ -49,9 +49,12 @@ memorized list:
    — stronger than an omission count, because room was not merely tight, a real
    capture was turned away. Drain it every run (see The audit cycle).
 3. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
-   the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
-   human-authored only — its existing sections are still audit candidates;
-   first-run candidates come from exactly there).
+   the host project's canonical host-rules directory `.agents/rules/`, plus any
+   retired-but-surviving single-file rules the project still carries
+   (`.claude/rules/PROJECT_RULES.md`, or a legacy `projectRulesFile` path).
+   All of it is human-authored only — the gardener proposes, it never rewrites —
+   and its existing sections are still audit candidates; first-run candidates
+   come from exactly there.
 4. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
    exposes (descriptions are eager context; bodies load on invoke).
 5. **The wiki index** — `wiki/index.md` when the project has a wiki.

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

@@ -65,18 +65,40 @@ Error: no Linear access substrate available. Authenticate the Linear MCP or set
 All GraphQL calls use:
 
 ```bash
+# Resolve the key through the chokepoint before giving up on the environment.
+# Without this rung a project that keeps its credentials in Bitwarden, Doppler,
+# or AWS has no path to the key at all — the ladder stopped at rung one, which
+# is also what left `/lisa:setup:linear` reading an OS keychain directly with
+# nowhere to migrate to. Mirrors `atlassian-access` and `notion-access`.
+read_linear_key() {
+  [ -n "${LINEAR_API_KEY:-}" ] && { echo "$LINEAR_API_KEY"; return; }
+  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
+  return 1
+}
+
 linear_graphql() {
   local query="$1"
   local variables="${2:-{}}"
-  [ -n "$LINEAR_API_KEY" ] || {
-    echo "Error: LINEAR_API_KEY is not set." >&2
+  local key
+  key=$(read_linear_key) || {
+    echo "Error: no Linear API key. Set LINEAR_API_KEY, or store it as" >&2
+    echo "LINEAR_API_KEY in this project's secrets provider." >&2
     return 1
   }
   jq -n --arg query "$query" --argjson variables "$variables" \
     '{query:$query, variables:$variables}' |
     curl -sS -X POST "https://api.linear.app/graphql" \
       -H "Content-Type: application/json" \
-      -H "Authorization: '"$LINEAR_API_KEY"'" \
+      -H "Authorization: $key" \
       --data-binary @-
 }
 ```

package/plugins/lisa/skills/lisa-linear-validate-issue/SKILL.md

@@ -96,6 +96,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 valid in team | `structural` | false |
 | F2 Project parent exists and is in same team | `structural` | false |
 | F3 Linked items exist | `structural` | false |
@@ -303,6 +304,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 a Project/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-linear-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 Linear lookups; skip in dry-run if requested)
 
 #### F1 — Issue type valid in team
@@ -394,6 +415,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 when --spec-only)
 - [PASS|FAIL|N/A] F1 Issue type valid in team — <one-line reason>

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