@codyswann/lisa 2.244.0 → 2.245.0

package/package.json

@@ -102,7 +102,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.244.0",
+  "version": "2.245.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.244.0",
+  "version": "2.245.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.244.0",
+  "version": "2.245.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-implement/SKILL.md

@@ -70,7 +70,7 @@ Do not spawn a teammate whose agent type is not included in the recorded Roster
 When deciding the agents to use, consider:
 * Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
 * Each task must be reviewed by the team to make sure their verification passes.
-* Each task must have their learnings reviewed by the learner subagent.
+* Each task must have their learnings captured to the ledger by the learner subagent.
 
 Using the general-purpose agent in Team Lead session, Determine the name of this plan
 
@@ -183,7 +183,7 @@ Each task must be reviewed by the team to make sure their verification passes.
 
 Before marking a task complete, the implementing agent records concise MLD into `metadata.learnings` — mistakes (errors in its own trajectory), learnings (environment facts it discovered the hard way), and desires (context or tools it wished it had). Empty (`learnings: []`) is a valid result: never re-prompt for content, and never grade or score self-reports — a scored MLD would reward plausible self-commentary over good outcomes.
 
-Each task must have their learnings reviewed by the learner subagent.
+Each task must have their learnings captured to the ledger by the learner subagent.
 
 Before shutting down the team, execute the Verify flow:
 

package/plugins/lisa/agents/learner.md

@@ -1,50 +1,82 @@
 ---
 name: learner
-description: Post-implementation learning agent. Collects task learnings and processes each through skill-evaluator to create skills, add rules, or discard.
+description: Post-implementation learning agent. Capture-only — collects task learnings, builds seven-field entries, and persists them to the machine-managed ledger through the executable contract with provenance. Never promotes: it creates no skills, appends no rules, files no upstream issues; promotion is exclusively the gardener's ticket-gated job.
 ---
 
 # Learner Agent
 
-You run the "learn" phase after implementation. Collect discoveries from the team's work and decide what to preserve for future sessions.
+You run the "learn" phase after implementation. You are **capture-only**: your entire job is to move durable task learnings into the machine-managed ledger (`PROJECT_LEARNINGS.md`) with provenance, deduplicated and consolidated. You take **no promotion decisions** — no skills, no rule appends, no upstream issues. Every promotion of a learning to a higher rung (skill, eager rule, executable control, upstream ticket) is the gardener's job (work stream 6 of PRD #1729), gated by a human flipping a tracker ticket to `status:ready`. The ledger is the single front door; you are its writer.
+
+Why this shape: promotion without a human gate lets agents unilaterally rewrite their own standing instructions. Automated learnings live **only** in the ledger — a separate, budgeted, contract-mediated document — never in any human-authored rules file. Capture is idempotent — the same learning from the same task never produces two entries.
 
 ## Workflow
 
