@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/skills/lisa-cross-pollinate/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: lisa-cross-pollinate
+description: "Detect a host project's locally-authored coding-agent definitions (skills, subagents, rules, commands, hooks, MCP) and make each available in the formats of the OTHER agents the project supports, as declared in .lisa.config.json. Any-to-any, provenance-tracked, idempotent, never clobbers hand-edited output."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
+argument-hint: "[path] [--dry-run] [--write]"
+---
+
+# Cross-Pollinate: $ARGUMENTS
+
+A host project that installs Lisa may hand-author a definition for **one** coding
+agent — a `.claude/skills/foo`, a `.cursor/rules/bar.mdc`, an MCP server only
+Claude sees. `/lisa:cross-pollinate` detects those locally-authored definitions
+and regenerates each in the formats of the **other** agents the project supports,
+so the whole fleet stays in parity with what a developer wrote for any single one.
+
+## The model
+
+```
+any agent's format  ->  Claude-format IR  ->  every OTHER configured agent
+```
+
+Claude format is the canonical intermediate representation (IR) because every
+Lisa generator already sources from it. So translation is always: **normalize
+the detected definition up to Claude-format IR, then fan that IR out** to each
+target agent using the documented mappings below. Never translate format A → B
+directly — that multiplies error and loses fidelity on every hop.
+
+The agents a project supports come from `.lisa.config.json` `harness`
+(`claude` | `codex` | `cursor` | `agy` | `copilot` | `opencode` | `both` | `fleet`;
+`all` is an alias for `fleet`). Only emit to agents that harness includes.
+
+## Provenance is authoritative — the lockfile, not file paths
+
+`.lisa/cross-pollination.lock.json` (committed) is the source of truth for what
+this skill generated. Location heuristics **cannot** work: a generated Cursor
+rule sits in the same `.cursor/rules/` directory as a hand-authored one. The
+lockfile is the only reliable way to enforce the four invariants:
+
+1. **No loops** — a path recorded as a `target` is NEVER treated as a source on
+   the next run. Without this, today's output becomes tomorrow's input and
+   translations ping-pong forever.
+2. **Garbage collection** — when a source is deleted/renamed, its now-orphaned
+   targets are removed.
+3. **Never clobber edits (Chesterton's fence)** — if a target's on-disk hash
+   differs from the recorded `generatedHash`, a human edited it. Stop and report;
+   do not overwrite. They may have intentionally diverged, or want to adopt the
+   edit as a new source.
+4. **Idempotent** — unchanged source + intact targets => no-op. (This is why it
+   is safe to also run during `lisa apply`.)
+
+Lockfile shape:
+
+```json
+{
+  "version": 1,
+  "entries": {
+    "skill:security-review": {
+      "source":  { "agent": "claude", "path": ".claude/skills/security-review", "hash": "…" },
+      "targets": [ { "agent": "codex", "path": ".claude/skills/security-review/agents/openai.yaml", "generatedHash": "…" } ]
+    }
+  }
+}
+```
+
+The `logicalId` is `<kind>:<name>` — stable across formats. It links a source to
+its targets and detects **collisions**: the same `logicalId` authored
+independently in two agents (neither generated). On a collision, NEVER
+auto-translate over either side — report it and let the human pick the source of
+truth.
+
+## How to run
+
+The deterministic core (scan, provenance, loop/GC/drift/conflict detection, and
+the skill + MCP emitters) is a bundled engine. **Always run it first** — it does
+the safe, mechanical work and tells you exactly what is left for you to translate
+by hand.
+
+```bash
+# dry-run (default): report only, writes nothing
+node "${CLAUDE_PLUGIN_ROOT}/scripts/cross-pollinate.mjs" "$PROJECT_ROOT" --json
+# apply the deterministic emits + update the lockfile
+node "${CLAUDE_PLUGIN_ROOT}/scripts/cross-pollinate.mjs" "$PROJECT_ROOT" --write
+```
+
+In the Lisa source repo itself the path is
+`node plugins/lisa/scripts/cross-pollinate.mjs` (built) or
+`node plugins/src/base/scripts/cross-pollinate.mjs` (source).
+
+The JSON report has four lists you act on:
+
+- `emits` — already handled by `--write` (skills, MCP). Verify, don't redo.
+- `conflicts` — STOP. Report each to the user; do not translate.
+- `orphans` — GC'd by `--write`. Confirm the removals look right.
+- `pending` — **your job.** Definitions whose target format the engine does not
+  emit deterministically. Translate each per the mappings below, then record
+  provenance (see "Recording provenance").
+
+## Per-agent format mappings (for `pending` translation)
+
+Normalize the source to Claude-format IR first, then emit per target:
+
+### Rules
+- **Claude ↔ Cursor**: handled deterministically by the engine. Claude reads
+  `.claude/rules/<name>.md`; Cursor reads `.cursor/rules/<name>.mdc` with YAML
+  frontmatter (`description` from the first H1, `alwaysApply: true`) and intra-rule
+  link extensions rewritten. You do not translate these — verify the engine's
+  emits.
+- **Codex / OpenCode / agy** (`pending`): project rules are delivered via
+  `AGENTS.md`, not a per-rule file. MERGE the rule content into `AGENTS.md` under a
+  stable marked section rather than writing a separate file (so re-runs replace,
+  not append). agy never gets a duplicate rule file (rules-once).
+- **Copilot** (`pending`): `.github/copilot-instructions.md` (inline). Merge into a
+  marked section, don't scatter.
+
+### Subagents
+- **Claude / agy / Cursor / OpenCode**: `agents/<name>.md` (or `.claude/agents/`).
+- **Copilot**: `agents/<name>.agent.md` (note the `.agent.md` suffix).
+- **Codex**: does not consume agent files. Report as **dropped — unsupported**,
+  do not invent a target.
+
+### Commands
+- **Claude / Cursor / Copilot**: markdown command files (`.claude/commands/…`).
+- **Codex / agy**: auto-derive commands from skills; no separate command file.
+  Report as **dropped — derived-from-skill**.
+
+### Hooks (lossy — drop-and-report, never fake support)
+- Event-name casing differs per agent (`PreToolUse`→`preToolUse`/`beforeSubmitPrompt`,
+  `UserPromptSubmit`→`userPromptSubmitted`, `Stop`→`agentStop`/`stop`, …).
+- **agy** lacks `SessionStart`/`SubagentStart` — only `PreToolUse` (e.g.
+  block-no-verify) is portable. Everything else: dropped — unsupported.
+- **Codex** plugin hooks do not fire in `codex exec` — install into
+  `~/.codex/hooks.json`, not a bundled file.
+- **Copilot** rejects the entire hooks config if a `SubagentStart`/empty-matcher
+  entry is present — drop that event wholesale.
+- For every hook you cannot faithfully translate to a target, REPORT it with the
+  reason. Do not silently omit (no silent caps).
+
+### MCP (handled by the engine for Claude↔Cursor; report others)
+- **Claude**: `.mcp.json`. **Cursor**: `.cursor/mcp.json` (same JSON shape).
+- **Copilot**: inline `mcpServers` object in the plugin manifest (bundled
+  `.mcp.json` is ignored). **Codex**: TOML / `.codex-plugin` pointer.
+  **agy/OpenCode**: user-global installer / `.opencode`. The engine reports these
+  as pending; translate per the target's documented shape or report dropped.
+
+## Recording provenance for hand-translated `pending` items
+
+After you write a target by hand, it MUST be recorded in
+`.lisa/cross-pollination.lock.json` or the next run will treat it as a source
+(loop) or fail to GC it. Re-run the engine after staging your translated files —
+on its next pass it adopts and hashes any target already referenced — OR add the
+entry yourself following the lockfile shape above (compute `generatedHash` as the
+sha256 of the written file/dir). Prefer the engine; only hand-edit the lock if
+the engine cannot infer the mapping.
+
+## Output
+
+Report, concisely:
+- harness + resolved target agents
+- counts: detected sources, written, skipped-drift, GC'd
+- every conflict (with the agents involved)
+- every pending item you translated, and every hook/agent/command you **dropped**
+  with its reason
+- confirm `.lisa/cross-pollination.lock.json` was updated and the working tree
+  otherwise contains only intended changes
+
+## Rules
+
+- Treat the lockfile as authoritative; never infer "mine vs theirs" from paths.
+- Never overwrite a drifted (hand-edited) target — report it.
+- Never auto-resolve a collision — report it.
+- Only emit to agents the project's `harness` includes.
+- Drop-and-report any translation a target genuinely cannot support; never fake
+  a location you are unsure of.
+- This skill is additive — it does not delete a human's source definitions, only
+  its own orphaned generated targets.

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

@@ -0,0 +1,96 @@
+---
+name: lisa-debrief
+description: "Run the Debrief flow over a shipped initiative. Input: a PRD URL (Notion / Confluence / Linear / GitHub Issue / file), a JIRA epic key, or a GitHub epic issue URL. Output: a triage-ready learnings document covering every work item in the initiative — edge cases, gotchas, process friction, tooling gaps, convention drift — each with structured evidence and a human-disposition field. Persistence is deferred to lisa-debrief-apply."
+allowed-tools: ["Skill", "ToolSearch", "Bash", "Read", "Glob", "Grep", "TeamCreate"]
+---
+
+# Debrief: $ARGUMENTS
+
+Walk the original Plan for `$ARGUMENTS`, mine the completed work items and their PRs, and produce a triage-ready learnings document for human review.
+
+## 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 and 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. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
+
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), 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.
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+| Input shape | Resolution |
+|-------------|------------|
+| Notion / Confluence / Linear / GitHub Issue PRD URL | Fetch the PRD; read its `## Tickets` (or equivalent) back-link section written by the Plan flow |
+| File path to a PRD markdown | Read the file; parse its `## Tickets` section |
+| JIRA epic key (e.g. `SE-1234`) or epic URL | Fetch the epic; list its child issues (Stories, Tasks, Bugs) |
+| GitHub epic issue URL or `<org>/<repo>#<n>` | Fetch the epic issue; list its sub-issues / linked items |
+
+If the PRD has no `## Tickets` section AND the input is not an epic, stop and report — the Plan flow's PRD back-link step (`lisa-prd-backlink`) was likely skipped. Suggest re-running Plan to populate the section, or pass the epic key directly.
+
+## Gate
+
+Run before mining begins:
+
+1. **All work items terminal.** Every linked work item must be in a terminal state (Done / Closed / Cancelled equivalent for the tracker). If any item is still open, stop and list the unfinished items — Debrief is post-shipping by definition.
+2. **PR coverage.** Every Done item that was implementable (Story / Task / Bug; not Spike) must have at least one merged PR linked. Items missing a PR are recorded as **anomalies** to surface in the report rather than silently excluded — a Done item with no PR is itself a learning ("how did this ship?").
+3. **Headless safety.** In headless / `-p` / scheduled mode, do not block on missing input — fail fast with a clear error listing what was needed.
+
+## Flow
+
+Execute the **Debrief** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The rule contains the canonical step sequence (gate, mining, synthesis, output, hand-off). This skill does NOT restate flow steps — change them in the rule, propagate everywhere.
+
+The flow's mining step runs `tracker-mining-specialist` and `pr-mining-specialist` in parallel as separate tasks within the team. Both must complete before `learnings-synthesizer` runs. Express this with `blockedBy` so the synthesizer task is automatically gated on the two mining tasks.
+
+## Exhaustiveness expectation
+
+Debrief is deliberately exhaustive — the human, not the agent, decides what is worth keeping. Specialists should err toward surfacing more candidates, not fewer. A candidate that the synthesizer rates low confidence is still a row in the triage doc; only outright duplicates are dropped.
+
+## Output
+
+A markdown triage document at `./debrief/<initiative-slug>-<YYYY-MM-DD>.md` (or wherever the project's debrief output directory is configured) containing:
+
+1. **Header** — initiative name, source PRD/epic link, work-item count, PR count, generation date, gate results.
+2. **Anomalies** — work items missing PRs, items with abnormal status-transition timing, PRs with no review comments at all (signal-of-absence is a learning), etc.
+3. **Candidate learnings** — one row per candidate, grouped by category (Edge case / Recurring gotcha / Process friction / Tooling gap / Convention drift / Decomposition infidelity / PRD defect / Missing tool access, plus `Uncategorized` for a finding none of the eight fit). The category set is owned by `learnings-synthesizer` — every category it can emit must have a section here and a route in `lisa-debrief-apply`, or an accepted row cannot be applied. Each row has:
+   - `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, 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.
+
+Before returning, write the Debrief run's direct usage onto the triage document through
+`lisa-usage-accounting` so the markdown artifact carries its own `## Lisa Usage` section separate
+from delivery-time usage. If runtime usage is unavailable, record a debrief entry with
+`source: unavailable` and nullable token/cost fields instead of skipping the row.
+
+The skill's terminal output is the path to the triage document and a one-line summary of counts per category. Persistence does not happen here — that is `lisa-debrief-apply`'s job.
+
+## Hand-off
+
+After producing the triage document, print:
+
+```text
+Triage document written to: <path>
+Counts: <n> edge cases, <n> gotchas, <n> friction, <n> tooling gaps, <n> convention drift, <n> decomposition infidelity, <n> PRD defects, <n> missing tool access, <n> uncategorized; <n> anomalies
+Next: human triage. When done, run `/lisa:debrief:apply <path>` to persist accepted learnings.
+```
+
+Then stop. Debrief never persists learnings on its own.

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

@@ -0,0 +1,106 @@
+---
+name: lisa-debrief-apply
+description: "Apply human-marked dispositions from a Debrief triage document. Reads the triage doc produced by lisa-debrief, parses each row's disposition (Accept / Reject / Defer), and routes Accepted items to their persistence destination. Deterministic and idempotent — safe to re-run if dispositions are added incrementally."
+allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
+---
+
+# Debrief Apply: $ARGUMENTS
+
+Read the triage document at `$ARGUMENTS` and persist every Accepted candidate learning to its destination.
+
+This skill is intentionally **single-agent** — there is no team. Routing is deterministic given the disposition column. Spawning sub-agents would only add latency.
+
+## Input
+
+A path or URL to a Debrief triage document produced by `lisa-debrief`. The document is expected to follow the structure that skill produces — a header, an anomalies section, candidate-learning rows grouped by category, and a source-map appendix.
+
+## Pre-flight
+
+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 host rules (`.agents/rules/`) / `AGENTS.md` are no longer knowledge destinations (see [Ledger persistence](#ledger-persistence-knowledge-categories)).
+
+## Routing rules
+
+For every row marked **Accept**:
+
+| Category | Destination | Action |
+|----------|-------------|--------|
+| Edge case | Edge Case Brainstorm checklist in `intent-routing.md` | Append the new pattern + question to the matching group (Navigation, Data, Failure, Input, Auth, or a new group if none fit). Use the row's `Summary` and `Evidence` link as a citation comment. |
+| Recurring gotcha | Committed learnings ledger (via contract) | Persist a ledger entry per [Ledger persistence](#ledger-persistence-knowledge-categories). The `rule` is the recurring gotcha and the guard against it; `why` is the causal claim. |
+| Process friction | Committed learnings ledger (via contract) | Persist a ledger entry per [Ledger persistence](#ledger-persistence-knowledge-categories). The `rule` is the friction-avoiding guideline; `why` names the friction it prevents. |
+| Tooling gap | Configured tracker — or upstream Lisa when harness-level | **Split by level.** Project-level (a missing project script, hook, or automation) → create a ticket via `lisa-tracker-write` with `issue_type: Task`, summary derived from the row's `Summary`, description citing the evidence and the originating debrief doc, labeled `type:tooling` / `lifecycle-improvement`, and explicit `build_ready: true` per `ready-role-filing` (a tooling gap the factory can close itself is queue work, and an omitted flag is NOT build-ready on any tracker). Harness-level (a Lisa skill/gate/agent that should have caught the issue but didn't) → file an upstream Lisa issue exactly per the "Filing upstream" procedure in `lisa-rework-triage` (dedupe search first, three-audience description, evidence chain, `self-hardening` label; repo from `.lisa.config.json` `hardening.upstreamRepo`, default `CodySwannGT/lisa`). |
+| Convention drift | Committed learnings ledger (via contract) | Persist a ledger entry per [Ledger persistence](#ledger-persistence-knowledge-categories). The `rule` is the correct convention; `why` records the drift it corrects. |
+| Decomposition infidelity | Upstream Lisa repo | File an upstream Lisa issue per the "Filing upstream" procedure in `lisa-rework-triage`, citing the PRD text vs. the distorted ticket AC and naming the gate that passed it. |
+| PRD defect | Source PRD | Comment on the PRD via the `lisa-prd-backlink` lineage quoting the defective requirement and the failure it missed; flag for product review. Never silently edit the spec. |
+| Missing tool access | Configured tracker | Create a provisioning ticket via `lisa-tracker-write` (`issue_type: Task`, `type:tooling`) describing the missing tool/credential/environment and which flow needs it. Pass `human_gate: "a human must grant the missing access"` per `ready-role-filing` — the factory cannot provision its own credentials. |
+| Uncategorized | **No route — requires reclassification** | `Uncategorized` records that the synthesizer could not fit the finding to a category; it is not itself a destination. Do NOT guess a route and do NOT silently skip the row. Leave the row unapplied, mark it `[!] Needs reclassification — <the synthesizer's "why no category fit" note>`, and list it under its own heading in the run summary so the human can retag it to one of the eight and re-run `apply`. A row that stays `Uncategorized` across runs is a signal the category set itself is missing a case — worth an upstream Lisa issue, not a forced fit. |
+
+For every row marked **Reject** or **Defer**: no action. Defer is a no-op for `apply` but worth surfacing in the run summary — the human may want to revisit at the next debrief.
+
+## Ledger persistence (knowledge categories)
+
+The three knowledge categories — **recurring gotcha**, **process friction**, and **convention drift** — all persist to the committed learnings ledger through the SAME executable contract the learner uses (`@codyswann/lisa/learnings`). This is the single governed, budgeted, contract-validated, team- and cloud-visible knowledge surface. **Never hand-edit the ledger markdown** — every write goes through the contract, or it is a bug.
+
+For each such Accepted row:
+
+Use the branch, PR deduplication, commit, submission and confidence-routing sequence in `lisa-persist-learning` Phase 3. The human's Accepted disposition supplies the high-confidence durable-learning decision here. Before writing, create or reuse the learning branch in an isolated worktree; never write the ledger in the default-branch checkout. Submit a pull request carrying only the resolved ledger or overflow surface. Keep the triage-document update separate. A local write alone is not an applied learning: report the PR and whether it is pending or merged.
+
+1. **Resolve the ledger path (never hardcode).** Use `resolveProjectLearningsFile` from `@codyswann/lisa/learnings` — 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)); })')
+   ```
+
+2. **Consolidation check (mandatory before writing).** Parse the existing entries with `parseLearningsFile` and look for one related to the row (same failure class, overlapping topic, or near-duplicate wording). Then write through the contract:
+   - **Related entry found** → consolidate with the exact parsed versions: `persistConsolidatedLearning(projectRoot, entry, { supersede: [{ id: <related id>, fingerprint: <related fingerprint> }], onStaleSupersede: targets => report(targets) })`. Every stamp is checked together inside the writer lock. If any is stale, the writer removes none, safely appends the new fingerprint, and reports the mismatch. Never append a near-duplicate sibling by choice — a sibling is a bug; the stale append is the deliberate concurrent-writer preservation path.
+   - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
+
+3. **Entry mapping (eight fields).**
+   - `fingerprint` — `learningFingerprint(rule)` from `@codyswann/lisa/learnings`, computed from the final consolidated rule. Keep workflow/PR markers separate: use the `lisa-persist-learning` Phase 0 occurrence key with the stable triage-document reference as `triggering_issue`; the rule distinguishes rows sharing that reference.
+   - `id` — initially `id = fingerprint`. On an exact stamped consolidation the writer carries forward the deterministic primary target id; report the returned id in the run summary.
+   - `rule` / `why` — from the row's `Summary` and the category-specific guidance in the routing table above (≤240 chars, ≤2 lines).
+   - `provenance` — **the triage-doc row's evidence links**. Evidence supports a rule; it is not the rule's identity, and one event may support several distinct lessons.
+   - `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`). 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.
+
+**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. Compute the final rule's fingerprint before checking its destination:
+
+- **Knowledge categories (gotcha, friction, drift) → ledger.** Read the default-branch ledger through `parseLearningsFile` from `@codyswann/lisa/learnings` and compare `learningFingerprint(existing.rule)` with `learningFingerprint(candidate.rule)`. An equal rule there is already captured: preserve its legacy id and fingerprint, report that id, and skip the write. A rule present only on an open PR branch remains pending, not applied; reuse that PR. For changed consolidations use exact parsed legacy stamps in `supersede`; never rewrite them merely to adopt the helper. Distinct rules sharing provenance must both be considered. Also reuse the existing PR when its workflow marker is present, including a PR not yet merged.
+- **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.
+
+## Updating the triage doc
+
+After a learning PR merges (or the rule is already in the default-branch ledger), replace the row's `[ ] Accept` checkbox with `[x] Applied — <entry id and PR>`. While the PR is open, leave the row Accepted and record `Pending PR: <url>` so a rerun reuses it. Other destinations retain their successful-write marking. If a write or submission fails, mark the row `[!] Apply failed — <reason>` and continue with the rest.
+
+## Output
+
+A run summary printed to the user:
+
+```text
+Applied <n> learnings:
+  <n> edge cases → intent-routing.md
+  <n> gotchas → ledger (<entry-id1>, <entry-id2>, ...)
+  <n> friction → ledger (<entry-id1>, ...)
+  <n> convention drift → ledger (<entry-id1>, ...)
+  <n> tooling gaps (project) → <tracker> (<key1>, <key2>, ...)
+  <n> tooling gaps (harness) → upstream Lisa (<issue-url1>, ...)
+  <n> decomposition infidelity → upstream Lisa (<issue-url1>, ...)
+  <n> PRD defects → PRD comments (<prd-link1>, ...)
+  <n> missing tool access → <tracker> (<key1>, ...)
+Skipped:
+  <n> rejected, <n> deferred, <n> already-applied
+Needs reclassification:
+  <n> uncategorized (retag to one of the eight categories and re-run apply)
+Failed:
+  <n> (see <path> for details)
+Triage doc updated in place: <path>
+```
+
+Report ledger PRs and their pending/merged state in the summary. Other local changes, such as the triage document or intent-routing checklist, remain separate from those PRs and may be committed through the project's normal flow.

package/plugins/lisa-devin/skills/lisa-delivery-effectiveness/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: lisa-delivery-effectiveness
+description: "Measure whether the work the factory delivers was worth shipping — gate rejection, rework, escape, first-pass yield and cost per delivered item — so autonomy rate cannot stand alone as a success measure."
+allowed-tools: ["Read", "Grep", "Glob", "Bash"]
+---
+
+# Delivery Effectiveness
+
+Autonomy rate answers how much ran without a human. It says nothing about whether any of it should have shipped, and on its own it rewards exactly the wrong thing: a factory that produces rejected work faster scores better.
+
+## The five measures
+
+Each needs a stated numerator, denominator and window, or it is a number-shaped opinion.
+
+| Measure | Counts | Reads as |
+| --- | --- | --- |
+| **Gate rejection rate** | Work the pipeline refused, over work submitted | How much effort is spent producing output the standards reject |
+| **Rework rate** | Items reopened or returned after being declared complete, over items completed | How often "done" was not done |
+| **Escape rate** | Defects reaching production, over items released | What the gates did not catch |
+| **First-pass yield** | Items reaching terminal state with no rework, over items started | The one number that moves only when the whole line works |
+| **Cost per delivered item** | Metered spend, over items reaching terminal state | What a unit of accepted output actually costs |
+
+First-pass yield is the summary measure worth watching, because every other failure shows up in it. The other four exist to tell you *where* it went.
+
+## Where the numbers come from
+
+Prefer the systems of record over anything self-reported: the tracker for state transitions and reopenings, CI history for gate rejections, the release record for escapes, the billing or gateway boundary for spend. An agent's account of its own rework rate is the least reliable source available and the easiest one to reach for.
+
+Say which source each measure came from. Two measures drawn from different systems with different definitions of "complete" cannot be compared, and that mismatch is invisible in the result.
+
+## Set targets that can only tighten
+
+Targets are yours to declare — this says nothing about what a good rejection rate is, because that depends on the standards being enforced and the work being attempted. But declare them, disclose them, and let them move in one direction only. A target quietly loosened to match the current number is a redefinition dressed as an improvement.
+
+## Read it against autonomy, never instead of it
+
+Report both, together, always. The pairing is the point:
+
+- **High autonomy, high first-pass yield** — the thing everyone is aiming for.
+- **High autonomy, low first-pass yield** — an unattended process producing work its own gates reject. Reporting autonomy alone would conceal exactly this, which is why the pairing is not optional.
+- **Low autonomy, high first-pass yield** — humans are carrying the quality. Honest, and expensive.
+- **Low autonomy, low first-pass yield** — the machinery is not the problem yet.
+
+## Output
+
+```text
+## Delivery Effectiveness
+
+**Window:** dates · **Autonomy rate over the same window:** %
+
+| Measure | Value | Numerator / denominator | Source of record | Target | Trend |
+|---|---|---|---|---|---|
+| Gate rejection rate | | | | | |
+| Rework rate | | | | | |
+| Escape rate | | | | | |
+| First-pass yield | | | | | |
+| Cost per delivered item | | | | | |
+
+**Reading:** which of the four autonomy/yield quadrants this window sits in
+**Uncollected:** any measure not gathered, and why — never an estimate in its place
+**Filed:** work items raised for measures outside target
+```