@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/skills/lisa-persist-learning/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: lisa-persist-learning
+description: This skill should be used when a candidate learning (from a failure signal, rejection, or debrief) needs to be judged and routed. It computes a stable fingerprint, runs the candidate through the hostile-default learning-judge gate, and performs exactly the verdict's side effects — a dropped-with-reason note on the triggering issue (drop), an automatically filed upstream Lisa ticket with marker dedupe, evidence, and a per-run cap (lisa-upstream), or a confidence-routed pull request that touches only the learnings surface (durable-learning). Idempotent via marker dedupe; headless-safe; never blocks the primary build flow.
+---
+
+# Persist Learning
+
+Route ONE candidate learning through the judgment gate and act on the verdict. Candidate: $ARGUMENTS
+
+Most candidates are dropped — that is the gate working, not a failure. Nothing is ever silent (every drop leaves a visible note), and no learning content ever reaches the learnings surface outside a pull request.
+
+On runtimes without the rule tree (Antigravity), read **Worth doing** in `lisa-track` for the same value and decline policy.
+
+## Candidate Input
+
+Accept the candidate as JSON or `key=value` fields:
+
+- `rule` — the proposed learning (must fit the executable contract: ≤240 chars, ≤2 lines)
+- `why` — the causal claim
+- `provenance` — stable refs (issues/PRs/commits/comments), ≤20
+- `evidence_links` — concrete evidence refs available for citation
+- `scope_hint` — `project` | `upstream` (a hint; the judge decides)
+- `triggering_issue` — the issue/work item whose failure produced this candidate (required)
+- `fingerprint` — optional; computed below when absent
+
+## Phase 0 — Fingerprint (stable dedupe key)
+
+Every workflow marker and branch below keys off this occurrence fingerprint. It is separate from the ledger entry fingerprint, which all writers compute with `learningFingerprint(rule)` from `@codyswann/lisa/learnings`:
+
+```text
+fingerprint = "sll4-" + first 12 hex chars of sha1(normalized_rule + "\n" + triggering_issue)
+normalized_rule = rule lowercased, all whitespace runs collapsed to single spaces, trimmed
+```
+
+```bash
+NORM=$(printf '%s' "$RULE" | tr '[:upper:]' '[:lower:]' | tr -s '[:space:]' ' ' | sed 's/^ *//; s/ *$//')
+FP="sll4-$(printf '%s\n%s' "$NORM" "$TRIGGERING_ISSUE" | shasum -a 1 | cut -c1-12)"
+```
+
+(Use `sha1sum` where `shasum` is unavailable.) The same rule for the same triggering issue always produces the same fingerprint, so re-runs dedupe instead of duplicating comments, PRs, or branches.
+
+## Phase 1 — Judge (mandatory, never skipped)
+
+Invoke the `learning-judge` agent (via the Agent/Task tool with `subagent_type: "learning-judge"` — the same invoke pattern the gardener uses for the `skill-evaluator` ladder router) with the full candidate including the fingerprint. It returns a verdict: `classification`, `cited_evidence[]`, `rationale`, `confidence` (durable only), `disposition`.
+
+**Respect the verdict — do not override it.** Never re-run the judge hoping for a different answer, and never persist anything the judge did not classify `durable-learning`.
+
+## Phase 2 — Route by disposition
+
+All issue/PR comments below follow the marker-dedupe discipline from `lisa-github-write-prd` Phase 2, each with its own producer tag: match on the **marker, never the title or text**; **exactly one marker per body**; **never write a markerless body** (it breaks all future dedupe); include the eventual-consistency guard — when the `gh` search index is stale, also enumerate the bodies directly (`gh issue view <n> --json comments --jq '.comments[].body'` or `gh pr list --json number,body`) and grep for the marker before deciding to create.
+
+### `drop` (classification `one-off` or `misunderstanding/spec-gap`)
+
+Post **one** comment on the triggering issue and write **nothing** — zero bytes — to the learnings surface (not a stub, not a placeholder):
+
+```markdown
+<!-- [lisa-learning-drop] key=<fingerprint> -->
+Dropped (<classification> — <plain-language gloss>): <reason>.
+```
+
+The note is one line naming the classification (with its fixed plain-language gloss) and the reason, readable by a non-technical operator. Use exactly these glosses per class:
+
+| Classification | Gloss |
+|----------------|-------|
+| `one-off` | a one-time fluke, not a recurring pattern |
+| `misunderstanding/spec-gap` | traced to an unclear requirement, not a durable lesson |
+| `lisa-upstream` | root cause suspected in Lisa; routed for upstream attribution |
+
+(A `lisa-upstream` classification never produces a drop note — it routes through the `handoff-upstream` flow below, whose step-1 note uses this pre-attribution wording because filing only happens after attribution confirms the Lisa surface.) Dedupe before posting: if any comment on the triggering issue already carries `[lisa-learning-drop] key=<fingerprint>`, do not post again — report the existing note.
+
+### `handoff-upstream` (classification `lisa-upstream`)
+
+This disposition completes the SLL-5 loop (#1583): on an accepted worthwhile Lisa-attributed failure the upstream Lisa ticket is filed **automatically**. Filing lives here — not in `lisa-attribute-failure` — because that skill is deliberately read-only (doctor delegates to it inside its own read-only contract), while this skill already owns exactly the verdict's side effects and the marker-dedupe discipline. Never persist a local rule for a Lisa-attributed failure; the host project's only durable trace is the brief linking note in step 6.
+
+First apply `do-it-now`'s **Worth doing** guidance. Attribution establishes ownership, not value. Decline low-value additional hardening in the current summary without filing, persisting a rule, or asking a human; otherwise continue below. Before creating an upstream issue, consult `rejection-detection` for open and closed matches, including legacy unmarked declines.
+
+1. **Post the handoff marker** on the triggering issue (same one-comment marker dedupe; the marker key is unchanged). The visible line must not claim a filing that has not happened yet — attribution and filing come after this step:
+
+   ```markdown
+   <!-- [lisa-learning-upstream-handoff] key=<fingerprint> -->
+   Candidate routed for upstream attribution (root cause suspected in Lisa): <reason>.
+   ```
+
+2. **Require a confirmed `lisa` verdict from `lisa-attribute-failure` — always.** Run the `lisa-attribute-failure` skill on the failure event before any filing. The judge's `cited_evidence` seeds the event (implicated files, surface in play, failure class) but never substitutes for the verdict — a path or commit reference alone is not attribution. File **only** when the skill returns a conclusive `lisa` verdict that names the Lisa surface with cited evidence. Any other outcome — `ambiguous`, `project`, or a verdict that cannot name a concrete Lisa surface — files **NOTHING** upstream: the candidate stays local and low-confidence, the run summary says attribution was inconclusive, and the step-1 note is resolved with one corrective follow-up comment on the triggering issue (marker-deduped so re-runs never repeat it; the suffix is distinct from the filing-failure marker in step 8 so one outcome never suppresses the other):
+
+   ```markdown
+   <!-- [lisa-learning-upstream-handoff] key=<fingerprint>-inconclusive -->
+   Attribution was inconclusive — nothing was filed upstream and nothing was persisted locally.
+   ```
+
+3. **Derive the root-cause key from the LISA SURFACE, never the host project or the local issue.** Two projects hitting the same Lisa bug MUST collide on the same key — that collision is the design (update, not duplicate):
+
+   ```text
+   root-cause-key = <lisa-surface>#<failure-class>
+   ```
+
+   - `<lisa-surface>` — the exact public Lisa-relative path of the surface at fault (e.g. `plugins/src/base/skills/lisa-doctor/SKILL.md`, `typescript/copy-overwrite/.github/workflows/quality.yml`). Canonical names, aliases, host paths, and unmanifested paths are prohibited.
+   - `<failure-class>` — exactly one exported closed value: `access-control-failure`, `agent-parity-regression`, `configuration-regression`, `data-integrity-failure`, `dependency-regression`, `generated-artifact-regression`, `installation-regression`, `observability-gap`, `pagination-truncation`, `performance-regression`, `public-data-exposure`, `release-regression`, `runtime-regression`, `stale-artifact-overwrite`, `test-coverage-gap`, `validation-gap`, or `workflow-contract-violation`.
+   - Normalize: lowercase, trim, collapse every whitespace run to a single `-`. The key must contain no host-project name, no local issue number, and no fingerprint — those vary per project and would defeat fleet-wide dedupe.
+
+4. **Enforce the per-run cap.** Resolve `hardening.maxUpstreamFilingsPerRun` from `.lisa.config.json` (default `5` — a conservative bound modeled on `lisa-repair-intake`'s `max_candidates` precedent). Count every upstream create **and** update this run performs; once the cap is reached, drop the remaining candidates and **note each dropped candidate visibly** (in the run summary, naming its root-cause key) — never queue a spam burst and never drop silently. A later run picks the dropped candidates up idempotently.
+
+5. **Evidence redaction (binding).** The upstream repo is PUBLIC by default (`hardening.upstreamRepo` → `CodySwannGT/lisa`) and this filing runs headless on crons — treat every drafted upstream body and comment as world-readable. The PRIMARY control is the **allowlist projection** in step 6: `bunx @codyswann/lisa file-upstream` calls the sole `buildUpstreamAttributionIssueBody` export from `@codyswann/lisa/learnings`, so content outside its enumerated fields is structurally incapable of reaching the public document. The rules below bind the FIELDS supplied to that command; the closing scan is a defense-in-depth backstop, never the primary control:
+
+   - Quote ONLY Lisa-owned surface text: template/rule/skill/hook excerpts and upstream commit references. The reproduction must be REDACTED — generic placeholders, never the host project's real values.
+   - Never paste host environment values, tokens/credentials, connection strings, API keys, PII (names, emails, customer data), or proprietary host code/payloads.
+   - The evidence chain names the Lisa surface and the failure class — never project payloads. Keep any host-project issue link only in the private local trace; it is never supplied to or emitted by the public builder.
+   - Use only these exact generic placeholders: `<host-project>`, `<env-value>`, `<credential>`, `<connection-string>`, `<pii>`, `<host-payload>`, `<path>`, `<identifier>`. A project-specific placeholder is host prose and must be rejected.
+   - **Backstop (defense in depth, never the primary control).** Before filing or commenting, scan the projected document for common secret shapes — `key=value` pairs with high-entropy values, token prefixes (`AKIA`, `ghp_`, `xox`), email addresses — and reject on a match. To strip on match, remove the offending INPUT field and re-run `file-upstream`; never strip or edit the generated output itself. Non-allowlisted fields must reject before filing rather than be silently dropped. When in doubt, leave it out: a thinner upstream document is recoverable; a leaked secret is not.
+
+6. **Dedupe by marker, then file or update.** The upstream marker is:
+
+   ```markdown
+   <!-- [lisa-upstream-attribution] key=<root-cause-key> -->
+   ```
+
+   Resolve the upstream repo from `.lisa.config.json` `hardening.upstreamRepo` (default `CodySwannGT/lisa`). Search **all issue states** for an existing issue carrying the marker — a closed marker-bearing ticket still owns this root cause, and searching only open issues would mint a duplicate the moment the original closes. Match on the **MARKER, never the title** — with the same eventual-consistency guard as above (`gh issue list -R <upstream> --state all --search '"<marker>" in:body' --json number,state,url`, and when the search index returns nothing, also `gh issue list -R <upstream> --state all --json number,state,body` and grep the bodies for the marker before concluding no ticket exists).
+
+   - **No existing ticket** → compose the body EXCLUSIVELY through the executable builder, then file its stdout verbatim via `lisa-github-write-issue` targeting the upstream repo with the `self-hardening` label and explicit `build_ready: true` (per `ready-role-filing`; the upstream repo runs its own build queue off the ready role, and an omitted flag would strand the hardening ticket there):
+
+     ```bash
+     bunx @codyswann/lisa file-upstream --input filing-event.json   # or pipe the JSON on stdin
+     ```
+
+     **Never assemble the public body as free-form prose.** Public composition happens through the builder, never by free-form prose assembly. The builder owns the three-audience description and the redacted evidence chain (Lisa-owned text only). Do not hand-write either section, name an affected project in prose, or edit the builder's output after generation. Supply only this JSON shape; host-project issue URLs remain private local-trace data and are never accepted by the public builder:
+
+     ```json
+     {
+       "documentKind": "issue",
+       "lisaSurface": "plugins/src/base/skills/lisa-doctor/SKILL.md",
+       "failureClass": "stale-artifact-overwrite",
+       "lisaOwnedExcerpts": [
+         {
+           "file": "plugins/src/base/skills/lisa-doctor/SKILL.md",
+           "text": "<verbatim Lisa-owned text>"
+         }
+       ],
+       "upstreamCommitRefs": ["<full 40-character public-origin SHA>"],
+       "redactedPlaceholders": ["<host-project>", "<env-value>"]
+     }
+     ```
+
+     Every excerpt is verified against the installed package's Lisa-owned source and every commit against the public origin. Callers cannot supply a verifier or Lisa root. Anything outside the allowlist is REJECTED by field name with empty stdout and a non-zero exit; fix or remove the offending input field and re-run the command, never route around it. The builder emits **exactly one** dedupe marker; **never write a markerless body** — it permanently breaks all future dedupe.
+   - **Existing ticket (open or closed)** → this is a repeat encounter: comment the new occurrence on the existing issue with this project's evidence. The comment is projected through the same builder: run `bunx @codyswann/lisa file-upstream` with the same allowlisted fields plus exactly `"documentKind": "occurrence"` and `"occurrenceFingerprint": "<fingerprint>"`. The supplied fingerprint is only a validated seed: the builder hashes it and emits a different deterministic `sll4-<12 lowercase hex>` marker. Use the marker in the builder's stdout — never the supplied literal — to search existing issue comments for a duplicate, then post stdout verbatim only when that emitted marker is absent. Free-form occurrence prose is prohibited, and post-generation edits are prohibited. Never open a second issue, and never match on the title — evidence compounds on one ticket. When the match is **CLOSED**, still comment the occurrence there and reference it in the local trace instead of filing a duplicate; do not reopen it yourself — recurrence evidence on a closed ticket signals the shipped fix may not cover this case, and reopening is the upstream maintainer's call.
+
+7. **Leave the local trace — a note, never a rule.** Post one follow-up comment on the triggering issue linking the upstream ticket:
+
+   ```markdown
+   <!-- [lisa-upstream-filed] key=<fingerprint> -->
+   Upstream ticket: <url> (root-cause key `<root-cause-key>`). No local rule persisted — the fix ships fleet-wide through Lisa.
+   ```
+
+   The learnings surface gains **no durable local rule** for a Lisa-attributed failure. Agents avoid the trap via the upstream ticket link until the fix ships.
+
+8. **Degrade gracefully.** If filing fails (auth, rate limit, network), report the failure in the run summary and continue shipping the host issue — a later run retries idempotently. Never block the primary build flow. So the step-1 note is not left dangling, post a marker-deduped corrective follow-up on the triggering issue — with its own suffix, distinct from step 2's `-inconclusive`, so an earlier inconclusive note can never suppress a filing-failure note (or vice versa):
+
+   ```markdown
+   <!-- [lisa-learning-upstream-handoff] key=<fingerprint>-filing-failed -->
+   Upstream filing did not complete — nothing was filed upstream and nothing was persisted locally; a later run retries.
+   ```
+
+### `persist` (classification `durable-learning`)
+
+Continue to Phase 3.
+
+## Phase 3 — Persist via PR (durable-learning only)
+
+No learning content is ever committed without a PR — there is no other write path, and the PR must touch **only** the learnings surface (any other changed file is a bug).
+
+1. **PR dedupe.** Search all PRs for the marker `[lisa-learning-pr] key=<fingerprint>` in the body (`gh pr list --state all --search '"<marker>" in:body' --json number,url`), with the stale-index guard above. If one exists, reference it and stop — never open a duplicate.
+2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the machine-managed ledger resolved from `.lisa.config.json` (the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md` — a cold path, never an auto-loaded rules tree):
+
+   ```bash
+   LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')
+   ```
+
+3. **Consolidation check (mandatory before writing).** Parse the existing entries (`parseLearningsFile` from `@codyswann/lisa/learnings`). First compare `learningFingerprint(existing.rule)` with `learningFingerprint(candidate.rule)`: an equal rule is already captured, even if its legacy id or fingerprint has another prefix. Preserve the stored values, report the existing id, and stop without writing that candidate. Shared evidence alone never makes two rules duplicates. Only otherwise look for related entries (same failure class, overlapping topic, or near-duplicate wording) and write through the executable contract — **never hand-edit the markdown**:
+   - **Related entry found** → consolidate with the exact versions returned by the parser: `persistConsolidatedLearning(projectRoot, entry, { supersede: [{ id: <related id>, fingerprint: <related fingerprint> }], onStaleSupersede: targets => report(targets) })`. The writer checks every stamp together inside the lock. If any target is absent or its fingerprint changed, the whole supersede is stale: it removes nothing, safely appends the new fingerprint, and reports the mismatch. Never append a near-duplicate sibling by choice — a sibling is a bug that fails review; the writer's stale append is the deliberate race-safe preservation path.
+   - **No related entry** → append via `persistLearningEntry(projectRoot, entry)` and state in the PR body why appending was correct.
+   - Entry mapping (eight fields): `fingerprint` = `learningFingerprint(rule)` and initial `id = fingerprint`; `rule`/`why`/`provenance` from the candidate; `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`); `confidence` = the judge's `high`/`low`. On an exact stamped consolidation the writer carries forward the deterministic primary target id while persisting the new fingerprint as the version token. Use exact parsed legacy stamps in `supersede`; never rewrite old ids or fingerprints just to adopt the helper. A duplicate fingerprint fails before mutation. The writer re-asserts the entry and token budgets — an over-budget failure means consolidate harder or drop, never truncate by hand.
+   - **On a budget-forced drop, signal saturation once (never silent).** When the writer's budget re-assertion cannot fit the entry even after consolidating harder — a durable capture has to be DROPPED for budget — the ledger is saturated, and that pressure must be visible to an operator instead of swallowed. Emit **exactly one** tracker signal via `lisa-tracker-write` (`issue_type: Task`; GitHub trackers carry the `type:Task` label), then continue — dropping the capture never blocks the build. Follow the same marker-dedupe discipline as every other comment here (match on the **marker, never the title**; **exactly one marker per body**; the eventual-consistency guard when the search index is stale), with **one deliberate difference: dedupe against OPEN signals only.** A *closed* saturation ticket means room was already reclaimed, so a fresh saturation is a new actionable event — searching closed tickets too (as the drop/upstream markers do) would permanently suppress every later saturation.
+
+     The saturation fingerprint keys on the **ledger, not the candidate**, so the signal fires once per saturation episode — never once per capture:
+
+     ```text
+     saturation-fingerprint = "sat-" + first 12 hex chars of sha1(<resolved learnings-file path>)
+     ```
+
+     ```markdown
+     <!-- [lisa-ledger-saturated] key=<saturation-fingerprint> -->
+     Learnings ledger saturated — a durable capture was dropped for budget. The projection is now omitting entries; promote or retire a learning to reclaim room. This is an operator-visible budget-pressure signal, not itself a new learning.
+     ```
+
+     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The signal records the saturation; it does not persist the rule.
+   - **The dropped capture is preserved for you — ship it.** The writer does this itself, so there is nothing to compose by hand: when the budget re-assertion fails, `persistConsolidatedLearning` / `persistLearningEntry` write the rejected entry to the **overflow buffer** — `PROJECT_LEARNINGS.overflow.md`, a sibling of the resolved ledger — and then re-raise a budget error naming that file. The thrown error is the confirmation; if it does not name the overflow, the capture was NOT preserved (the overflow is full too) and that is what the error says instead.
+
+     The overflow is git-tracked and bound to the same union merge driver as the ledger, so **still open the pull request on a budget-forced drop** — carrying the overflow file instead of the ledger. That is the whole point of preserving it: a capture that reaches only a disposable `learning/<fingerprint>` worktree is durable in name only, and the gardener draining `main` would never see it. Never hand-edit the overflow, and never delete an entry from it to make room; the gardener drains it.
+
+     So a budget-forced drop produces **both** halves and neither substitutes for the other: the `[lisa-ledger-saturated]` ticket (the signal that room must be reclaimed) and a pull request carrying the overflow file (the content itself). Report both in the run summary.
+4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings surface — the ledger, or the overflow buffer on a budget-forced drop; verify with `git diff --name-only` that the diff touches nothing else.
+5. **PR body.** Exactly one marker line plus the reviewable story:
+
+   ```markdown
+   <!-- [lisa-learning-pr] key=<fingerprint> -->
+
+   ## Learning
+   <rule> — <judge rationale>
+
+   ## Provenance
+   - Triggering issue: <ref>
+   - Ancestor issue/PR (the past failure this is round 2 of): <ref or none found>
+   - Rejection comments that produced the candidate: <refs or none>
+   - Cited evidence (from the judge): <refs>
+
+   ## Consolidation decision
+   <"Superseded entry id(s) X, Y: <why they merged>" | "Appended: no related entry exists — <one-line search summary>">
+   ```
+
+   For a **low-confidence** PR, the body must additionally end with this fixed decision-framing line so the human at the gate knows exactly what merging means:
+
+   ```markdown
+   **Merge** to adopt this rule into every future session for all six coding agents; **close** to discard it.
+   ```
+
+6. **Confidence routing.**
+   - **`high`** → submit through `lisa-git-submit-pr` with its defaults: auto-merge ON, merging through the project's normal gates.
+   - **`low`** → submit through `lisa-git-submit-pr` with `auto_merge=false` (drives the PR to green-and-open `awaiting-human`, never merging — even on repos that disallow auto-merge). Then apply the human-triage label, creating it idempotently first (the `lisa-drive-pr-to-merge` label pattern — `|| true` tolerates only already-exists, so verify):
+
+     ```bash
+     gh label create "learning:needs-triage" \
+       --description "Low-confidence learning PR awaiting human triage" \
+       --color FBCA04 || true
+     gh label list --search "learning:needs-triage" --json name \
+       --jq '[.[].name] | contains(["learning:needs-triage"])'   # must print true
+     gh pr edit <pr> --add-label "learning:needs-triage"
+     ```
+
+     A low-confidence PR sitting OPEN with green checks and `autoMergeRequest: null` is this mode's **success** state — a human merges or closes it. All pending low-confidence learning PRs are findable by filtering on the `learning:needs-triage` label (`gh pr list --label "learning:needs-triage"`).
+
+## Rules
+
+- **Headless-safe**: no interactive prompts; must run identically under an intake cron.
+- **Never block the build**: if judging or persistence fails, report the failure and let the primary flow continue — shipping the triggering issue always outranks recording a learning about it.
+- **No learning loops about learning**: never feed this skill a candidate whose triggering artifact is itself learning machinery (a `[lisa-learning-*]`-marked comment, learning PR, or handoff); the judge's Step 0 guard backstops this.
+- **Idempotent**: re-running with the same candidate posts no duplicate comment, opens no duplicate PR, and writes no duplicate entry — the fingerprint and markers guarantee it.
+- **One write path**: the learnings surface changes only through `persistLearningEntry` / `persistConsolidatedLearning` inside a PR. Never hand-edit the file, never commit it to the default branch directly.
+- **Never resolve a ledger conflict by taking one side.** Concurrent passes each work on their own `learning/<fingerprint>` branch, so two PRs routinely touch the same JSONL block. The `lisa-learnings` union merge driver reconciles them by entry id, but when it cannot it exits non-zero **without writing conflict markers** — leaving a clean-looking file that holds **OUR SIDE ONLY**. Driver installation is enabled by default; only an exact `learnings.mergeDriver: false` declines it. That opt-out is non-destructive: changing the setting does not uninstall an existing registration or remove the committed mapping. `git add`-ing the failed result, or running `git checkout --ours`, silently deletes the other branch's learnings. Re-union both sides instead: keep every distinct entry id, honour supersessions from either side, then re-run `lisa check-learnings-budget`. Literal conflict markers in the ledger mean the driver was not registered — run `lisa install-merge-driver .` and redo the merge unless the project explicitly opted out.

package/plugins/lisa-devin/skills/lisa-plan/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: lisa-plan
+description: "Decompose a single PRD or specification into ordered work items in the configured tracker. Vendor-agnostic — the source can be a Notion PRD URL, a Confluence PRD URL, a Linear project URL, a GitHub Issue URL, an existing JIRA epic key, a markdown file, or a free-form description; the destination tracker is whatever the project is configured to use via `.lisa.config.json` `tracker` (JIRA, GitHub Issues, or Linear). Single-PRD mode only — for batch scanning of all Ready PRDs in a queue, use the lisa-intake skill."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Plan: $ARGUMENTS
+
+Decompose the PRD/spec at `$ARGUMENTS` into ordered work items with acceptance criteria, dependencies, and recommended skills/agents.
+
+## Orchestration: agent team
+
+You are "inside an agent team" only if you are yourself a spawned teammate or subagent — you were spawned into a team context, or your context names a team lead you report to. A lead/root session that has previously spawned subagents is still the lead: prior `Agent` calls in the session (e.g., an Intake cycle's bounded scan helpers) do NOT make this a nested flow, and the lead retains full authority to create this flow's team.
+
+If you are NOT inside an agent team by that definition, the very first thing you do is establish team orchestration.
+
+Use the team tool for the current runtime:
+
+- Claude Code >= 2.1.178: there is no `TeamCreate` tool; the team forms automatically when you spawn the first teammate with `Agent`. That first spawn should be the bounded specialist needed to start this flow. On older Claude Code that still exposes `TeamCreate`, the explicit team-create path is also acceptable.
+- Codex: do not call `TeamCreate`; Codex does not expose that Claude tool. Use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation. Treat the first successful `spawn_agent` call as establishing team orchestration.
+- Other runtimes: use the current runtime's tool-discovery mechanism to discover and call the appropriate multi-agent/team tool.
+
+If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
+
+Until the team is established, the first Codex teammate has been spawned, or the no-team fallback has been declared, do NOT call any of: `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. The initial Claude `Agent` spawn described above is the only pre-team exception because it establishes the team. Reading the PRD, exploring the code, fetching context — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
+
+Note that `lisa-intake` dispatching this skill is NOT the nested case: Intake is a thin dispatcher that creates no team of its own and invokes this skill via the Skill tool in the lead session precisely so this preamble fires — treat an Intake dispatch exactly like a direct invocation and run the full team-first flow above.
+
+If you ARE already inside an agent team by the definition above (you are a teammate that was handed this skill via the Skill tool from within another flow's team), do NOT create a second team — many harnesses reject double-creates — and do NOT collapse the nested flow into a single inline worker. A nested team-first flow must still bring in the specialists it requires by adding them to the existing team, not by doing the work itself:
+
+- **Claude:** teams are flat and only the lead can add named teammates, so do NOT call `Agent` with a `name` from a teammate (the harness rejects it: *"Teammates cannot spawn other teammates — the team roster is flat"*). Send the team lead a message naming the specialist teammate(s) this flow needs, their task assignments, and completion criteria, then coordinate through the shared task list until they finish. An anonymous subagent (`Agent` with `name` omitted) is permitted only for bounded one-shot work whose result returns directly to you — it is not a substitute for the required lifecycle specialists.
+- **Codex:** do NOT call `TeamCreate`. If the lead/root agent is addressable (you were given its id/handle), send it a request to `multi_agent_v1.spawn_agent` the specialist agent(s), including each agent's prompt, ownership, and expected result. If no lead handle exists but `spawn_agent` is available to you, spawn only the bounded specialist agent(s) this flow needs, `wait_agent` for their results, and relay those results upward to the parent/lead.
+
+Treat the first successful lead-spawn request (or, on the Codex fallback, the first specialist spawn) as preserving team orchestration. Never satisfy a team-first lifecycle flow by doing all the work inline.
+
+## Source dispatch
+
+Detect the input type from `$ARGUMENTS` and route to the appropriate source skill:
+
+| If `$ARGUMENTS` is... | Hand off to |
+|------------------------|-------------|
+| A Notion **page** URL or page ID (single PRD) | `lisa-notion-to-tracker` (with the PRD URL; runs the full pipeline: extract artifacts → walk live product → validate → write tickets → coverage audit) |
+| A Notion **database** URL or database ID | Stop and report — single-PRD mode only. Direct the caller to `lisa-intake` for batch scanning of a database. |
+| A Confluence **page** URL containing `/wiki/spaces/<KEY>/pages/<ID>/...` (single PRD) | `lisa-confluence-to-tracker` (with the PRD URL; same full pipeline as the Notion path) |
+| A Confluence **space** URL (`/wiki/spaces/<KEY>` with no `/pages/...`) | Stop and report — single-PRD mode only. Direct the caller to `lisa-intake` for batch scanning of a space. |
+| A Linear **project** URL (`https://linear.app/<workspace>/project/<slug>-<id>`) | `lisa-linear-to-tracker` (with the project URL; same full pipeline as the Notion / Confluence paths). The Linear project's description, attached documents, and sub-issues form the PRD body. |
+| A Linear **workspace** URL (`https://linear.app/<workspace>` with no `/project/...`) or **team** URL | Stop and report — single-PRD mode only. Direct the caller to `lisa-intake` for batch scanning of a workspace or team. |
+| A JIRA ticket ID/URL of an Epic (existing epic *is* the spec) | `lisa-jira-agent` (read epic, decompose into stories/sub-tasks) |
+| A Linear Project URL of a Project that *is* the spec, when destination tracker = `linear` | `lisa-linear-agent` (read project, decompose into Issues / sub-Issues). Symmetric counterpart to the JIRA-Epic and GitHub-Epic branches. |
+| A GitHub **issue** URL (`https://github.com/<org>/<repo>/issues/<number>`) or `<org>/<repo>#<number>` token (single PRD) | `lisa-github-to-tracker` (with the issue ref; runs the full pipeline: extract artifacts → walk live product → validate → write tickets → coverage audit). The destination tracker is read from `.lisa.config.json` `tracker`. |
+| A GitHub **repository** URL or `<org>/<repo>` token (no issue number) | Stop and report — single-PRD mode only. Direct the caller to `lisa-intake` for batch scanning of a GitHub repo. |
+| A GitHub Issue URL of a build-side ticket (`type:Epic` / `type:Story` / etc., not `prd-*`-labelled) when `tracker = github` | `lisa-github-agent` (read issue, decompose into Sub-tasks). Symmetric counterpart to the JIRA-Epic branch above. |
+| A file path (`@plan.md`, `./spec.md`) | Read the file as the spec; run the Plan flow's core decomposition with the file content as input. |
+| A plain-text description | Use the description as the spec; run the Plan flow's core decomposition. |
+
+If no PRD or specification exists, suggest running the `lisa-research` skill first to produce one.
+
+## Flow
+
+Execute the **Plan** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The rule contains the canonical step sequence (gates, sub-flows, output structure). This skill does NOT restate flow steps — change them in the rule, propagate everywhere.
+
+## Output
+
+Work items in the configured tracker (JIRA, GitHub Issues, or Linear, per `.lisa.config.json` `tracker`) with acceptance criteria, dependencies, and recommended skills/agents per item. Ordered by dependency. Before finishing, route usage writes through `lisa-usage-accounting`: record the Plan run as a direct entry on the source PRD/spec artifact, attach a plan usage entry (or an explicit `source: unavailable` entry with nullable token/cost fields) to each created work item, and refresh the PRD rollup after `lisa-prd-backlink` regenerates the `## Tickets` child refs. Do not invent plan-specific ledger formats or omit missing usage silently. If the specification cannot be decomposed without further clarification, stop and report what is missing.

package/plugins/lisa-devin/skills/lisa-plugin-sync-explain/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: lisa-plugin-sync-explain
+description: "Read-only diagnostic for Lisa plugin source/generated drift. Compares plugins/src against generated plugins/lisa* status, reports source-not-built, generated-only, and marketplace registration drift, and preserves the working tree."
+allowed-tools: ["Bash", "Read"]
+---
+
+# Plugin Sync Explain: $ARGUMENTS
+
+`/lisa:plugin-sync-explain` explains why the plugin sync gate would need attention without mutating the working tree.
+
+## Scope
+
+Inspect the current Lisa repository, or an optional path passed as `$ARGUMENTS`, using `scripts/plugin-sync-explain.mjs`.
+
+The diagnostic is **read-only**:
+
+- Do not run `bun run build:plugins`.
+- Do not run `bun run check:plugins`.
+- Do not edit source files, generated plugin artifacts, or `.claude-plugin/marketplace.json`.
+- Do not stash, commit, reset, or clean local changes.
+
+## What to Report
+
+Report a concise terminal-first summary with stable classifications:
+
+- `SOURCE_NOT_BUILT`: files under `plugins/src/**` changed without their generated `plugins/lisa*` counterpart.
+- `GENERATED_ONLY`: files under `plugins/lisa*` changed without their `plugins/src/**` source counterpart.
+- `MARKETPLACE_REGISTRATION_DRIFT`: a built plugin directory is missing from `.claude-plugin/marketplace.json`, or a marketplace source points at a missing built directory.
+- `OUT_OF_SYNC`: source and generated counterparts both changed and need human review.
+- `IN_SYNC`: no plugin source/generated or marketplace registration drift was detected.
+
+For every finding, include the evidence path and the smallest source-first next action. Prefer `bun run build:plugins` only after source edits are in the right place, and preserve `bun run check:plugins` as the final reproducibility gate.
+
+## Process
+
+1. Resolve the repo path from `$ARGUMENTS` or the current directory.
+2. Capture `git status --porcelain` before the diagnostic.
+3. Run:
+   ```bash
+   node plugins/lisa/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+   If running from the source tree before generated artifacts are rebuilt, use:
+   ```bash
+   node plugins/src/base/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+4. Capture `git status --porcelain` after the diagnostic and confirm it is unchanged.
+5. Surface the script output plus the read-only confirmation.
+
+## Rules
+
+- Keep this surface aligned with `scripts/check-plugins-sync.sh`; it explains the gate but does not replace it.
+- Treat `plugins/src/**` as the source of truth and `plugins/lisa*` as generated artifacts.
+- If the diagnostic cannot inspect git status or marketplace JSON, report the error plainly and do not guess.

package/plugins/lisa-devin/skills/lisa-posthog-access/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: lisa-posthog-access
+description: "Vendor-neutral access layer for PostHog. PostHog skills and observability rules MUST delegate through this skill rather than calling PostHog MCP tools or REST directly. Per the credential-substrate-precedence contract, resolves POSTHOG_PERSONAL_API_KEY bearer auth first when present and identity-matched to the configured project, then falls back to the PostHog MCP."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# PostHog Access: $ARGUMENTS
+
+Single chokepoint for PostHog operations. Caller skills and rules MUST NOT call
+`mcp__posthog__*` tools or PostHog REST directly.
+
+## Invocation Contract
+
+```text
+operation: query project_id:<ID> payload:{...}
+operation: insights project_id:<ID>
+operation: persons project_id:<ID> [query:<QUERY>]
+operation: events project_id:<ID> [after:<ISO>] [before:<ISO>]
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a PostHog-local choice. The first tier that is ready **and**
+identity-matches the configured project is used; a substrate authenticated against
+a different project is skipped, never used.
+
+1. **Tier 1 — configured-provider substrate: `POSTHOG_PERSONAL_API_KEY`** bearer
+   token against the configured PostHog host, resolved through
+   `lisa-secrets-access`.
+2. **Tier 2 — interactive MCP fallback: PostHog MCP**, if available and
+   authenticated. Used when tier 1 is genuinely unavailable: no
+   `POSTHOG_PERSONAL_API_KEY`, no REST adapter for the operation, or a PostHog
+   outage.
+
+PostHog documents personal API keys and bearer authentication, and the same key
+works interactively and headlessly — which is why it leads. The REST tier uses:
+
+```bash
+POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
+
+# Resolve the key through the chokepoint before giving up on the environment.
+# `$POSTHOG_PERSONAL_API_KEY` is the documented fallback, not the only rung:
+# without this, a project that keeps its credentials in Bitwarden, Doppler, or
+# AWS has no tier 1 path at all and silently resolves through the interactive
+# MCP — the exact divergence `credential-substrate-precedence` exists to remove.
+read_posthog_key() {
+  [ -n "${POSTHOG_PERSONAL_API_KEY:-}" ] && { echo "$POSTHOG_PERSONAL_API_KEY"; return; }
+  #
+  # Ordered across trusted machine-managed substrates, ending at the installed
+  # package. Checkout-local paths are deliberately absent: a familiar generated
+  # destination is still repository-controlled executable code. The plugin
+  # rungs are the floor: `resolve-secret.mjs` ships beside this skill, so a rung
+  # pointing at it is reachable from anywhere the plugin itself is installed.
+  # Without one, a consumer repository that vendors none of the leading paths
+  # never reaches a resolver at all — the ladder exits without having asked
+  # anything, which is what pushed agents into improvising their own credential
+  # lookups. This LADDER is identical in every skill that resolves a credential
+  # and `credential-resolver-ladder` fails if any copy diverges. Only what
+  # happens AFTER the ladder may differ between them.
+  # Execute only machine-managed plugin/package resolvers. Checkout-local
+  # candidates are repository-controlled code, not trusted merely by path.
+  local candidates=()
+  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+    candidates+=("$CLAUDE_PLUGIN_ROOT/skills/lisa-secrets-access/scripts/resolve-secret.mjs")
+  fi
+  if [ -n "${PLUGIN_ROOT:-}" ]; then
+    candidates+=("$PLUGIN_ROOT/skills/lisa-secrets-access/scripts/resolve-secret.mjs")
+  fi
+  # Last rung deliberately needs no environment variable: an agent that was
+  # never handed a plugin root still has the installed package to fall back on.
+  candidates+=(node_modules/@codyswann/lisa/plugins/lisa/skills/lisa-secrets-access/scripts/resolve-secret.mjs)
+
+  local resolver
+  local tried=()
+  for resolver in "${candidates[@]}"; do
+    tried+=("$resolver")
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get POSTHOG_PERSONAL_API_KEY 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      # Empty/error means this substrate had no answer; try the next trusted one.
+    fi
+  done
+  # Name every path. A bare `return 1` sends the next reader hunting for a
+  # resolver they cannot see the absence of; the enumeration turns that into a
+  # seconds-long diagnosis. Paths and store coordinates only — never any
+  # resolved value, on any path.
+  echo "Error: could not resolve POSTHOG_PERSONAL_API_KEY through lisa-secrets-access." >&2
+  echo "Tried, in order (relative paths are from $PWD):" >&2
+  printf '  %s\n' "${tried[@]}" >&2
+  return 1
+}
+
+posthog_api() {
+  local path="$1"
+  local method="${2:-GET}"
+  local body="${3:-}"
+  local key
+  key=$(read_posthog_key) || {
+    echo "Error: no PostHog key. Set POSTHOG_PERSONAL_API_KEY, or store it as" >&2
+    echo "POSTHOG_PERSONAL_API_KEY in this project's secrets provider." >&2
+    return 1
+  }
+  local args=(-sS -X "$method" -H "Authorization: Bearer $key")
+  [ -n "$body" ] && args+=(-H "Content-Type: application/json" --data-binary "$body")
+  curl "${args[@]}" "${POSTHOG_HOST%/}/api${path}"
+}
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no PostHog access substrate available. Authenticate the PostHog MCP or set POSTHOG_PERSONAL_API_KEY.
+```
+
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — analytics
+retrieval. `query` is an HTTP POST, but it reads: it submits a query body and
+changes no PostHog state. So the `credential-substrate-precedence` guarded
+fallback for mutating operations (write, read back, assert the tenant from the
+response, roll back on mismatch) is not engaged here, and a failed tier is
+simply skipped. Adding a genuinely mutating operation — creating an insight,
+editing a feature flag — pulls that protocol in: a write of unknown outcome MUST
+reconcile by read-back before any retry.
+
+## Invariants
+
+- Tier order is `credential-substrate-precedence`: `POSTHOG_PERSONAL_API_KEY`
+  first, the PostHog MCP as a preserved first-class fallback. Identity-match
+  against the configured project is mandatory on every tier.
+- The key is resolved through `lisa-secrets-access`, with the bare
+  `POSTHOG_PERSONAL_API_KEY` environment variable as the documented fallback.
+  Never read a second credential store directly.
+- `POSTHOG_HOST` defaults to PostHog Cloud but can point at a self-hosted
+  deployment.
+- Consumer skills do not embed PostHog REST paths.