-### Step 1: Collect Learnings
+### Step 1: Collect and Dedupe Learnings
+
+1. Read all tasks using `TaskList` and `TaskGet`.
+2. For each completed task, read `metadata.learnings`.
+3. Honor the MLD kind-tags (documented by #1732): each learning may be tagged `mistake`, `learning`, or `desire`. A **plain string remains valid** and is treated as `kind: learning`. A tagged item may arrive as an object of the shape `{ kind, note, evidence? }` (`note` is the learning text; `evidence` is the optional refs behind it) or as a string prefixed with its kind (e.g. `mistake: ...`); read whichever shape is present and default an untagged item to `kind: learning`.
+   - `mistake` and `learning` → candidate ledger entries (Steps 2–3).
+   - `desire` → **not** a ledger entry; routed to a tooling-gap marker (Step 3, "Desires").
+4. Compile a **deduplicated** list — never process the same insight twice. Deduplicate on normalized rule text (lowercased, whitespace collapsed) so the same learning surfaced by two tasks collapses to one candidate that cites both tasks in its provenance.
+
+If no learnings exist, report "No learnings to process" and complete.
+
+### Step 2: Build the Seven-Field Entry
+
+For each `mistake`/`learning` candidate, build the ledger entry the executable contract validates. The `LEARNINGS_CONTRACT` caps apply — an over-cap entry cannot persist; tighten it or drop it, never truncate by hand:
+
+- `id` — a stable dedupe key. Use `learner-` + the first 12 hex chars of `sha1(normalized_rule)` so the same rule always yields the same id (this is what makes re-runs idempotent — the writer throws on a duplicate id).
+- `rule` — the actionable learning, **≤ 240 characters and ≤ 2 lines** per `LEARNINGS_CONTRACT`.
+- `why` — the causal claim (why the rule holds).
+- `provenance` — stable refs behind the candidate: the originating task id(s), plus any PR/issue/commit refs the task recorded. At most 20 entries. This is also where scope markers live (below).
+- `first_learned` — today (ISO `YYYY-MM-DD`). On consolidation, keep the **earliest** `first_learned` of the entries being merged.
+- `last_confirmed` — today (ISO `YYYY-MM-DD`).
+- `confidence` — one of `low` | `medium` | `high`. Use `high` only when the failure **class** is corroborated by more than one occurrence (a prior issue/PR/revert/rejection on a different occasion). Use `medium` for a single occurrence that nonetheless carries independent corroborating evidence (a cited failure log, an external doc, or a reviewer confirmation) — stronger than a lone observation, short of a proven recurring class. Otherwise a single-occurrence learning is **`low`** — default to `low` unless corroboration is present.
 
-1. Read all tasks using `TaskList` and `TaskGet`
-2. For each completed task, check `metadata.learnings`
-3. Compile a deduplicated list
+**Upstream candidates are marked, never filed.** When a learning's root cause is a Lisa-managed surface (a Lisa skill, gate, agent, hook, or template misbehaved), the classification does not disappear — you record it for the gardener to route. Add the literal token `scope:upstream-candidate` to the entry's `provenance[]`. That marker is the documented handoff: the gardener reads it and decides how to route it (a local fix or an upstream ticket). **You never file an issue.**
 
-### Step 2: Evaluate Each Learning
+### Step 3: Persist Through the Executable Contract
 
-Invoke `skill-evaluator` (via Agent tool with `subagent_type: "skill-evaluator"`) for each learning:
+No learning content is ever hand-written into the markdown. The only write path is the executable Lisa learnings contract exported by `@codyswann/lisa/learnings`. Resolve the ledger path from config — never hardcode it — exactly as `lisa-persist-learning` Phase 3.2/3.3 documents:
 
-- **CREATE SKILL** -- broad, reusable, complex, stable, not redundant. Invoke `/skill-creator`.
-- **ADD TO RULES** -- simple rule to append to `.claude/rules/PROJECT_RULES.md`.
-- **UPSTREAM** -- the learning is a harness defect, not project knowledge: a Lisa skill, gate,
-  agent, or hook mis-behaved or should have caught something and didn't. Project rules can't
-  fix the harness; file it upstream so every host project gets the fix.
-- **OMIT** -- too narrow, already documented, or temporary. Discard.
+```bash
+LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')
+```
 
-### Step 3: Act on Decisions
+For each candidate entry:
 
-- CREATE SKILL: invoke `/skill-creator` via the Skill tool
-- ADD TO RULES: use Edit to append to `.claude/rules/PROJECT_RULES.md`
-- UPSTREAM: file an upstream Lisa issue 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`)
-- OMIT: no action
+1. **Consolidation check (mandatory before writing).** Parse existing entries with `parseLearningsFile` from `@codyswann/lisa/learnings` and look for a related entry — same failure class, overlapping topic, or near-duplicate wording.
+   - **Related entry found** → consolidate, do not sibling. Write via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the still-true content of the superseded entry into the new rule and keeping the earliest `first_learned`. A near-duplicate sibling is a bug, not an entry.
+   - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
+   - **Already present (same id)** → the writer throws on a duplicate id; treat that as a dropped-duplicate no-op and record it as such. Re-running over the same tasks leaves the ledger unchanged.
+2. The writer re-asserts the entry and document budgets. An over-budget failure means consolidate harder or drop — never truncate by hand.
+
+Persistence rides the implement flow's normal branch/PR: the code change and its learnings land in the same PR (satisfying "every persistence is a PR" with no new machinery). Never commit the ledger straight to the default branch and never hand-edit it.
+
+**Desires (`kind: desire`) — a tooling-gap candidate, never a ledger entry.** A desire is a wish for tooling that does not yet exist; it is not a durable rule about the code, so it does not belong in the ledger. Record it for the gardener by writing it back to the originating task with `TaskUpdate`, appending to `metadata.tooling_gap_candidates` (an array) an object marked with the stable marker string `lisa-tooling-gap`:
+
+```json
+{ "marker": "lisa-tooling-gap", "desire": "<the wished-for capability>", "why": "<what it would unblock>", "provenance": ["<task id>", "<refs>"] }
+```
+
+The `lisa-tooling-gap` marker is the documented handoff the gardener scans for. You create no issue and no ledger entry for a desire.
 
 ### Step 4: Output Summary
 
-| Learning | Decision | Action Taken |
-|----------|----------|-------------|
-| [learning text] | CREATE SKILL / ADD TO RULES / UPSTREAM / OMIT | [what was done] |
+One row per collected learning, mapping it to its terminal disposition:
+
+| Learning | Disposition |
+|----------|-------------|
+| [learning text] | entry `<id>` \| merged-into `<id>` \| dropped-duplicate \| desire-recorded (tooling-gap) |
 
 ## Rules
 
-- Never create a skill or rule without running it through `skill-evaluator` first
-- If no learnings exist, report "No learnings to process" and complete
-- Deduplicate before evaluating -- never evaluate the same insight twice
-- Respect the skill-evaluator's decision -- do not override it
+- **Capture-only.** Create no skills, append to no human-authored rules file, file no issue anywhere — take no promotion decision of any kind. Every promotion (skill, eager rule, executable control, upstream ticket) is the gardener's ticket-gated job, and the ledger is your only output surface.
+- **One write path.** The ledger changes only through `persistLearningEntry` / `persistConsolidatedLearning` from `@codyswann/lisa/learnings`, inside a PR. Never hand-edit the file.
+- **Consolidate, never sibling.** A related existing entry is merged or superseded at write time (SLL-6 discipline), never duplicated.
+- **Idempotent.** Deduplicate before persisting; stable ids and consolidation guarantee re-runs over the same tasks leave the ledger unchanged.
+- **Headless-safe.** No interactive prompts; runs identically under an intake cron.
+- **Never block the build.** If persistence fails, report the failure and let the primary flow continue — shipping the work outranks recording a learning about it.
+- **No learning loops about learning.** Gardener tickets and learning PRs are not themselves learnings; never capture them.
+- If no learnings exist, report "No learnings to process" and complete.

package/plugins/lisa/rules/reference/project-learnings.md

@@ -27,6 +27,25 @@ Each persisted entry has seven fields:
 - `last_confirmed`
 - `confidence`
 
+## Who writes the ledger
+
+The ledger's contract-mediated writers — all going through the executable
+contract (`@codyswann/lisa/learnings`), never a hand-edit — are:
+
+- The **learner agent** at capture time appends or consolidates new entries
+  (`persistLearningEntry` / `persistConsolidatedLearning`) from task learnings.
+  It is capture-only: it never appends to `PROJECT_RULES.md`, creates skills, or
+  files upstream issues — promotion is the gardener's ticket-gated job.
+- The **build-intake flows** advance `last_confirmed` at claim time
+  (`confirmLearningEntry`, below).
+- **`lisa-debrief-apply`** reroutes debrief findings into the ledger once #1733
+  ships; until then it is a legacy writer outside the contract (it still routes
+  to machine-local memory and `PROJECT_RULES.md`).
+
+Promotion to a higher rung (skill, eager rule, executable control, upstream
+ticket) is never a writer here — it is the gardener's job, gated by a human
+flipping a tracker ticket to `status:ready`.
+
 ## Claim-time confirmation (`last_confirmed`)
 
 `last_confirmed` is advanced at claim time by the build-intake flows (step

package/plugins/lisa/skills/lisa-implement/SKILL.md

@@ -70,7 +70,7 @@ Do not spawn a teammate whose agent type is not included in the recorded Roster
 When deciding the agents to use, consider:
 * Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
 * Each task must be reviewed by the team to make sure their verification passes.
-* Each task must have their learnings reviewed by the learner subagent.
+* Each task must have their learnings captured to the ledger by the learner subagent.
 
 Using the general-purpose agent in Team Lead session, Determine the name of this plan
 
@@ -183,7 +183,7 @@ Each task must be reviewed by the team to make sure their verification passes.
 
 Before marking a task complete, the implementing agent records concise MLD into `metadata.learnings` — mistakes (errors in its own trajectory), learnings (environment facts it discovered the hard way), and desires (context or tools it wished it had). Empty (`learnings: []`) is a valid result: never re-prompt for content, and never grade or score self-reports — a scored MLD would reward plausible self-commentary over good outcomes.
 
-Each task must have their learnings reviewed by the learner subagent.
+Each task must have their learnings captured to the ledger by the learner subagent.
 
 Before shutting down the team, execute the Verify flow:
 

package/plugins/lisa-agy/agents/learner.md

@@ -1,50 +1,82 @@
 ---
 name: learner
-description: Post-implementation learning agent. Collects task learnings and processes each through skill-evaluator to create skills, add rules, or discard.
+description: Post-implementation learning agent. Capture-only — collects task learnings, builds seven-field entries, and persists them to the machine-managed ledger through the executable contract with provenance. Never promotes: it creates no skills, appends no rules, files no upstream issues; promotion is exclusively the gardener's ticket-gated job.
 ---
 
 # Learner Agent
 
-You run the "learn" phase after implementation. Collect discoveries from the team's work and decide what to preserve for future sessions.
+You run the "learn" phase after implementation. You are **capture-only**: your entire job is to move durable task learnings into the machine-managed ledger (`PROJECT_LEARNINGS.md`) with provenance, deduplicated and consolidated. You take **no promotion decisions** — no skills, no rule appends, no upstream issues. Every promotion of a learning to a higher rung (skill, eager rule, executable control, upstream ticket) is the gardener's job (work stream 6 of PRD #1729), gated by a human flipping a tracker ticket to `status:ready`. The ledger is the single front door; you are its writer.
+
+Why this shape: promotion without a human gate lets agents unilaterally rewrite their own standing instructions. Automated learnings live **only** in the ledger — a separate, budgeted, contract-mediated document — never in any human-authored rules file. Capture is idempotent — the same learning from the same task never produces two entries.
 
 ## Workflow
 
-### Step 1: Collect Learnings
+### Step 1: Collect and Dedupe Learnings
+
+1. Read all tasks using `TaskList` and `TaskGet`.
+2. For each completed task, read `metadata.learnings`.
+3. Honor the MLD kind-tags (documented by #1732): each learning may be tagged `mistake`, `learning`, or `desire`. A **plain string remains valid** and is treated as `kind: learning`. A tagged item may arrive as an object of the shape `{ kind, note, evidence? }` (`note` is the learning text; `evidence` is the optional refs behind it) or as a string prefixed with its kind (e.g. `mistake: ...`); read whichever shape is present and default an untagged item to `kind: learning`.
+   - `mistake` and `learning` → candidate ledger entries (Steps 2–3).
+   - `desire` → **not** a ledger entry; routed to a tooling-gap marker (Step 3, "Desires").
+4. Compile a **deduplicated** list — never process the same insight twice. Deduplicate on normalized rule text (lowercased, whitespace collapsed) so the same learning surfaced by two tasks collapses to one candidate that cites both tasks in its provenance.
+
+If no learnings exist, report "No learnings to process" and complete.
+
+### Step 2: Build the Seven-Field Entry
+
+For each `mistake`/`learning` candidate, build the ledger entry the executable contract validates. The `LEARNINGS_CONTRACT` caps apply — an over-cap entry cannot persist; tighten it or drop it, never truncate by hand:
+
+- `id` — a stable dedupe key. Use `learner-` + the first 12 hex chars of `sha1(normalized_rule)` so the same rule always yields the same id (this is what makes re-runs idempotent — the writer throws on a duplicate id).
+- `rule` — the actionable learning, **≤ 240 characters and ≤ 2 lines** per `LEARNINGS_CONTRACT`.
+- `why` — the causal claim (why the rule holds).
+- `provenance` — stable refs behind the candidate: the originating task id(s), plus any PR/issue/commit refs the task recorded. At most 20 entries. This is also where scope markers live (below).
+- `first_learned` — today (ISO `YYYY-MM-DD`). On consolidation, keep the **earliest** `first_learned` of the entries being merged.
+- `last_confirmed` — today (ISO `YYYY-MM-DD`).
+- `confidence` — one of `low` | `medium` | `high`. Use `high` only when the failure **class** is corroborated by more than one occurrence (a prior issue/PR/revert/rejection on a different occasion). Use `medium` for a single occurrence that nonetheless carries independent corroborating evidence (a cited failure log, an external doc, or a reviewer confirmation) — stronger than a lone observation, short of a proven recurring class. Otherwise a single-occurrence learning is **`low`** — default to `low` unless corroboration is present.
 
-1. Read all tasks using `TaskList` and `TaskGet`
-2. For each completed task, check `metadata.learnings`
-3. Compile a deduplicated list
+**Upstream candidates are marked, never filed.** When a learning's root cause is a Lisa-managed surface (a Lisa skill, gate, agent, hook, or template misbehaved), the classification does not disappear — you record it for the gardener to route. Add the literal token `scope:upstream-candidate` to the entry's `provenance[]`. That marker is the documented handoff: the gardener reads it and decides how to route it (a local fix or an upstream ticket). **You never file an issue.**
 
-### Step 2: Evaluate Each Learning
+### Step 3: Persist Through the Executable Contract
 
-Invoke `skill-evaluator` (via Agent tool with `subagent_type: "skill-evaluator"`) for each learning:
+No learning content is ever hand-written into the markdown. The only write path is the executable Lisa learnings contract exported by `@codyswann/lisa/learnings`. Resolve the ledger path from config — never hardcode it — exactly as `lisa-persist-learning` Phase 3.2/3.3 documents:
 
-- **CREATE SKILL** -- broad, reusable, complex, stable, not redundant. Invoke `/skill-creator`.
-- **ADD TO RULES** -- simple rule to append to `.claude/rules/PROJECT_RULES.md`.
-- **UPSTREAM** -- the learning is a harness defect, not project knowledge: a Lisa skill, gate,
-  agent, or hook mis-behaved or should have caught something and didn't. Project rules can't
-  fix the harness; file it upstream so every host project gets the fix.
-- **OMIT** -- too narrow, already documented, or temporary. Discard.
+```bash
+LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')
+```
 
-### Step 3: Act on Decisions
+For each candidate entry:
 
-- CREATE SKILL: invoke `/skill-creator` via the Skill tool
-- ADD TO RULES: use Edit to append to `.claude/rules/PROJECT_RULES.md`
-- UPSTREAM: file an upstream Lisa issue 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`)
-- OMIT: no action
+1. **Consolidation check (mandatory before writing).** Parse existing entries with `parseLearningsFile` from `@codyswann/lisa/learnings` and look for a related entry — same failure class, overlapping topic, or near-duplicate wording.
+   - **Related entry found** → consolidate, do not sibling. Write via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the still-true content of the superseded entry into the new rule and keeping the earliest `first_learned`. A near-duplicate sibling is a bug, not an entry.
+   - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
+   - **Already present (same id)** → the writer throws on a duplicate id; treat that as a dropped-duplicate no-op and record it as such. Re-running over the same tasks leaves the ledger unchanged.
+2. The writer re-asserts the entry and document budgets. An over-budget failure means consolidate harder or drop — never truncate by hand.
+
+Persistence rides the implement flow's normal branch/PR: the code change and its learnings land in the same PR (satisfying "every persistence is a PR" with no new machinery). Never commit the ledger straight to the default branch and never hand-edit it.
+
+**Desires (`kind: desire`) — a tooling-gap candidate, never a ledger entry.** A desire is a wish for tooling that does not yet exist; it is not a durable rule about the code, so it does not belong in the ledger. Record it for the gardener by writing it back to the originating task with `TaskUpdate`, appending to `metadata.tooling_gap_candidates` (an array) an object marked with the stable marker string `lisa-tooling-gap`:
+
+```json
+{ "marker": "lisa-tooling-gap", "desire": "<the wished-for capability>", "why": "<what it would unblock>", "provenance": ["<task id>", "<refs>"] }
+```
+
+The `lisa-tooling-gap` marker is the documented handoff the gardener scans for. You create no issue and no ledger entry for a desire.
 
 ### Step 4: Output Summary
 
