@codyswann/lisa 2.242.0 → 2.244.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/dist/core/instruction-files-migration.d.ts +38 -0
  2. package/dist/core/instruction-files-migration.d.ts.map +1 -1
  3. package/dist/core/instruction-files-migration.js +76 -7
  4. package/dist/core/instruction-files-migration.js.map +1 -1
  5. package/dist/core/learnings-projection.d.ts +38 -0
  6. package/dist/core/learnings-projection.d.ts.map +1 -0
  7. package/dist/core/learnings-projection.js +94 -0
  8. package/dist/core/learnings-projection.js.map +1 -0
  9. package/dist/core/learnings.d.ts +2 -1
  10. package/dist/core/learnings.d.ts.map +1 -1
  11. package/dist/core/learnings.js +2 -1
  12. package/dist/core/learnings.js.map +1 -1
  13. package/dist/core/lisa.d.ts +40 -0
  14. package/dist/core/lisa.d.ts.map +1 -1
  15. package/dist/core/lisa.js +90 -12
  16. package/dist/core/lisa.js.map +1 -1
  17. package/dist/core/project-config.d.ts +36 -3
  18. package/dist/core/project-config.d.ts.map +1 -1
  19. package/dist/core/project-config.js +127 -10
  20. package/dist/core/project-config.js.map +1 -1
  21. package/dist/sync/registry.js +1 -1
  22. package/dist/sync/registry.js.map +1 -1
  23. package/package.json +1 -1
  24. package/plugins/lisa/.claude-plugin/plugin.json +1 -1
  25. package/plugins/lisa/.codex-plugin/plugin.json +1 -1
  26. package/plugins/lisa/.codex-plugin/skills/lisa-implement/SKILL.md +6 -1
  27. package/plugins/lisa/.codex-plugin/skills/lisa-persist-learning/SKILL.md +1 -1
  28. package/plugins/lisa/rules/eager/config-resolution.md +6 -3
  29. package/plugins/lisa/rules/eager/project-learnings.md +11 -5
  30. package/plugins/lisa/rules/reference/config-resolution.md +2 -1
  31. package/plugins/lisa/rules/reference/intent-routing.md +2 -0
  32. package/plugins/lisa/rules/reference/project-learnings.md +28 -8
  33. package/plugins/lisa/skills/lisa-implement/SKILL.md +6 -1
  34. package/plugins/lisa/skills/lisa-persist-learning/SKILL.md +1 -1
  35. package/plugins/lisa-agy/plugin.json +1 -1
  36. package/plugins/lisa-agy/skills/lisa-implement/SKILL.md +6 -1
  37. package/plugins/lisa-agy/skills/lisa-persist-learning/SKILL.md +1 -1
  38. package/plugins/lisa-cdk/.claude-plugin/plugin.json +1 -1
  39. package/plugins/lisa-cdk/.codex-plugin/plugin.json +1 -1
  40. package/plugins/lisa-cdk-agy/plugin.json +1 -1
  41. package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json +1 -1
  42. package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json +1 -1
  43. package/plugins/lisa-copilot/.claude-plugin/plugin.json +1 -1
  44. package/plugins/lisa-copilot/rules/eager/config-resolution.md +6 -3
  45. package/plugins/lisa-copilot/rules/eager/project-learnings.md +11 -5
  46. package/plugins/lisa-copilot/rules/reference/config-resolution.md +2 -1
  47. package/plugins/lisa-copilot/rules/reference/intent-routing.md +2 -0
  48. package/plugins/lisa-copilot/rules/reference/project-learnings.md +28 -8
  49. package/plugins/lisa-copilot/skills/lisa-implement/SKILL.md +6 -1
  50. package/plugins/lisa-copilot/skills/lisa-persist-learning/SKILL.md +1 -1
  51. package/plugins/lisa-cursor/.claude-plugin/plugin.json +1 -1
  52. package/plugins/lisa-cursor/rules/config-resolution-reference.mdc +2 -1
  53. package/plugins/lisa-cursor/rules/config-resolution.mdc +6 -3
  54. package/plugins/lisa-cursor/rules/intent-routing-reference.mdc +2 -0
  55. package/plugins/lisa-cursor/rules/project-learnings-reference.mdc +28 -8
  56. package/plugins/lisa-cursor/rules/project-learnings.mdc +11 -5
  57. package/plugins/lisa-cursor/skills/lisa-implement/SKILL.md +6 -1
  58. package/plugins/lisa-cursor/skills/lisa-persist-learning/SKILL.md +1 -1
  59. package/plugins/lisa-expo/.claude-plugin/plugin.json +1 -1
  60. package/plugins/lisa-expo/.codex-plugin/plugin.json +1 -1
  61. package/plugins/lisa-expo-agy/plugin.json +1 -1
  62. package/plugins/lisa-expo-copilot/.claude-plugin/plugin.json +1 -1
  63. package/plugins/lisa-expo-cursor/.claude-plugin/plugin.json +1 -1
  64. package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json +1 -1
  65. package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json +1 -1
  66. package/plugins/lisa-harper-fabric-agy/plugin.json +1 -1
  67. package/plugins/lisa-harper-fabric-copilot/.claude-plugin/plugin.json +1 -1
  68. package/plugins/lisa-harper-fabric-cursor/.claude-plugin/plugin.json +1 -1
  69. package/plugins/lisa-nestjs/.claude-plugin/plugin.json +1 -1
  70. package/plugins/lisa-nestjs/.codex-plugin/plugin.json +1 -1
  71. package/plugins/lisa-nestjs-agy/plugin.json +1 -1
  72. package/plugins/lisa-nestjs-copilot/.claude-plugin/plugin.json +1 -1
  73. package/plugins/lisa-nestjs-cursor/.claude-plugin/plugin.json +1 -1
  74. package/plugins/lisa-openclaw/.claude-plugin/plugin.json +1 -1
  75. package/plugins/lisa-openclaw/.codex-plugin/plugin.json +1 -1
  76. package/plugins/lisa-openclaw-agy/plugin.json +1 -1
  77. package/plugins/lisa-openclaw-copilot/.claude-plugin/plugin.json +1 -1
  78. package/plugins/lisa-openclaw-cursor/.claude-plugin/plugin.json +1 -1
  79. package/plugins/lisa-phaser/.claude-plugin/plugin.json +1 -1
  80. package/plugins/lisa-phaser/.codex-plugin/plugin.json +1 -1
  81. package/plugins/lisa-phaser-agy/plugin.json +1 -1
  82. package/plugins/lisa-phaser-copilot/.claude-plugin/plugin.json +1 -1
  83. package/plugins/lisa-phaser-cursor/.claude-plugin/plugin.json +1 -1
  84. package/plugins/lisa-rails/.claude-plugin/plugin.json +1 -1
  85. package/plugins/lisa-rails/.codex-plugin/plugin.json +1 -1
  86. package/plugins/lisa-rails-agy/plugin.json +1 -1
  87. package/plugins/lisa-rails-copilot/.claude-plugin/plugin.json +1 -1
  88. package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json +1 -1
  89. package/plugins/lisa-typescript/.claude-plugin/plugin.json +1 -1
  90. package/plugins/lisa-typescript/.codex-plugin/plugin.json +1 -1
  91. package/plugins/lisa-typescript-agy/plugin.json +1 -1
  92. package/plugins/lisa-typescript-copilot/.claude-plugin/plugin.json +1 -1
  93. package/plugins/lisa-typescript-cursor/.claude-plugin/plugin.json +1 -1
  94. package/plugins/lisa-wiki/.claude-plugin/plugin.json +1 -1
  95. package/plugins/lisa-wiki/.codex-plugin/plugin.json +1 -1
  96. package/plugins/lisa-wiki-agy/plugin.json +1 -1
  97. package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json +1 -1
  98. package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json +1 -1
  99. package/plugins/src/base/rules/eager/config-resolution.md +6 -3
  100. package/plugins/src/base/rules/eager/project-learnings.md +11 -5
  101. package/plugins/src/base/rules/reference/config-resolution.md +2 -1
  102. package/plugins/src/base/rules/reference/intent-routing.md +2 -0
  103. package/plugins/src/base/rules/reference/project-learnings.md +28 -8
  104. package/plugins/src/base/skills/lisa-implement/SKILL.md +6 -1
  105. package/plugins/src/base/skills/lisa-persist-learning/SKILL.md +1 -1
  106. package/scripts/check-learnings-budget.ts +1 -2
  107. /package/all/create-only/{.claude/rules → .lisa}/PROJECT_LEARNINGS.md +0 -0
