@codyswann/lisa 2.245.1 → 2.247.0

package/all/create-only/.claude/rules/PROJECT_RULES.md

@@ -5,5 +5,13 @@ Project-specific rules and guidelines that apply to this codebase.
 Rules in `.claude/rules/` are automatically loaded by Claude Code at session start.
 Add project-specific patterns, conventions, and requirements below.
 
----
+This file is **human-authored only** — the humans' decree surface. Automated
+flows never append to it: machine-captured learnings land in the learnings
+ledger (default `.lisa/PROJECT_LEARNINGS.md`) via the executable contract, and
+the gardener (`/lisa:learnings:audit`) proposes promotions, demotions, and
+retirements as human-gated tracker tickets. Existing sections of this file are
+first-run gardener candidates like any other knowledge — expect prose that
+restates what a lint or hook already enforces to earn a promote-and-delete
+ticket over time, so this file shrinks instead of growing.
 
+---

package/package.json

@@ -102,7 +102,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.245.1",
+  "version": "2.247.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.245.1",
+  "version": "2.247.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.245.1",
+  "version": "2.247.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

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

@@ -18,7 +18,7 @@ A path or URL to a Debrief triage document produced by `lisa-debrief`. The docum
 
 1. **Verify the doc exists and parses.** If the file cannot be read or the expected sections are missing, stop and report — do not guess.
 2. **Confirm dispositions exist.** If every row is unmarked, stop and ask the human to triage first. A pristine doc is a no-op, not an error to silently swallow.