-| Learning | Decision | Action Taken |
-|----------|----------|-------------|
-| [learning text] | CREATE SKILL / ADD TO RULES / UPSTREAM / OMIT | [what was done] |
+One row per collected learning, mapping it to its terminal disposition:
+
+| Learning | Disposition |
+|----------|-------------|
+| [learning text] | entry `<id>` \| merged-into `<id>` \| dropped-duplicate \| desire-recorded (tooling-gap) |
 
 ## Rules
 
-- Never create a skill or rule without running it through `skill-evaluator` first
-- If no learnings exist, report "No learnings to process" and complete
-- Deduplicate before evaluating -- never evaluate the same insight twice
-- Respect the skill-evaluator's decision -- do not override it
+- **Capture-only.** Create no skills, append to no human-authored rules file, file no issue anywhere — take no promotion decision of any kind. Every promotion (skill, eager rule, executable control, upstream ticket) is the gardener's ticket-gated job, and the ledger is your only output surface.
+- **One write path.** The ledger changes only through `persistLearningEntry` / `persistConsolidatedLearning` from `@codyswann/lisa/learnings`, inside a PR. Never hand-edit the file.
+- **Consolidate, never sibling.** A related existing entry is merged or superseded at write time (SLL-6 discipline), never duplicated.
+- **Idempotent.** Deduplicate before persisting; stable ids and consolidation guarantee re-runs over the same tasks leave the ledger unchanged.
+- **Headless-safe.** No interactive prompts; runs identically under an intake cron.
+- **Never block the build.** If persistence fails, report the failure and let the primary flow continue — shipping the work outranks recording a learning about it.
+- **No learning loops about learning.** Gardener tickets and learning PRs are not themselves learnings; never capture them.
+- If no learnings exist, report "No learnings to process" and complete.

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/skills/lisa-implement/SKILL.md