@@ -1,11 +1,17 @@
1
1
  # Project Learnings (load-bearing)
2
2
 
3
3
  Before normal task work, resolve this repository's committed `.lisa.config.json`
4
- and derive the canonical learnings file as the sibling of `projectRulesFile`
5
- (default: `.claude/rules/PROJECT_LEARNINGS.md`). If that file exists, consume it
6
- through the executable Lisa learnings contract exported by
7
- `@codyswann/lisa/learnings` before relying on ad-hoc memory or prior-session
8
- notes.
4
+ and derive the machine-managed learnings ledger: the optional `learnings.file`
5
+ override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives cold in
6
+ `.lisa/`, NOT in an auto-loaded rules tree — so it is never injected raw into the
7
+ session.
8
+
9
+ Consume it ONLY through the executable Lisa learnings contract exported by
10
+ `@codyswann/lisa/learnings`: parse and validate with `parseLearningsFile`, then
11
+ take the bounded serving slice from `projectLearnings` (the highest-priority
12
+ entries within the token/entry budget). **Never read the raw ledger file
13
+ wholesale into context** — the whole point of the relocation is that sessions
14
+ receive the contract's bounded projection, not the full file.
9
15
 
10
16
  Missing learnings are a silent no-op. Malformed, non-canonical, unsafe, or
