@codyswann/lisa 2.246.0 → 2.247.0

package/plugins/src/base/rules/eager/promotion-contract.md

@@ -0,0 +1,18 @@
+# Promotion Contract (load-bearing)
+
+When implementing a learnings-ladder **promotion ticket** — turning prose
+knowledge into an executable control (lint / ast-grep / type / test / hook /
+`package.lisa.json` force) — the change must be **atomic**: one PR that
+**enables the control**, **fixes the existing violation population**, **ships a
+remediation-teaching diagnostic** (violated invariant + why + concrete fix),
+and **deletes the superseded prose**. A PR missing any of the four is
+**rejected by rule** — promote-without-remove double-pays forever;
+remove-without-diagnostic strands agents.
+
+Eager-tier admission is **demotion-biased** and earned only by repeated-miss
+evidence; the gardener audits the eager tier every run, including Lisa's own
+shipped eager rules.
+
+Full contract, diagnostic-quality bar, and the AC template the gardener embeds
+in EXECUTABLE-CONTROL promotion tickets:
+[reference/promotion-contract.md](../reference/promotion-contract.md).

package/plugins/src/base/rules/reference/promotion-contract.md

@@ -0,0 +1,126 @@
+# Promotion Contract
+
+When a learnings-ladder promotion ticket (PRD #1729) is implemented — turning a
+prose learning, rule section, or ledger entry into an **executable control**
+(lint, ast-grep, type constraint, test, hook, or `package.lisa.json` force) —
+the implementing PR is governed by this contract. The gardener
+(`lisa-learnings-audit`) files the tickets; a human gates them by flipping
+`status:ready`; the factory implements them like any other work item. This rule
+is what makes the resulting PR reviewable **by rule, not by reviewer taste**.
+
+## The atomic promote-and-delete contract
+
+A promotion PR must do **all four** of the following, in **one atomic PR**:
+
+1. **Enable the control.** The lint rule, ast-grep pattern, type constraint,
+   test, hook, or `package.lisa.json` force entry is active and blocking (CI
+   and/or local gates), not merely added in a warn-only or disabled state.
+2. **Fix the existing violation population.** Every current violation of the
+   new control in the repository is migrated in the same PR, so the control
+   lands green. Enabling a control against a red population either blocks all
+   unrelated work or forces a blanket ignore — both defeat the promotion.
+3. **Ship a remediation-teaching diagnostic.** The control's failure message
+   meets the diagnostic-quality bar below. The prose being deleted is not
+   lost — its content is **relocated into the error message**, so the agent
+   that trips the control learns the rule at exactly the moment it matters.
+4. **Delete the superseded prose.** The ledger entry, rules-file section,
+   memory note, or wiki duplication that the control replaces is removed in
+   the same PR. Keeping both means every session keeps paying context tax for
+   knowledge the machine already enforces.
+
+**A PR missing any of the four is rejected by rule.** Reviewers (human, bot,
+or verification lifecycle) cite this contract and reject — no case-by-case
+judgment call is needed. The failure modes are structural, not stylistic:
+
+- **Promote-without-remove double-pays forever**: the control enforces the
+  invariant while the prose keeps taxing every session, and the two drift
+  apart over time.
+- **Remove-without-diagnostic strands agents**: the prose is gone, the control
+  fires, and the violator has no idea what invariant it tripped or how to
+  repair it.
+- **Enable-without-population-fix** reds the build for everyone or breeds
+  blanket ignores that hollow the control out.
+
+The same atomicity applies in reverse to **retirements** the gardener batches:
+a prose deletion whose invariant is claimed to be mechanically owned must cite
+the owning control (rule name, config location) in the deleting PR.
+
+## The diagnostic-quality bar
+
+The error message must **teach the repair**, because it is the only surface
+the violating agent will see. Every promoted control's diagnostic states:
+
+1. **The violated invariant** — what rule was broken, named precisely.
+2. **Why the invariant holds** — the causal story that used to live in the
+   prose (the incident, the failure class, the platform behavior).
+3. **The concrete fix** — what to change, ideally with the typical corrected
+   form inline.
+
+Example shape (from this repo's own lint conventions):
+
+> "Direct `process.env` access is forbidden. Config values bypass validation
+> and typing when read ad hoc (past incidents: silent `undefined` in Lambda
+> cold starts). Use the config module: `getStandaloneConfig().myValue`."
+
+A diagnostic that merely restates the rule name ("no-direct-env: direct env
+access is not allowed") fails the bar and fails the promotion PR with it.
+
+## Eager-tier admission policy (demotion-biased)
+
+The eager rules tier (auto-loaded rules trees) charges **every session,
+unconditionally**. Admission is therefore **earned, never defaulted**:
+
+- A rule enters (or stays in) the eager tier only on cited **repeated-miss
+  evidence** — the knowledge was already retrievable (ledger, wiki, skill,
+  reference body) and agents still failed repeatedly because they did not
+  know to look. Absent that evidence, the content belongs on a cheaper rung.
+- The policy is **demotion-biased**: when in doubt, move down the ladder.
+  A wrongly demoted rule earns its way back with fresh failure evidence; a
+  wrongly admitted rule taxes every session until someone notices.
+- The gardener audits the eager tier **every run** — and that audit includes
+  **Lisa's own shipped eager rules**, not just host-project additions. No
+  rule is grandfathered; kernel rules demonstrating no repeated-miss evidence
+  get demotion tickets like any other candidate, filed upstream
+  (`template-candidate` or `self-hardening` lane as applicable).
+
+## AC template for EXECUTABLE-CONTROL promotion tickets
+
+The gardener embeds the following snippet **verbatim** (markers included) into
+the acceptance criteria of every EXECUTABLE-CONTROL promotion ticket, so
+implementing agents receive the contract inside the work item itself:
+
+<!-- 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 -->
+
+Do not paraphrase, reorder, or partially quote the snippet when embedding it —
+verbatim embedding is what keeps the contract identical across every ticket
+and lets reviewers diff against a single source of truth.
+
+## Who consumes this rule
+
+- **Implementing agents** working a promotion ticket: structure the PR around
+  the four legs before writing code.
+- **Review flows** (human, CodeRabbit, `lisa-pull-request-review`,
+  verification lifecycle): reject a promotion PR missing any leg, citing this
+  rule.
+- **The gardener** (`lisa-learnings-audit`): embeds the AC template above into
+  EXECUTABLE-CONTROL promotion tickets and applies the eager-tier admission
+  policy when auditing.
+- **PROJECT_RULES.md owners**: that file is human-authored only; machine
+  writes go to the learnings ledger, and promotions out of it arrive as
+  gardener tickets governed by this contract.

package/plugins/src/base/skills/lisa-learnings-audit/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: lisa-learnings-audit
+description: "The gardener of the learnings ladder (PRD #1729). Periodically audits every knowledge surface — ledger, rules trees (including Lisa's own shipped eager rules), skills, wiki index, and mechanical-control surfaces — gathers evidence per item (recurrence, staleness, redundancy, contradiction, budget pressure), classifies each candidate through the ladder router (skill-evaluator, advisory), and communicates exclusively through the tracker: one evidence-bearing ticket per PROMOTE/DEMOTE, one batch ticket per run for CONFIRM/RETIRE, upstream Lisa issues for upstream-scoped patterns. Everything is human-gated at v1 — the skill only files tickets; humans gate by flipping status:ready or closing as rejected, and rejections are remembered. Cron-able via lisa-setup-automations and runnable on demand via /lisa:learnings:audit."
+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/src/base/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/src/base/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/src/base/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/src/base/skills/lisa-setup-automations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-setup-automations
-description: "Set up the recurring Lisa automations on the local workstation using the CURRENT runtime's native scheduler — Codex automations (the native automations / automation_update mechanism) or, on Claude, /schedule. This skill is a declarative specification: it states WHICH automations to create, how often, and with which parameters; it does not template schedule files or run scheduling code itself — the runtime's native automation mechanism does the creating. Creates six automations: intake-repair (every 60 min), intake PRD (every 60 min), intake tickets (every 10 min), exploratory-bugs (once a day), exploratory-prds (once a day), monitor (once a day). Two flags — auto-start-prds and auto-start-tickets — control whether the ideated PRDs / filed bug tickets are created auto-pickup-ready (prd_ready / ready, default true) or left for human review. Tear down with /tear-down-automations."
+description: "Set up the recurring Lisa automations on the local workstation using the CURRENT runtime's native scheduler — Codex automations (the native automations / automation_update mechanism) or, on Claude, /schedule. This skill is a declarative specification: it states WHICH automations to create, how often, and with which parameters; it does not template schedule files or run scheduling code itself — the runtime's native automation mechanism does the creating. Creates six default automations: intake-repair (every 60 min), intake PRD (every 60 min), intake tickets (every 10 min), exploratory-bugs (once a day), exploratory-prds (once a day), monitor (once a day) — plus opt-in learnings-audit (once a week, the gardener). Three flags: auto-start-prds and auto-start-tickets control whether ideated PRDs / filed bug tickets are created auto-pickup-ready (prd_ready / ready, default true) or left for human review; learnings-audit (default false) opts into the weekly gardener loop. Tear down with /tear-down-automations."
 allowed-tools: ["Skill", "Bash", "Read"]
 ---
 
@@ -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