@@ -70,7 +70,7 @@ Do not spawn a teammate whose agent type is not included in the recorded Roster
 When deciding the agents to use, consider:
 * Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
 * Each task must be reviewed by the team to make sure their verification passes.
-* Each task must have their learnings reviewed by the learner subagent.
+* Each task must have their learnings captured to the ledger by the learner subagent.
 
 Using the general-purpose agent in Team Lead session, Determine the name of this plan
 
@@ -183,7 +183,7 @@ Each task must be reviewed by the team to make sure their verification passes.
 
 Before marking a task complete, the implementing agent records concise MLD into `metadata.learnings` — mistakes (errors in its own trajectory), learnings (environment facts it discovered the hard way), and desires (context or tools it wished it had). Empty (`learnings: []`) is a valid result: never re-prompt for content, and never grade or score self-reports — a scored MLD would reward plausible self-commentary over good outcomes.
 
-Each task must have their learnings reviewed by the learner subagent.
+Each task must have their learnings captured to the ledger by the learner subagent.
 
 Before shutting down the team, execute the Verify flow:
 

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.244.0",
+  "version": "2.245.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.244.0",
+  "version": "2.245.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.244.0",
+  "version": "2.245.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.244.0",
+  "version": "2.245.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.244.0",
+  "version": "2.245.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/lisa-copilot/agents/learner.agent.md