11
17
  over-budget learnings produce one readable warning, apply no entry, and must not
@@ -179,7 +179,8 @@ fi
179
179
  |-------|----------|---------|-------|
180
180
  | `tracker` | **yes** | — | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing → fail with instruction to run the matching `/lisa:setup:*` skill. |
181
181
  | `source` | no | — | Default PRD source for batch skills (`/lisa:intake`) and arg-less single-PRD skills. One of `"notion"`, `"confluence"`, `"linear"`, `"github"`, `"jira"`. Explicit URLs/keys passed to a skill always win over `source`; this is a default, not a lock. |
182
- | `projectRulesFile` | no | `.claude/rules/PROJECT_RULES.md` | Safe repo-relative Markdown path for hand-authored project rules. The bounded learning writer derives a separate `PROJECT_LEARNINGS.md` sibling in the same directory; there is intentionally no second path setting. |
182
+ | `projectRulesFile` | no | `.claude/rules/PROJECT_RULES.md` | Safe repo-relative Markdown path for hand-authored project rules. Independent of the learnings ledger relocating the rules file never moves the ledger. |
183
+ | `learnings.file` | no | `.lisa/PROJECT_LEARNINGS.md` | Safe repo-relative Markdown path for the machine-managed learnings ledger, overriding the `.lisa/` default. Rejected if it resolves inside any auto-loaded rules tree (`.claude/rules`, `.cursor/rules`, `.github/instructions`, `.agents/rules`) — the ledger must stay out of eager context. |
183
184
  | `usage` | no | — | Optional token/cost pricing metadata consumed by the `usage-accounting` rule. Missing pricing never blocks a lifecycle flow; Lisa records token counts with `estimated_cost: null` when no trustworthy price source is configured. |
184
185
  | `wiki` | no | — | Wiki location for the `wiki-knowledge-source` rule. Omit for a local in-repo wiki (`wiki/`). See **Wiki source** below. |
185
186
 
@@ -166,6 +166,8 @@ Determine the work type and execute the matching variant:
166
166
  3. Recommend next action (Research, Plan, Implement, or escalate)
167
167
  4. `learner` -- capture discoveries
168
168
 
169
+ In every work type above, before a task completes -- immediately ahead of the closing `learner` step -- the implementing agent records concise kind-tagged MLD (Mistakes / Learnings / Desires) into that task's `metadata.learnings`: one line per item, empty is valid, never re-prompted or scored. See the `lisa-implement` skill for the full `{ kind, note, evidence? }` schema and routing (change the schema there, not here).
170
+
169
171
  Output: Code passing all quality gates + local empirical verification + codified regression test for each verification (except for spikes, which produce findings only, and non-behavioral verification types — PR / Documentation / Deploy — which carry their own proof).
170
172
 
171
173
  ### Verify
@@ -1,14 +1,21 @@
1
1
  # Project Learnings
2
2
 