-3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), `projectRulesFile` (default: `.claude/rules/PROJECT_RULES.md`), memory directory (per the auto-memory system path), tracker for new tickets.
+3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), the committed learnings ledger path (resolve it — never hardcode — via `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md`), tracker for new tickets. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the ledger now; machine-local auto-memory and `PROJECT_RULES.md` / `CLAUDE.md` are no longer knowledge destinations (see [Ledger persistence](#ledger-persistence-knowledge-categories)).
 
 ## Routing rules
 
@@ -27,19 +27,49 @@ 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 | Memory file (`project_*.md`) | Write a new memory entry with `type: project`, structured as: rule, **Why:**, **How to apply:**. Add an index line to `MEMORY.md`. |
-| Process friction | Configured project rules file | Append a one-line guideline to the `.lisa.config.json` `projectRulesFile` destination (default `PROJECT_RULES.md`) under an appropriate heading (or create one). |
+| 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`. 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 | `CLAUDE.md` for project-wide agent operating instructions; otherwise the configured project rules file for codebase conventions | Append the convention as a one-paragraph note under the relevant section. If no relevant section exists, create one. |
+| 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. |
 
 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:
+
+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 via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the old entry's still-true content into the new rule. Never append a near-duplicate sibling — a sibling is a bug.
+   - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
+
+3. **Entry mapping (seven fields).**
+   - `id` — the entry id returned by the contract writer (report it 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**. This is the same evidence link that doubles as the idempotency fingerprint below, so the row's provenance is what a later re-apply scans for.
+   - `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`).
+   - `confidence` = **`high`**. A human marking the row **Accept** is corroboration — an independent human judgement that the learning is real — so a debrief-accepted entry starts higher than the learner's single-occurrence auto-capture (which defaults to `low`). The writer re-asserts the entry and token budgets; an over-budget failure means consolidate harder or drop, never truncate by hand.
+
+**Machine-local memory is no longer a knowledge destination.** Auto-memory (`project_*.md`, `MEMORY.md`) remains available only for the assistant's *personal* collaboration notes — it is invisible to cloud runs and to teammates, so it can never hold shared project knowledge. **`CLAUDE.md` is human-authored** agent operating instruction and `PROJECT_RULES.md` is durable human-authored guidance; `apply` never writes to any of the three for these categories.
+
 ## Idempotency
 
-`apply` is safe to re-run. Each Accepted row carries an evidence link that doubles as a fingerprint — before writing, check whether the destination already cites that fingerprint. If it does, 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.
+`apply` is safe to re-run. Each Accepted row carries an evidence link that doubles as a fingerprint. Before writing, check whether the destination already cites that fingerprint:
+
+- **Knowledge categories (gotcha, friction, drift) → ledger.** Parse the ledger once with `parseLearningsFile` from `@codyswann/lisa/learnings` and scan the entries' `provenance` for the row's evidence link. If any entry's provenance already contains it, the row is already persisted — skip the write. This replaces the old scattered-file greps (memory files, `PROJECT_RULES.md`, `CLAUDE.md`): provenance in the single governed ledger is now the one fingerprint surface.
+- **Other categories** keep their existing destination check (the tracker for the ticket marker, the PRD for the defect comment, `intent-routing.md` for the edge-case citation).
+
+If the fingerprint is already present, skip the write and note the row as `already-applied` in the run summary. This lets the human triage a doc incrementally (mark a few, run apply, mark more, run apply again) without producing duplicates.
 
 ## Updating the triage doc
 
@@ -52,11 +82,11 @@ A run summary printed to the user:
 ```text
 Applied <n> learnings:
   <n> edge cases → intent-routing.md
-  <n> gotchas → memory
-  <n> friction → PROJECT_RULES.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> convention drift → CLAUDE.md
   <n> decomposition infidelity → upstream Lisa (<issue-url1>, ...)
   <n> PRD defects → PRD comments (<prd-link1>, ...)
   <n> missing tool access → <tracker> (<key1>, ...)
@@ -67,4 +97,4 @@ Failed:
 Triage doc updated in place: <path>
 ```
 
-If anything is written to a tracker, suggest the human commit the local file changes (memory, rules, intent-routing) when ready — `apply` does not commit.
+If anything is written to a tracker, suggest the human commit the local file changes (the learnings ledger, intent-routing) when ready — `apply` does not commit.

package/plugins/lisa/.codex-plugin/skills/lisa-learnings-audit/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: lisa-learnings-audit
+description: "The gardener of the learnings…"
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Learnings Audit (the gardener): $ARGUMENTS
+
+Run one audit cycle over this project's knowledge surfaces and convert what the
+evidence supports into **human-gated tracker tickets** — nothing else. The
+gardener is the only flow in Lisa that takes knowledge *back out* or moves it
+*up* the ladder; it closes the loop that capture (learner, debrief-apply, MLD)
+opens.
+
+`$ARGUMENTS` (all optional): `max_candidates=<n>` (default **10** — cap on
+per-item PROMOTE/DEMOTE tickets filed per run, following the
+`lisa-repair-intake` bounded-cycle precedent; CONFIRM/RETIRE batch rows are
+not capped), `surface=<ledger|rules|skills|wiki|all>` (default `all`),
+`dry_run=true` (report what would be filed, file nothing).
+
+## Intent
+
+Keep the knowledge system from silting up: every learning lives at the
+cheapest rung that still prevents the mistake (per the six-rung ladder,
+PRD #1729), prose never duplicates a mechanical owner, the eager tier shrinks
+over time, and every change to "what the agents believe" is approved by a
+human through the tracker. A quiet run with nothing to propose is a healthy
+outcome and says so in its one-line summary.
+
+## Sources of truth
+
+Inventory these surfaces each run — discover dynamically, never from a
+memorized list:
+
+1. **The ledger** — resolve via `.lisa.config.json` (`learnings.file`, default
+   `.lisa/PROJECT_LEARNINGS.md`) and read it ONLY through the executable
+   contract from `@codyswann/lisa/learnings`: `parseLearningsFile` for the
+   **full parse** (the gardener is the maintenance loop — auditing requires
+   every entry, and the contract-mediated full parse is its documented
+   exemption from projection-only serving) plus `projectLearnings` for the
+   bounded projection (to measure **budget pressure**: how many entries the
+   projection omits). Never hand-parse or hand-edit the raw file.
+2. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
+   the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
+   human-authored only — its existing sections are still audit candidates;
+   first-run candidates come from exactly there).
+3. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
+   exposes (descriptions are eager context; bodies load on invoke).
+4. **The wiki index** — `wiki/index.md` when the project has a wiki.
+5. **Mechanical-control surfaces** — lint configs (ESLint/oxlint), ast-grep
+   rules, git hooks, test suites, and `package.lisa.json` force sections:
+   the surfaces that answer "does a mechanical owner already exist?".
+6. **The tracker** — prior gardener tickets (open, done, and closed-rejected)
+   are its memory; see Idempotency.
+
+## Candidate-selection rules
+
+A surface item becomes a candidate only when evidence supports a change.
+Gather, per item, the five evidence axes:
+
+| Axis | Question | How |
+|------|----------|-----|
+| **Recurrence** | Has the same failure class recurred since the entry's `last_confirmed` (or the rule's last touch)? | Search issues/PRs/commits since that date — reuse the `git-history-analyzer` agent for commit/PR archaeology; tracker search for issue recurrence. |
+| **Staleness** | Does the item reference files, flags, versions, or tools that no longer exist? | Glob/Grep the referenced paths and configs. |
+| **Redundancy** | Does a mechanical owner already enforce the invariant? (The double-payment hunter.) | Check lint/ast-grep/hook/test/force surfaces for the same invariant. |
+| **Contradiction** | Does the item contradict another rule, skill, config, or observed current behavior? | Cross-reference the inventoried surfaces. |
+| **Budget pressure** | Is the ledger projection omitting entries, or the eager tier growing? | `projectLearnings` omission count; eager-tree token/size trend. |
+
+Selection outcomes per candidate: **PROMOTE** (up the ladder), **DEMOTE**
+(down the ladder), **CONFIRM** (evidence the entry demonstrably applied —
+a `last_confirmed` bump), **RETIRE** (provably redundant/stale — proof, not
+vibes), or leave alone. No evidence ⇒ no candidate; the gardener never files
+a recommendation it cannot evidence.
+
+**The eager tier is audited every run** — including
+**Lisa's own shipped eager rules**, not just host additions. Admission is demotion-biased and
+earned only by repeated-miss evidence (see the `promotion-contract` rule);
+an eager rule without that evidence gets a DEMOTE candidate citing the
+admission policy, scoped upstream when the rule ships with the kernel.
+
+**Exclusions (no learning loops about learning).** Never candidates, never
+evidence:
+
+- The gardener's own tickets, PRs, and comments (anything carrying the
+  `[lisa-gardener]` marker).
+- All learning-machinery artifacts: items carrying `[lisa-learning-drop]`,
+  `[lisa-learning-pr]`, `[lisa-learning-upstream-handoff]` (any
+  `[lisa-learning-*]` marker), `[lisa-rejection-candidate]`, or
+  `[lisa-archaeology-candidate]`, and the `learning:needs-triage` label.
+
+## Scope
+
+- **In scope**: recommending placement changes for knowledge on any
+  inventoried surface, in this repository (`project` scope) or upstream in
+  `CodySwannGT/lisa` (`upstream` scope).
+- **Out of scope**: executing any promotion/demotion/retirement (the factory
+  does, per flipped tickets), editing any knowledge surface, auto-apply modes
+  (v1 is fully gated), and the capture streams (learner, debrief, MLD).
+
+## Proof
+
+A run is proven, not asserted. The per-run report (and the run ticket, when
+one exists) must show:
+
+- The surfaces inventoried, with counts (ledger entries parsed, rules files,
+  skills, wiki pages, mechanical controls).
+- Per filed ticket: the fingerprint marker, the evidence refs behind it, and
+  the router's rung — so any reviewer can replay the reasoning from links
+  alone.
+- Per skipped candidate: which dedupe hit suppressed it (open ticket URL,
+  done ticket, or rejection date).
+- For `nothing-needed`: the thresholds nothing met, in one line.
+
+The tickets themselves are the durable artifacts; the report is how a human
+audits the auditor without re-running it.
+
+## The audit cycle
+
+1. **Inventory** the sources of truth above.
+2. **Evidence** — gather the five axes per item; drop items with none.
+3. **Classify** — pass each candidate (`rule`, `why`, `provenance`,
+   `evidence`) to the ladder router (the `skill-evaluator` agent). The router
+   is **advisory**: it returns `rung`, `scope`, `rationale`, and
+   `drafted_artifact`; the gardener decides whether the evidence clears the
+   filing bar and attaches the router's draft to the ticket.
+4. **Emit** (see Ticket emission).
+5. **Report** the terminal state and one-line summary.
+
+## Ticket emission
+
+All project-tracker writes go through **`lisa-tracker-write`** so gardener
+tickets pass the same validation gates as all factory work. Nothing is created
+`status:ready` — the human flips.
+
+**Per-item tickets — PROMOTE / DEMOTE** (`issue_type: Task`; GitHub trackers
+carry the `type:Task` label) — one ticket per recommendation, capped by
+`max_candidates`:
+
+- A **three-audience description** (operator: what changes about what the
+  agents believe and why it is safe; engineering: the surface, the invariant,
+  the destination rung; QA: how to verify the move) with **evidence links**
+  (the recurrence issues/PRs/commits, the staleness proof, the mechanical
+  owner).
+- The router's **`drafted_artifact`** verbatim (the lint/hook sketch +
+  diagnostic text, proposed rule text, skill outline, page outline, or
+  redundancy proof).
+- For **EXECUTABLE-CONTROL** promotions, embed the promotion-contract AC
+  template below **verbatim** (markers included — do not paraphrase, reorder,
+  or partially quote it; it is the single source of truth from the
+  `promotion-contract` rule):
+
+<!-- promotion-contract-ac-template:start -->
+### Acceptance Criteria (promotion-to-control contract)
+
+One atomic PR that satisfies all four legs — a PR missing any of the four is
+rejected by rule (see the `promotion-contract` rule):
+
+- [ ] **Enables the control** — the lint / ast-grep / type constraint / test /
+      hook / `package.lisa.json` force entry is active and blocking.
+- [ ] **Fixes the existing violation population** — every current violation is
+      migrated in this same PR, so the control lands green with no blanket
+      ignores.
+- [ ] **Ships a remediation-teaching diagnostic** — the failure message states
+      the violated invariant, why it holds, and the concrete fix.
+- [ ] **Deletes the superseded prose** — the ledger entry / rules section this
+      control replaces is removed in this same PR, citing the new mechanical
+      owner.
+<!-- promotion-contract-ac-template:end -->
+
+**One batch ticket per run — CONFIRM + RETIRE** (`issue_type: Task`): a single
+ticket listing every CONFIRM row (`last_confirmed` bump, with the evidence the
+entry demonstrably applied) and every **provably-redundant** RETIRE row (with
+the mechanical owner / staleness proof per row). Rows are individually
+strikeable — the human deletes rows they reject, then flips the ticket ready.
+The gardener **never bumps `last_confirmed` itself**: the bumps are executed
+by the **implementing factory run** that picks up the flipped batch ticket.
+Embed the following execution contract **verbatim** (markers included — do
+not paraphrase, reorder, or partially quote it) in every batch ticket, so the
+implementing run receives its instructions inside the work item:
+
+<!-- gardener-batch-ticket-template:start -->
+### Execution contract (CONFIRM/RETIRE batch)
+
+- Apply each surviving CONFIRM row via `confirmLearningEntry` from
+  `@codyswann/lisa/learnings` — never hand-edit the ledger.
+- Implement each surviving RETIRE row as a proof-citing deletion PR per the
+  `promotion-contract` rule's reverse-atomicity clause: the deleting PR must
+  cite the row's mechanical owner or staleness proof.
+- Struck/deleted rows are human rejections — skip them; they are not re-filed
+  without new postdating evidence.
+<!-- gardener-batch-ticket-template:end -->
+
+**Upstream scope** → an issue on `CodySwannGT/lisa` (resolve via
+`hardening.upstreamRepo`, default `CodySwannGT/lisa`), following the
+`lisa-rework-triage` "Filing upstream" procedure and its two lanes:
+`self-hardening` for defects, `template-candidate` for generalizable patterns
+(with the required `## Proposed template change` section). Same dedupe-marker
++ evidence-chain discipline; the gardener's fingerprint marker (below) rides
+in the issue body.
+
+## Idempotency
+
+Every recommendation carries a stable fingerprint embedded as an HTML comment
+marker in the ticket/issue body:
+
+```
+<!-- [lisa-gardener] key=<surface>+<invariant-hash> -->
+```
+
+where `<surface>` names the audited artifact (e.g. `ledger:<entry-id>`,
+`rules-eager:<file>#<section>`, `skill:<name>`) and `<invariant-hash>` is
+computed **deterministically — never estimated by the model**:
+
+1. **Normalize** the invariant text: trim leading/trailing whitespace,
+   collapse every internal whitespace run to a single space, lowercase.
+2. **Hash** in Bash: `printf '%s' "$normalized" | shasum -a 256 | cut -c1-12`.
+
+The same knowledge item therefore always produces the same key across runs,
+regardless of which session computes it.
+
+Before filing anything, search the tracker for the marker in
+**open AND closed** issues — and key the search on the deterministic
+`<surface>` prefix **first**, using the hash as disambiguation only, so even
+a hash discrepancy can never cause a duplicate for the same surface:
+
+```bash
+gh search issues "[lisa-gardener] key=<surface>" --repo <upstream-or-tracker-repo> # searches open AND closed by default; --state all is NOT a valid gh search flag
+```
+
+plus a body-enumeration fallback for search-index lag (`gh issue list …
+--json number,body` and grep bodies for `[lisa-gardener] key=<surface>`).
+Among prefix hits, compare hashes to distinguish genuinely different
+invariants on the same surface; a prefix hit with a mismatched hash is
+resolved by reading the ticket, never by filing a sibling blind. Then:
+
+- **Open** with the marker → do not re-file; append new evidence as a comment
+  only if it is materially new.
+- **Closed via merged work** → done; a genuine regression later is new
+  evidence and a new ticket.
+- **Closed unmerged / rejected** → the human declined. **Do NOT re-file**
+  unless new evidence **postdates the rejection** — and when re-filing, state
+  the postdating evidence explicitly in the ticket ("rejected <date>; recurred
+  <date> in <ref>"). Closed-as-rejected tickets ARE the gardener's memory of
+  declined recommendations.
+
+Re-runs are quiet no-ops: same surfaces + same evidence ⇒ zero new tickets.
+
+## Autonomous-vs-approval boundary
+
+**Everything is human-gated at v1 — this skill only files tickets.** The
+gardener never edits, writes, or deletes any rule, skill, wiki page, ledger
+entry, lint config, or hook itself; it never merges, transitions, or flips
+anything to `status:ready`; it never bumps `last_confirmed`. Autonomous
+actions are limited to: reading surfaces, gathering evidence, invoking the
+advisory router, and creating/commenting marker-deduped tickets. Humans gate
+by flipping a ticket to `status:ready` (the factory then executes it like any
+work item, honoring the `promotion-contract` rule) or closing it as rejected.
+A future `learnings.autoApply` config may widen this; v1 ships none.
+
+## Escalation
+
+Headless-safe: this skill **never prompts** — it is a cron target. When it
+cannot proceed (tracker unreachable, contradictory config, ledger contract
+error that blocks the parse), it labels its own run ticket — or, when it
+cannot create one, reports in its summary — `status:blocked` + `human-needed`
+with an **operator-readable** reason: what it was trying to do, what it
+observed, and the smallest human action that unblocks it, in plain language a
+non-technical operator standing at the gate can act on.
+
+## Recovery
+
+Every external write is marker-deduped, so a crashed or interrupted run
+leaves no cleanup debt: re-running is the recovery procedure. A partial run's
+already-filed tickets are found by their markers and not duplicated; a batch
+ticket from an interrupted run is reused (append missing rows as a comment)
+rather than reissued. **Filing order**: file the per-item PROMOTE/DEMOTE
+tickets first and the CONFIRM/RETIRE **batch ticket last** — the batch is the
+run's completion signal, so a crash mid-run leaves individually
+marker-recoverable per-item tickets and a missing (not half-filled) batch:
+the most recoverable state. Never attempt to "roll back" filed tickets —
+close-out decisions belong to humans.
+
+## Terminal states
+
+Exactly one per run: **`nothing-needed | candidates-proposed | blocked`**
+
+- `nothing-needed` — no candidate met any recommendation threshold. Healthy.
+  Report one line: surfaces scanned, entries seen, "nothing to propose".
+- `candidates-proposed` — tickets filed. Report each ticket URL, its
+  recommendation (PROMOTE/DEMOTE + rung), and the batch ticket URL with its
+  row count.
+- `blocked` — could not complete; escalated per Escalation with the
+  operator-readable reason.
+
+## Retirement condition
+
+The loop retires itself by the same discipline it applies to everything else,
+and the condition is **stateless — derived from the tracker, never from a
+counter or state file** (there is no durable home for a run counter, and a
+tracker-derived condition is headless- and concurrent-safe by construction).
+Propose retirement when BOTH hold:
+
+1. **Quiet trailing window** — a date-filtered search finds NO
+   `[lisa-gardener]` ticket created in the
+   **trailing six-week window** (six runs at the weekly cadence), e.g.
+   `gh search issues '"[lisa-gardener] key="' --created ">=<six-weeks-ago>"`.
+2. **This run proposes nothing** — the current run's inventory yields zero
+   candidates (it is terminating `nothing-needed`).
+
+When both hold, the gardener files ONE (marker-deduped) ticket proposing to
+lengthen its cadence or tear down its automation (`/tear-down-automations`),
+with the date-filtered search result and this run's summary as evidence. It
+keeps running until a human flips that ticket — retirement is a
+recommendation like any other, never a self-executed exit.
+
+## Scheduling
+
+Register as an **optional** recurring loop through `lisa-setup-automations`
+(the `lisa-auto-<project>-*` naming convention): automation
+`lisa-auto-<project>-learnings-audit`, running `/lisa:learnings:audit`, once
+a **week** (Codex `rrule`: `FREQ=WEEKLY;INTERVAL=1`) — opt-in, created only
+when the operator asks for the gardener loop, unlike the six default
+automations. **Single-scheduled-runner assumption**: register at most ONE
+learnings-audit automation per project. Also runnable on demand — but before
+a manual `/lisa:learnings:audit`, confirm the scheduled automation is not due
+or currently running (check the scheduler's last-run/next-run state) and
+prefer waiting over racing it.
+
+**Concurrency honesty.** Marker dedupe is search-then-write, not an atomic
+claim: two truly concurrent runs can each miss the other's in-flight ticket
+and file a transient duplicate. Dedupe therefore guarantees
+**convergence, not mutual exclusion** — a duplicate is found and closed by
+the next run's marker search (or by the human triaging the pair), and because
+rejection memory keys on the surface prefix, a duplicate never multiplies.
+This is an accepted trade-off for a weekly advisory loop; a tracker-side
+locking protocol would be disproportionate to the risk.
+
+## Rules
+
+- Tracker-only output: no file edits, no PRs, no label flips beyond the
+  gardener's own run-ticket escalation labels.
+- Evidence or nothing: every recommendation cites concrete refs; RETIRE
+  requires proof of redundancy/staleness, not vibes.
+- One batch ticket per run, at most `max_candidates` per-item tickets.
+- All ticket writes via `lisa-tracker-write` (or `gh` for the upstream repo,
+  per the rework-triage upstream procedure) — never raw unvalidated creation.
+- Never classify without the router, never file without the dedupe search,
+  never re-file over a rejection without postdating evidence.
+- No learning loops about learning: the exclusion registry is absolute.

package/plugins/lisa/.codex-plugin/skills/lisa-learnings-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Learnings Audit"
+short_description: "The gardener of the learnings…"
+default_prompt:
+  - "Use $lisa-learnings-audit: The gardener of the learnings…."

package/plugins/lisa/.codex-plugin/skills/lisa-parity-skill-creator/SKILL.md

@@ -32,7 +32,9 @@ reimplement a semver-versioned upstream plugin.
 
 If the knowledge is narrow or one-off, prefer a rule in `.claude/rules/` instead
 — skills are for broad, repeatable capabilities. When unsure whether content
-warrants a skill, run it past the `skill-evaluator` agent first.
+warrants a skill, run it past the `skill-evaluator` agent first — it is the
+six-rung ladder router, a skill is only one rung, and it may recommend a
+cheaper or stronger destination instead.
 
 ## Where skills live
 

package/plugins/lisa/.codex-plugin/skills/lisa-persist-learning/SKILL.md

@@ -39,7 +39,7 @@ FP="sll4-$(printf '%s\n%s' "$NORM" "$TRIGGERING_ISSUE" | shasum -a 1 | cut -c1-1
 
 ## 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 `learner` uses for `skill-evaluator`) with the full candidate including the fingerprint. It returns a verdict: `classification`, `cited_evidence[]`, `rationale`, `confidence` (durable only), `disposition`.
+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`.
 

package/plugins/lisa/.codex-plugin/skills/lisa-rework-triage/SKILL.md

@@ -115,16 +115,33 @@ Upstream issues target the Lisa repository itself so the harness gets fixed for
 project at once. Resolve the repo from `.lisa.config.json` `hardening.upstreamRepo`;
 default `CodySwannGT/lisa`.
 
+There are **two upstream lanes**, distinguished by what the filing proposes. Both share
+the same dedupe-marker and evidence-chain discipline below; only the label and one body
+section differ:
+
+| Lane | Label | When | Extra body section |
+|------|-------|------|--------------------|
+| Defect | `self-hardening` | A Lisa gate/skill/template did something wrong — a harness bug the kernel must fix. | none |
+| Contribution | `template-candidate` | A generalizable pattern discovered downstream that would benefit every host project — not a defect, a proposed improvement to Lisa's templates/rules/skills. | `## Proposed template change` |
+
 1. **Dedupe first.** `gh issue list -R <upstream> --state open --search "<fingerprint terms>"`
-   — if an open issue already covers this failure class, comment the new occurrence on it
-   (evidence compounds; duplicates dilute) and link it instead of filing.
-2. **File with the same bar as any ticket:** a three-audience description (what failed for
-   the operator, what the harness did wrong, what to change), the verbatim evidence chain
-   (PRD text → ticket AC → QA failure → gate that passed it), and a `self-hardening` label:
-   `gh issue create -R <upstream> --title "<gate/skill>: <failure class>" --label self-hardening`.
+   — if an open issue already covers this failure class or pattern, comment the new
+   occurrence on it (evidence compounds; duplicates dilute) and link it instead of filing.
+2. **File with the same bar as any ticket:** a three-audience description (what failed or
+   improved for the operator, what the harness did or could do, what to change), the
+   verbatim evidence chain (PRD text → ticket AC → QA failure → gate that passed it; for
+   patterns, the downstream occurrences proving generality), and the lane's label:
+   `gh issue create -R <upstream> --title "<gate/skill>: <failure class>" --label self-hardening`
+   for defects, or
+   `gh issue create -R <upstream> --title "<template surface>: <pattern>" --label template-candidate`
+   for contributions. A `template-candidate` filing MUST include a
+   `## Proposed template change` section naming the Lisa template/rule/skill surface to
+   change (e.g. `typescript/package-lisa/package.lisa.json`, a `plugins/src/base` rule)
+   and the proposed content or diff sketch, so Lisa-side intake can triage it as a
+   contribution rather than a defect.
 3. **Close the loop.** Reference the upstream issue URL in the triage comment. The upstream
-   repo's own build intake implements it; the next kernel release ships the hardening to
-   every host project.
+   repo's own build intake implements it; the next kernel release ships the hardening (or
+   the generalized pattern) to every host project.
 
 ## Verdict
 

package/plugins/lisa/.codex-plugin/skills/lisa-setup-automations/SKILL.md

@@ -38,10 +38,16 @@ create them; invoke the runtime's automation tool with the spec below.
   automation. `true` → filed bug/usability tickets are created build-ready (auto-picked-up by ticket
   intake); `false` → created in the backlog for human triage.
 
+- `learnings-audit` (default **false**) — opt-in: when `true`, additionally create the weekly
+  `lisa-auto-<project>-learnings-audit` automation running `/lisa:learnings:audit` (the gardener —
+  see "Optional automation" below). Default `false` because the gardener's output is human-gated
+  tracker tickets: a project opts into the recurring audit stream deliberately rather than
+  receiving recommendation tickets by surprise.
+
 The defaults are autonomous by design — the factory model wants inputs flowing through the gates
 without a human between the loops and the pipeline. Pass `false` explicitly to opt a project into
-human triage. The two flags affect **only** the two exploratory automations; the intake gates'
-adversarial validation remains the quality control either way.
+human triage. The two auto-start flags affect **only** the two exploratory automations; the intake
+gates' adversarial validation remains the quality control either way.
 
 ## The automations to create
 
@@ -67,7 +73,21 @@ report the exact conflicting path(s).
 | **monitor** | `/lisa:monitor` | **once a day** |
 
 For a Codex `rrule`: every 60 min → `FREQ=HOURLY;INTERVAL=1`; every 10 min →
-`FREQ=MINUTELY;INTERVAL=10`; once a day → `FREQ=DAILY;INTERVAL=1`.
+`FREQ=MINUTELY;INTERVAL=10`; once a day → `FREQ=DAILY;INTERVAL=1`; once a week →
+`FREQ=WEEKLY;INTERVAL=1`.
+
+**Optional automation — the gardener.** When the operator opts in
+(`learnings-audit=true`; default **false** — this one is opt-in, unlike the six
+defaults above), additionally create `lisa-auto-<project>-learnings-audit`
+running `/lisa:learnings:audit` once a **week**. It audits the project's
+knowledge surfaces (learnings ledger, rules trees, skills, wiki) and files
+human-gated promote/demote/confirm/retire tickets per the
+`lisa-learnings-audit` skill. Register at most ONE learnings-audit automation
+per project — the gardener's marker dedupe assumes a single scheduled runner
+and guarantees convergence (a transient duplicate from a concurrent run is
+closed by the next run's dedupe or the human), not mutual exclusion; manual
+runs should first confirm the cron is not due or running. Tear-down removes
+it with the rest of the `lisa-auto-<project>-*` set.
 
 **Exploratory PRD pressure gate.** `auto-start-prds=true` means "create PRDs in the ready PRD
 lifecycle when the PRD queue has capacity," not "always create a new ready PRD." The

package/plugins/lisa/agents/learning-judge.md

@@ -16,7 +16,7 @@ You are the quality bar between a claimed learning and the project learnings sur
 - Dropping is a valid, successful outcome — not a failure of the gate.
 - You judge the **truth and durability** of a claimed learning, not its plausibility. Plausibility without evidence is a drop.
 
-This gate is independent of (and composes with) `skill-evaluator`: that agent judges whether knowledge is skill-worthy; this agent judges whether a claimed learning is true, caused the failure, and will recur. Callers must respect your verdict — the same contract `learner` holds with `skill-evaluator`: do not override it.
+This gate is independent of (and composes with) the `skill-evaluator` ladder router: the router recommends the promotion destination — which rung of the ladder a presumed-valid learning should live on — feeding the gardener's human-gated tickets; this agent judges whether a claimed learning is true, caused the failure, and will recur. Callers must respect your verdict — do not override it.
 
 ## Candidate Input Schema