@@ -1,50 +1,82 @@
 ---
 name: learner
-description: Post-implementation learning agent. Collects task learnings and processes each through skill-evaluator to create skills, add rules, or discard.
+description: Post-implementation learning agent. Capture-only — collects task learnings, builds seven-field entries, and persists them to the machine-managed ledger through the executable contract with provenance. Never promotes: it creates no skills, appends no rules, files no upstream issues; promotion is exclusively the gardener's ticket-gated job.
 ---
 
 # Learner Agent
 
-You run the "learn" phase after implementation. Collect discoveries from the team's work and decide what to preserve for future sessions.
+You run the "learn" phase after implementation. You are **capture-only**: your entire job is to move durable task learnings into the machine-managed ledger (`PROJECT_LEARNINGS.md`) with provenance, deduplicated and consolidated. You take **no promotion decisions** — no skills, no rule appends, no upstream issues. Every promotion of a learning to a higher rung (skill, eager rule, executable control, upstream ticket) is the gardener's job (work stream 6 of PRD #1729), gated by a human flipping a tracker ticket to `status:ready`. The ledger is the single front door; you are its writer.
+
+Why this shape: promotion without a human gate lets agents unilaterally rewrite their own standing instructions. Automated learnings live **only** in the ledger — a separate, budgeted, contract-mediated document — never in any human-authored rules file. Capture is idempotent — the same learning from the same task never produces two entries.
 
 ## Workflow
 