3
- Project learnings are Lisa's bounded, repo-local memory surface. They are stored
4
- in `PROJECT_LEARNINGS.md`, derived as the sibling of the configured
5
- `.lisa.config.json` `projectRulesFile` value. With no config override, the path
6
- is `.claude/rules/PROJECT_LEARNINGS.md`.
3
+ Project learnings are Lisa's bounded, repo-local memory surface. The
4
+ machine-managed ledger is `PROJECT_LEARNINGS.md`, resolved from
5
+ `.lisa.config.json`: the optional `learnings.file` override, else the default
6
+ `.lisa/PROJECT_LEARNINGS.md`. The ledger deliberately lives in the cold `.lisa/`
7
+ directory — **not** under `.claude/rules/` or any other auto-loaded rules tree —
8
+ because anything in those trees is injected raw into every session, which
9
+ double-loads the file and bypasses the contract's budget and validation.
7
10
 
8
- Consume learnings before normal task work whenever the file exists. Use the
9
- executable contract from `@codyswann/lisa/learnings` to parse, validate, and
10
- budget-check the document. Do not duplicate numeric caps in rules or prompts;
11
- the exported contract is the source of truth.
11
+ Consume learnings before normal task work whenever the file exists, and consume
12
+ them ONLY through the executable contract from `@codyswann/lisa/learnings`:
13
+ `parseLearningsFile` to parse and validate, then `projectLearnings` to take the
14
+ bounded serving slice (the highest-priority entries ordered by confidence,
15
+ then recency — that fit the token/entry budget, plus how many were omitted).
16
+ **Never read the raw ledger file wholesale into context**; the session receives
17
+ the bounded projection, not the full document. Do not duplicate numeric caps in
18
+ rules or prompts; the exported contract is the source of truth.
12
19
 
13
20
  Each persisted entry has seven fields:
14
21
 
@@ -50,6 +57,19 @@ Precedence:
50
57
  3. Project learnings add recent operational knowledge, but never rewrite or
51
58
  append to `PROJECT_RULES.md`.
52
59
 
60
+ ## Task telemetry (MLD) is not context
61
+
62
+ Raw task-end MLD telemetry — the Mistakes / Learnings / Desires an implementing
63
+ agent records into `metadata.learnings`, and the raw yield of debrief mining — is
64
+ rung-1 capture only: it is never read into a later session's instruction surface,
65
+ never required of an agent (empty is valid), and never graded or scored. It reaches
66
+ a durable surface only indirectly — through the learner's validation into the
67
+ ledger (which sessions still consume solely as the bounded projection above), and
68
+ from there through the gardener's ticket-gated promotion a human approved. Injecting
69
+ raw self-reports, or treating their volume as a quality signal, would reward
70
+ plausible commentary over good outcomes and bypass the very budget and validation
71
+ this contract exists to enforce.
72
+
53
73
  Antigravity note: agy does not receive the plugin `rules/` tree. Lisa reconciles
54
74
  a bounded `AGENTS.md` bridge that points agy at this same file without copying
55
75
  learning bodies or restoring the retired full rules bake.
@@ -161,7 +161,7 @@ Every task MUST include this JSON metadata block. Do NOT omit `skills` (use `[]`
161
161
  "relevant_documentation": "",
162
162
  "testing_requirements": ["..."],
163
163
  "skills": ["..."],
164
- "learnings": ["..."],
164
+ "learnings": [{ "kind": "mistake", "note": "one line", "evidence": "optional ref" }],
165
165
  "required_access": [
166
166
  { "tool": "<external tool/system this task or its verification needs>", "probe": "<the read-only command or *-access check that proves access>", "status": "pass|fail" }
167
167
  ],
@@ -173,11 +173,16 @@ Every task MUST include this JSON metadata block. Do NOT omit `skills` (use `[]`
173
173
  }
174
174
  ```
175
175
 
176
+ The `learnings` array is task-end MLD telemetry (Mistakes / Learnings / Desires) — a low-trust self-report for the harness builder, never instructions for a later agent. Each entry is either a plain string (treated as kind `learning` for backward compatibility with older flows) or an object, exactly like the example entry in the block above: a `kind` of `mistake`, `learning`, or `desire`; a one-line `note`; and an optional `evidence` pointer. A `mistake` is an error in the agent's own trajectory, a `learning` is an environment fact discovered the hard way, a `desire` is context or tooling the agent wished it had. Keep each to one line — no essays. `mistake`/`learning` entries are ledger candidates; `desire` entries are tooling-gap candidates that the learner (#1731) records for the gardener's human-gated tooling-gap lane.
177
+
176
178
  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.
177
179
 
178
180
  For Fix tasks and user-visible Build tasks, `testing_requirements` must include the highest-practical-observation regression requirement above, including the selected harness or the recorded absence/blocker path. The completion condition must include the proof command and the required CI execution evidence for the new spec.
179
181
 
180
182
  Each task must be reviewed by the team to make sure their verification passes.
183
+
184
+ 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.
185
+
181
186
  Each task must have their learnings reviewed by the learner subagent.
182
187
 
183
188
  Before shutting down the team, execute the Verify flow:
@@ -139,7 +139,7 @@ Continue to Phase 3.
139
139
  No learning content is ever committed without a PR — there is no other write path, and the PR must touch **only** the learnings surface (any other changed file is a bug).
140
140
 
141
141
  1. **PR dedupe.** Search all PRs for the marker `[lisa-learning-pr] key=<fingerprint>` in the body (`gh pr list --state all --search '"<marker>" in:body' --json number,url`), with the stale-index guard above. If one exists, reference it and stop — never open a duplicate.
142
- 2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `PROJECT_LEARNINGS.md` sibling of the configured `.lisa.config.json` `projectRulesFile` (default `.claude/rules/PROJECT_LEARNINGS.md`):
142
+ 2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the machine-managed ledger resolved from `.lisa.config.json` (the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md` — a cold path, never an auto-loaded rules tree):
143
143
 
