@codyswann/lisa 2.350.0 → 2.352.0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/hooks/block-suppress-directives.sh

@@ -16,7 +16,7 @@
 
 JSON_INPUT=$(cat)
 
-# Project rule (.claude/rules/PROJECT_RULES.md): never parse JSON in shell with
+# Project rule (host rules, .agents/rules/): never parse JSON in shell with
 # grep/sed/cut/awk — always use jq. Fail open without jq so we never hard-block
 # the agent on missing tooling.
 command -v jq >/dev/null 2>&1 || exit 0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-copilot/hooks/block-suppress-directives.sh

@@ -16,7 +16,7 @@
 
 JSON_INPUT=$(cat)
 
-# Project rule (.claude/rules/PROJECT_RULES.md): never parse JSON in shell with
+# Project rule (host rules, .agents/rules/): never parse JSON in shell with
 # grep/sed/cut/awk — always use jq. Fail open without jq so we never hard-block
 # the agent on missing tooling.
 command -v jq >/dev/null 2>&1 || exit 0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-cursor/hooks/block-suppress-directives.sh

@@ -16,7 +16,7 @@
 
 JSON_INPUT=$(cat)
 
-# Project rule (.claude/rules/PROJECT_RULES.md): never parse JSON in shell with
+# Project rule (host rules, .agents/rules/): never parse JSON in shell with
 # grep/sed/cut/awk — always use jq. Fail open without jq so we never hard-block
 # the agent on missing tooling.
 command -v jq >/dev/null 2>&1 || exit 0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.350.0",
+  "version": "2.352.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/agents/learnings-synthesizer.md

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

package/plugins/src/base/agents/skill-evaluator.md

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

package/plugins/src/base/hooks/block-instruction-file-edits.sh

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

package/plugins/src/base/hooks/block-shell-json-parsing.sh

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

package/plugins/src/base/rules/eager/config-resolution.md

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

package/plugins/src/base/rules/eager/derived-branch-plan.md

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

package/plugins/src/base/rules/eager/project-learnings.md

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

package/plugins/src/base/rules/reference/config-resolution.md

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

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