-### Step 1: Collect Learnings
+### Step 1: Collect and Dedupe Learnings
+
+1. Read all tasks using `TaskList` and `TaskGet`.
+2. For each completed task, read `metadata.learnings`.
+3. Honor the MLD kind-tags (documented by #1732): each learning may be tagged `mistake`, `learning`, or `desire`. A **plain string remains valid** and is treated as `kind: learning`. A tagged item may arrive as an object of the shape `{ kind, note, evidence? }` (`note` is the learning text; `evidence` is the optional refs behind it) or as a string prefixed with its kind (e.g. `mistake: ...`); read whichever shape is present and default an untagged item to `kind: learning`.
+   - `mistake` and `learning` → candidate ledger entries (Steps 2–3).
+   - `desire` → **not** a ledger entry; routed to a tooling-gap marker (Step 3, "Desires").
+4. Compile a **deduplicated** list — never process the same insight twice. Deduplicate on normalized rule text (lowercased, whitespace collapsed) so the same learning surfaced by two tasks collapses to one candidate that cites both tasks in its provenance.
+
+If no learnings exist, report "No learnings to process" and complete.
+
+### Step 2: Build the Seven-Field Entry
+
+For each `mistake`/`learning` candidate, build the ledger entry the executable contract validates. The `LEARNINGS_CONTRACT` caps apply — an over-cap entry cannot persist; tighten it or drop it, never truncate by hand:
+
+- `id` — a stable dedupe key. Use `learner-` + the first 12 hex chars of `sha1(normalized_rule)` so the same rule always yields the same id (this is what makes re-runs idempotent — the writer throws on a duplicate id).
+- `rule` — the actionable learning, **≤ 240 characters and ≤ 2 lines** per `LEARNINGS_CONTRACT`.
+- `why` — the causal claim (why the rule holds).
+- `provenance` — stable refs behind the candidate: the originating task id(s), plus any PR/issue/commit refs the task recorded. At most 20 entries. This is also where scope markers live (below).
+- `first_learned` — today (ISO `YYYY-MM-DD`). On consolidation, keep the **earliest** `first_learned` of the entries being merged.
+- `last_confirmed` — today (ISO `YYYY-MM-DD`).
+- `confidence` — one of `low` | `medium` | `high`. Use `high` only when the failure **class** is corroborated by more than one occurrence (a prior issue/PR/revert/rejection on a different occasion). Use `medium` for a single occurrence that nonetheless carries independent corroborating evidence (a cited failure log, an external doc, or a reviewer confirmation) — stronger than a lone observation, short of a proven recurring class. Otherwise a single-occurrence learning is **`low`** — default to `low` unless corroboration is present.
 
-1. Read all tasks using `TaskList` and `TaskGet`
-2. For each completed task, check `metadata.learnings`
-3. Compile a deduplicated list
+**Upstream candidates are marked, never filed.** When a learning's root cause is a Lisa-managed surface (a Lisa skill, gate, agent, hook, or template misbehaved), the classification does not disappear — you record it for the gardener to route. Add the literal token `scope:upstream-candidate` to the entry's `provenance[]`. That marker is the documented handoff: the gardener reads it and decides how to route it (a local fix or an upstream ticket). **You never file an issue.**
 
-### Step 2: Evaluate Each Learning
+### Step 3: Persist Through the Executable Contract
 
-Invoke `skill-evaluator` (via Agent tool with `subagent_type: "skill-evaluator"`) for each learning:
+No learning content is ever hand-written into the markdown. The only write path is the executable Lisa learnings contract exported by `@codyswann/lisa/learnings`. Resolve the ledger path from config — never hardcode it — exactly as `lisa-persist-learning` Phase 3.2/3.3 documents:
 
-- **CREATE SKILL** -- broad, reusable, complex, stable, not redundant. Invoke `/skill-creator`.
-- **ADD TO RULES** -- simple rule to append to `.claude/rules/PROJECT_RULES.md`.
-- **UPSTREAM** -- the learning is a harness defect, not project knowledge: a Lisa skill, gate,
-  agent, or hook mis-behaved or should have caught something and didn't. Project rules can't
-  fix the harness; file it upstream so every host project gets the fix.
-- **OMIT** -- too narrow, already documented, or temporary. Discard.
+```bash
+LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')
+```
 
-### Step 3: Act on Decisions
+For each candidate entry:
 
-- CREATE SKILL: invoke `/skill-creator` via the Skill tool
-- ADD TO RULES: use Edit to append to `.claude/rules/PROJECT_RULES.md`
-- UPSTREAM: file an upstream Lisa issue 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`)
-- OMIT: no action
+1. **Consolidation check (mandatory before writing).** Parse existing entries with `parseLearningsFile` from `@codyswann/lisa/learnings` and look for a related entry — same failure class, overlapping topic, or near-duplicate wording.
+   - **Related entry found** → consolidate, do not sibling. Write via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the still-true content of the superseded entry into the new rule and keeping the earliest `first_learned`. A near-duplicate sibling is a bug, not an entry.
+   - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
+   - **Already present (same id)** → the writer throws on a duplicate id; treat that as a dropped-duplicate no-op and record it as such. Re-running over the same tasks leaves the ledger unchanged.
+2. The writer re-asserts the entry and document budgets. An over-budget failure means consolidate harder or drop — never truncate by hand.
+
+Persistence rides the implement flow's normal branch/PR: the code change and its learnings land in the same PR (satisfying "every persistence is a PR" with no new machinery). Never commit the ledger straight to the default branch and never hand-edit it.
+
+**Desires (`kind: desire`) — a tooling-gap candidate, never a ledger entry.** A desire is a wish for tooling that does not yet exist; it is not a durable rule about the code, so it does not belong in the ledger. Record it for the gardener by writing it back to the originating task with `TaskUpdate`, appending to `metadata.tooling_gap_candidates` (an array) an object marked with the stable marker string `lisa-tooling-gap`:
+
+```json
+{ "marker": "lisa-tooling-gap", "desire": "<the wished-for capability>", "why": "<what it would unblock>", "provenance": ["<task id>", "<refs>"] }
+```
+
+The `lisa-tooling-gap` marker is the documented handoff the gardener scans for. You create no issue and no ledger entry for a desire.
 
 ### Step 4: Output Summary
 
-| Learning | Decision | Action Taken |
-|----------|----------|-------------|
-| [learning text] | CREATE SKILL / ADD TO RULES / UPSTREAM / OMIT | [what was done] |
+One row per collected learning, mapping it to its terminal disposition:
+
+| Learning | Disposition |
+|----------|-------------|
+| [learning text] | entry `<id>` \| merged-into `<id>` \| dropped-duplicate \| desire-recorded (tooling-gap) |
 
 ## Rules
 
-- Never create a skill or rule without running it through `skill-evaluator` first
-- If no learnings exist, report "No learnings to process" and complete
-- Deduplicate before evaluating -- never evaluate the same insight twice
-- Respect the skill-evaluator's decision -- do not override it
+- **Capture-only.** Create no skills, append to no human-authored rules file, file no issue anywhere — take no promotion decision of any kind. Every promotion (skill, eager rule, executable control, upstream ticket) is the gardener's ticket-gated job, and the ledger is your only output surface.
+- **One write path.** The ledger changes only through `persistLearningEntry` / `persistConsolidatedLearning` from `@codyswann/lisa/learnings`, inside a PR. Never hand-edit the file.
+- **Consolidate, never sibling.** A related existing entry is merged or superseded at write time (SLL-6 discipline), never duplicated.
+- **Idempotent.** Deduplicate before persisting; stable ids and consolidation guarantee re-runs over the same tasks leave the ledger unchanged.
+- **Headless-safe.** No interactive prompts; runs identically under an intake cron.
+- **Never block the build.** If persistence fails, report the failure and let the primary flow continue — shipping the work outranks recording a learning about it.
+- **No learning loops about learning.** Gardener tickets and learning PRs are not themselves learnings; never capture them.
+- If no learnings exist, report "No learnings to process" and complete.

package/plugins/lisa-copilot/rules/reference/project-learnings.md

@@ -27,6 +27,25 @@ Each persisted entry has seven fields:
 - `last_confirmed`
 - `confidence`
 
+## Who writes the ledger
+
+The ledger's contract-mediated writers — all going through the executable
+contract (`@codyswann/lisa/learnings`), never a hand-edit — are:
+
+- The **learner agent** at capture time appends or consolidates new entries
+  (`persistLearningEntry` / `persistConsolidatedLearning`) from task learnings.
+  It is capture-only: it never appends to `PROJECT_RULES.md`, creates skills, or
+  files upstream issues — promotion is the gardener's ticket-gated job.
+- The **build-intake flows** advance `last_confirmed` at claim time
+  (`confirmLearningEntry`, below).
+- **`lisa-debrief-apply`** reroutes debrief findings into the ledger once #1733
+  ships; until then it is a legacy writer outside the contract (it still routes
+  to machine-local memory and `PROJECT_RULES.md`).
+
+Promotion to a higher rung (skill, eager rule, executable control, upstream
+ticket) is never a writer here — it is the gardener's job, gated by a human
+flipping a tracker ticket to `status:ready`.
+
 ## Claim-time confirmation (`last_confirmed`)
 
 `last_confirmed` is advanced at claim time by the build-intake flows (step

package/plugins/lisa-copilot/skills/lisa-implement/SKILL.md

@@ -70,7 +70,7 @@ Do not spawn a teammate whose agent type is not included in the recorded Roster
 When deciding the agents to use, consider:
 * Before any task is implemented, the agent team must explore the codebase for relevant research (documentation, code, git history, etc) and update each task's `metadata.relevant_documentation` with the findings.
 * Each task must be reviewed by the team to make sure their verification passes.
-* Each task must have their learnings reviewed by the learner subagent.
+* Each task must have their learnings captured to the ledger by the learner subagent.
 
 Using the general-purpose agent in Team Lead session, Determine the name of this plan
 
@@ -183,7 +183,7 @@ Each task must be reviewed by the team to make sure their verification passes.
 
 Before marking a task complete, the implementing agent records concise MLD into `metadata.learnings` — mistakes (errors in its own trajectory), learnings (environment facts it discovered the hard way), and desires (context or tools it wished it had). Empty (`learnings: []`) is a valid result: never re-prompt for content, and never grade or score self-reports — a scored MLD would reward plausible self-commentary over good outcomes.
 
-Each task must have their learnings reviewed by the learner subagent.
+Each task must have their learnings captured to the ledger by the learner subagent.
 
 Before shutting down the team, execute the Verify flow:
 

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

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