144
144
  ```bash
145
145
  LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -184,7 +184,8 @@ fi
184
184
  |-------|----------|---------|-------|
185
185
  | `tracker` | **yes** | — | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing → fail with instruction to run the matching `/lisa:setup:*` skill. |
186
186
  | `source` | no | — | Default PRD source for batch skills (`/lisa:intake`) and arg-less single-PRD skills. One of `"notion"`, `"confluence"`, `"linear"`, `"github"`, `"jira"`. Explicit URLs/keys passed to a skill always win over `source`; this is a default, not a lock. |
187
- | `projectRulesFile` | no | `.claude/rules/PROJECT_RULES.md` | Safe repo-relative Markdown path for hand-authored project rules. The bounded learning writer derives a separate `PROJECT_LEARNINGS.md` sibling in the same directory; there is intentionally no second path setting. |
187
+ | `projectRulesFile` | no | `.claude/rules/PROJECT_RULES.md` | Safe repo-relative Markdown path for hand-authored project rules. Independent of the learnings ledger relocating the rules file never moves the ledger. |
188
+ | `learnings.file` | no | `.lisa/PROJECT_LEARNINGS.md` | Safe repo-relative Markdown path for the machine-managed learnings ledger, overriding the `.lisa/` default. Rejected if it resolves inside any auto-loaded rules tree (`.claude/rules`, `.cursor/rules`, `.github/instructions`, `.agents/rules`) — the ledger must stay out of eager context. |
188
189
  | `usage` | no | — | Optional token/cost pricing metadata consumed by the `usage-accounting` rule. Missing pricing never blocks a lifecycle flow; Lisa records token counts with `estimated_cost: null` when no trustworthy price source is configured. |
189
190
  | `wiki` | no | — | Wiki location for the `wiki-knowledge-source` rule. Omit for a local in-repo wiki (`wiki/`). See **Wiki source** below. |
190
191
 
@@ -34,9 +34,12 @@ Project tracker (`jira` / `github` / `linear`) is read from `.lisa.config.json`
34
34
 
35
35
  Resolve hand-authored project rules from `.lisa.config.json`
36
36
  `projectRulesFile`, defaulting to `.claude/rules/PROJECT_RULES.md`. Automated
37
- learnings never append to that file: they use the separate
38
- `PROJECT_LEARNINGS.md` sibling derived from the configured rules directory.
39
- Both writers and budget checks import the executable contract from
37
+ learnings never append to that file: they use the separate machine-managed
38
+ ledger resolved from `.lisa.config.json` the optional `learnings.file`
39
+ override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives in the
40
+ cold `.lisa/` tree (never an auto-loaded rules directory) and is consumed only
41
+ through the contract's bounded projection, never read raw wholesale. Both
42
+ writers and budget checks import the executable contract from
40
43
  `@codyswann/lisa/learnings`; they must not copy its numeric limits.
41
44
 
42
45
  ## Env → base branch
@@ -171,6 +171,8 @@ Determine the work type and execute the matching variant:
171
171
  3. Recommend next action (Research, Plan, Implement, or escalate)
172
172
  4. `learner` -- capture discoveries
173
173
 
174
+ In every work type above, before a task completes -- immediately ahead of the closing `learner` step -- the implementing agent records concise kind-tagged MLD (Mistakes / Learnings / Desires) into that task's `metadata.learnings`: one line per item, empty is valid, never re-prompted or scored. See the `lisa-implement` skill for the full `{ kind, note, evidence? }` schema and routing (change the schema there, not here).
175
+
174
176
  Output: Code passing all quality gates + local empirical verification + codified regression test for each verification (except for spikes, which produce findings only, and non-behavioral verification types — PR / Documentation / Deploy — which carry their own proof).
175
177
 
176
178
  ### Verify
@@ -5,15 +5,22 @@ alwaysApply: false
5
5
 
6
6
  # Project Learnings
7
7
 
8
- Project learnings are Lisa's bounded, repo-local memory surface. They are stored
9
- in `PROJECT_LEARNINGS.md`, derived as the sibling of the configured
10
- `.lisa.config.json` `projectRulesFile` value. With no config override, the path
11
- is `.claude/rules/PROJECT_LEARNINGS.md`.
8
+ Project learnings are Lisa's bounded, repo-local memory surface. The
9
+ machine-managed ledger is `PROJECT_LEARNINGS.md`, resolved from
10
+ `.lisa.config.json`: the optional `learnings.file` override, else the default
11
+ `.lisa/PROJECT_LEARNINGS.md`. The ledger deliberately lives in the cold `.lisa/`
12
+ directory — **not** under `.claude/rules/` or any other auto-loaded rules tree —
13
+ because anything in those trees is injected raw into every session, which
14
+ double-loads the file and bypasses the contract's budget and validation.
12
15
 
13
- Consume learnings before normal task work whenever the file exists. Use the
14
- executable contract from `@codyswann/lisa/learnings` to parse, validate, and
15
- budget-check the document. Do not duplicate numeric caps in rules or prompts;
16
- the exported contract is the source of truth.
16
+ Consume learnings before normal task work whenever the file exists, and consume
17
+ them ONLY through the executable contract from `@codyswann/lisa/learnings`:
18
+ `parseLearningsFile` to parse and validate, then `projectLearnings` to take the
19
+ bounded serving slice (the highest-priority entries ordered by confidence,
20
+ then recency — that fit the token/entry budget, plus how many were omitted).
21
+ **Never read the raw ledger file wholesale into context**; the session receives
22
+ the bounded projection, not the full document. Do not duplicate numeric caps in
23
+ rules or prompts; the exported contract is the source of truth.
17
24
 
18
25
  Each persisted entry has seven fields:
19
26
 
@@ -55,6 +62,19 @@ Precedence:
55
62
  3. Project learnings add recent operational knowledge, but never rewrite or
56
63
  append to `PROJECT_RULES.md`.
57
64
 
65
+ ## Task telemetry (MLD) is not context
66
+
67
+ Raw task-end MLD telemetry — the Mistakes / Learnings / Desires an implementing
68
+ agent records into `metadata.learnings`, and the raw yield of debrief mining — is
69
+ rung-1 capture only: it is never read into a later session's instruction surface,
70
+ never required of an agent (empty is valid), and never graded or scored. It reaches
71
+ a durable surface only indirectly — through the learner's validation into the
72
+ ledger (which sessions still consume solely as the bounded projection above), and
73
+ from there through the gardener's ticket-gated promotion a human approved. Injecting
74
+ raw self-reports, or treating their volume as a quality signal, would reward
75
+ plausible commentary over good outcomes and bypass the very budget and validation
76
+ this contract exists to enforce.
77
+
58
78
  Antigravity note: agy does not receive the plugin `rules/` tree. Lisa reconciles
59
79
  a bounded `AGENTS.md` bridge that points agy at this same file without copying
60
80
  learning bodies or restoring the retired full rules bake.
@@ -6,11 +6,17 @@ alwaysApply: true
6
6
  # Project Learnings (load-bearing)
7
7
 
8
8
  Before normal task work, resolve this repository's committed `.lisa.config.json`
9
- and derive the canonical learnings file as the sibling of `projectRulesFile`
10
- (default: `.claude/rules/PROJECT_LEARNINGS.md`). If that file exists, consume it
11
- through the executable Lisa learnings contract exported by
12
- `@codyswann/lisa/learnings` before relying on ad-hoc memory or prior-session
13
- notes.
9
+ and derive the machine-managed learnings ledger: the optional `learnings.file`
10
+ override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives cold in
11
+ `.lisa/`, NOT in an auto-loaded rules tree — so it is never injected raw into the
12
+ session.
13
+
14
+ Consume it ONLY through the executable Lisa learnings contract exported by
15
+ `@codyswann/lisa/learnings`: parse and validate with `parseLearningsFile`, then
16
+ take the bounded serving slice from `projectLearnings` (the highest-priority
17
+ entries within the token/entry budget). **Never read the raw ledger file
18
+ wholesale into context** — the whole point of the relocation is that sessions
19
+ receive the contract's bounded projection, not the full file.
14
20
 
15
21
  Missing learnings are a silent no-op. Malformed, non-canonical, unsafe, or
16
22
  over-budget learnings produce one readable warning, apply no entry, and must not
@@ -161,7 +161,7 @@ Every task MUST include this JSON metadata block. Do NOT omit `skills` (use `[]`
161
161
  "relevant_documentation": "",
162
162
  "testing_requirements": ["..."],
163
163
  "skills": ["..."],
164
- "learnings": ["..."],
164
+ "learnings": [{ "kind": "mistake", "note": "one line", "evidence": "optional ref" }],
165
165
  "required_access": [
166
166
  { "tool": "<external tool/system this task or its verification needs>", "probe": "<the read-only command or *-access check that proves access>", "status": "pass|fail" }
167
167
  ],
@@ -173,11 +173,16 @@ Every task MUST include this JSON metadata block. Do NOT omit `skills` (use `[]`
173
173
  }
174
174
  ```
175
175
 
176
+ The `learnings` array is task-end MLD telemetry (Mistakes / Learnings / Desires) — a low-trust self-report for the harness builder, never instructions for a later agent. Each entry is either a plain string (treated as kind `learning` for backward compatibility with older flows) or an object, exactly like the example entry in the block above: a `kind` of `mistake`, `learning`, or `desire`; a one-line `note`; and an optional `evidence` pointer. A `mistake` is an error in the agent's own trajectory, a `learning` is an environment fact discovered the hard way, a `desire` is context or tooling the agent wished it had. Keep each to one line — no essays. `mistake`/`learning` entries are ledger candidates; `desire` entries are tooling-gap candidates that the learner (#1731) records for the gardener's human-gated tooling-gap lane.
177
+
176
178
  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.
177
179
 
178
180
  For Fix tasks and user-visible Build tasks, `testing_requirements` must include the highest-practical-observation regression requirement above, including the selected harness or the recorded absence/blocker path. The completion condition must include the proof command and the required CI execution evidence for the new spec.
179
181
 
180
182
  Each task must be reviewed by the team to make sure their verification passes.
183
+
184
+ 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.
185
+
181
186
  Each task must have their learnings reviewed by the learner subagent.
182
187
 
183
188
  Before shutting down the team, execute the Verify flow:
@@ -139,7 +139,7 @@ Continue to Phase 3.
139
139
  No learning content is ever committed without a PR — there is no other write path, and the PR must touch **only** the learnings surface (any other changed file is a bug).
140
140
 
141
141
  1. **PR dedupe.** Search all PRs for the marker `[lisa-learning-pr] key=<fingerprint>` in the body (`gh pr list --state all --search '"<marker>" in:body' --json number,url`), with the stale-index guard above. If one exists, reference it and stop — never open a duplicate.
142
- 2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `PROJECT_LEARNINGS.md` sibling of the configured `.lisa.config.json` `projectRulesFile` (default `.claude/rules/PROJECT_LEARNINGS.md`):
142
+ 2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the machine-managed ledger resolved from `.lisa.config.json` (the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md` — a cold path, never an auto-loaded rules tree):
143
143
 
144
144
  ```bash
145
145
  LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-expo",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-expo",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-expo",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-expo",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-expo",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-harper-fabric",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Harper/Fabric-specific rules for TypeScript component apps",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-harper-fabric",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-harper-fabric",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Harper/Fabric-specific rules for TypeScript component apps",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-harper-fabric",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Harper/Fabric-specific rules for TypeScript component apps",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-harper-fabric",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Harper/Fabric-specific rules for TypeScript component apps",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-nestjs",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-nestjs",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "NestJS-specific skills and migration write-protection hooks.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-nestjs",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-nestjs",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-nestjs",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-openclaw",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-openclaw",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-openclaw",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-openclaw",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-openclaw",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "2.242.0",
3
+ "version": "2.244.0",
4
4
  "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"