@codyswann/lisa 2.242.0 → 2.243.0

package/plugins/lisa-cursor/rules/config-resolution.mdc

@@ -34,9 +34,12 @@ Project tracker (`jira` / `github` / `linear`) is read from `.lisa.config.json`
 
 Resolve hand-authored project rules from `.lisa.config.json`
 `projectRulesFile`, defaulting to `.claude/rules/PROJECT_RULES.md`. Automated
-learnings never append to that file: they use the separate
-`PROJECT_LEARNINGS.md` sibling derived from the configured rules directory.
-Both writers and budget checks import the executable contract from
+learnings never append to that file: they use the separate machine-managed
+ledger resolved from `.lisa.config.json` — the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives in the
+cold `.lisa/` tree (never an auto-loaded rules directory) and is consumed only
+through the contract's bounded projection, never read raw wholesale. Both
+writers and budget checks import the executable contract from
 `@codyswann/lisa/learnings`; they must not copy its numeric limits.
 
 ## Env → base branch

package/plugins/lisa-cursor/rules/project-learnings-reference.mdc

@@ -5,15 +5,22 @@ alwaysApply: false
 
 # Project Learnings
 
-Project learnings are Lisa's bounded, repo-local memory surface. They are stored
-in `PROJECT_LEARNINGS.md`, derived as the sibling of the configured
-`.lisa.config.json` `projectRulesFile` value. With no config override, the path
-is `.claude/rules/PROJECT_LEARNINGS.md`.
-
-Consume learnings before normal task work whenever the file exists. Use the
-executable contract from `@codyswann/lisa/learnings` to parse, validate, and
-budget-check the document. Do not duplicate numeric caps in rules or prompts;
-the exported contract is the source of truth.
+Project learnings are Lisa's bounded, repo-local memory surface. The
+machine-managed ledger is `PROJECT_LEARNINGS.md`, resolved from
+`.lisa.config.json`: the optional `learnings.file` override, else the default
+`.lisa/PROJECT_LEARNINGS.md`. The ledger deliberately lives in the cold `.lisa/`
+directory — **not** under `.claude/rules/` or any other auto-loaded rules tree —
+because anything in those trees is injected raw into every session, which
+double-loads the file and bypasses the contract's budget and validation.
+
+Consume learnings before normal task work whenever the file exists, and consume
+them ONLY through the executable contract from `@codyswann/lisa/learnings`:
+`parseLearningsFile` to parse and validate, then `projectLearnings` to take the
+bounded serving slice (the highest-priority entries — ordered by confidence,
+then recency — that fit the token/entry budget, plus how many were omitted).
+**Never read the raw ledger file wholesale into context**; the session receives
+the bounded projection, not the full document. Do not duplicate numeric caps in
+rules or prompts; the exported contract is the source of truth.
 
 Each persisted entry has seven fields:
 

package/plugins/lisa-cursor/rules/project-learnings.mdc

@@ -6,11 +6,17 @@ alwaysApply: true
 # Project Learnings (load-bearing)
 
 Before normal task work, resolve this repository's committed `.lisa.config.json`
-and derive the canonical learnings file as the sibling of `projectRulesFile`
-(default: `.claude/rules/PROJECT_LEARNINGS.md`). If that file exists, consume it
-through the executable Lisa learnings contract exported by
-`@codyswann/lisa/learnings` before relying on ad-hoc memory or prior-session
-notes.
+and derive the machine-managed learnings ledger: the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives cold in
+`.lisa/`, NOT in an auto-loaded rules tree — so it is never injected raw into the
+session.
+
+Consume it ONLY through the executable Lisa learnings contract exported by
+`@codyswann/lisa/learnings`: parse and validate with `parseLearningsFile`, then
+take the bounded serving slice from `projectLearnings` (the highest-priority
+entries within the token/entry budget). **Never read the raw ledger file
+wholesale into context** — the whole point of the relocation is that sessions
+receive the contract's bounded projection, not the full file.
 
 Missing learnings are a silent no-op. Malformed, non-canonical, unsafe, or
 over-budget learnings produce one readable warning, apply no entry, and must not

package/plugins/lisa-cursor/skills/lisa-persist-learning/SKILL.md

@@ -139,7 +139,7 @@ Continue to Phase 3.
 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).
 
 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.
-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`):
+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):
 
    ```bash
    LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "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",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "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",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "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",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "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",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.242.0",
+  "version": "2.243.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/rules/eager/config-resolution.md

@@ -29,9 +29,12 @@ Project tracker (`jira` / `github` / `linear`) is read from `.lisa.config.json`
 
 Resolve hand-authored project rules from `.lisa.config.json`
 `projectRulesFile`, defaulting to `.claude/rules/PROJECT_RULES.md`. Automated
-learnings never append to that file: they use the separate
-`PROJECT_LEARNINGS.md` sibling derived from the configured rules directory.
-Both writers and budget checks import the executable contract from
+learnings never append to that file: they use the separate machine-managed
+ledger resolved from `.lisa.config.json` — the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives in the
+cold `.lisa/` tree (never an auto-loaded rules directory) and is consumed only
+through the contract's bounded projection, never read raw wholesale. Both
+writers and budget checks import the executable contract from
 `@codyswann/lisa/learnings`; they must not copy its numeric limits.
 
 ## Env → base branch

package/plugins/src/base/rules/eager/project-learnings.md

@@ -1,11 +1,17 @@
 # Project Learnings (load-bearing)
 
 Before normal task work, resolve this repository's committed `.lisa.config.json`
-and derive the canonical learnings file as the sibling of `projectRulesFile`
-(default: `.claude/rules/PROJECT_LEARNINGS.md`). If that file exists, consume it
-through the executable Lisa learnings contract exported by
-`@codyswann/lisa/learnings` before relying on ad-hoc memory or prior-session
-notes.
+and derive the machine-managed learnings ledger: the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives cold in
+`.lisa/`, NOT in an auto-loaded rules tree — so it is never injected raw into the
+session.
+
+Consume it ONLY through the executable Lisa learnings contract exported by
+`@codyswann/lisa/learnings`: parse and validate with `parseLearningsFile`, then
+take the bounded serving slice from `projectLearnings` (the highest-priority
+entries within the token/entry budget). **Never read the raw ledger file
+wholesale into context** — the whole point of the relocation is that sessions
+receive the contract's bounded projection, not the full file.
 
 Missing learnings are a silent no-op. Malformed, non-canonical, unsafe, or
 over-budget learnings produce one readable warning, apply no entry, and must not

package/plugins/src/base/rules/reference/config-resolution.md

@@ -179,7 +179,8 @@ fi
 |-------|----------|---------|-------|
 | `tracker` | **yes** | — | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing → fail with instruction to run the matching `/lisa:setup:*` skill. |
 | `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. |
-| `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. |
+| `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. |
+| `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. |
 | `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. |
 | `wiki` | no | — | Wiki location for the `wiki-knowledge-source` rule. Omit for a local in-repo wiki (`wiki/`). See **Wiki source** below. |
 

package/plugins/src/base/rules/reference/project-learnings.md

@@ -1,14 +1,21 @@
 # Project Learnings
 
-Project learnings are Lisa's bounded, repo-local memory surface. They are stored
-in `PROJECT_LEARNINGS.md`, derived as the sibling of the configured
-`.lisa.config.json` `projectRulesFile` value. With no config override, the path
-is `.claude/rules/PROJECT_LEARNINGS.md`.
-
-Consume learnings before normal task work whenever the file exists. Use the
-executable contract from `@codyswann/lisa/learnings` to parse, validate, and
-budget-check the document. Do not duplicate numeric caps in rules or prompts;
-the exported contract is the source of truth.
+Project learnings are Lisa's bounded, repo-local memory surface. The
+machine-managed ledger is `PROJECT_LEARNINGS.md`, resolved from
+`.lisa.config.json`: the optional `learnings.file` override, else the default
+`.lisa/PROJECT_LEARNINGS.md`. The ledger deliberately lives in the cold `.lisa/`
+directory — **not** under `.claude/rules/` or any other auto-loaded rules tree —
+because anything in those trees is injected raw into every session, which
+double-loads the file and bypasses the contract's budget and validation.
+
+Consume learnings before normal task work whenever the file exists, and consume
+them ONLY through the executable contract from `@codyswann/lisa/learnings`:
+`parseLearningsFile` to parse and validate, then `projectLearnings` to take the
+bounded serving slice (the highest-priority entries — ordered by confidence,
+then recency — that fit the token/entry budget, plus how many were omitted).
+**Never read the raw ledger file wholesale into context**; the session receives
+the bounded projection, not the full document. Do not duplicate numeric caps in
+rules or prompts; the exported contract is the source of truth.
 
 Each persisted entry has seven fields:
 

package/plugins/src/base/skills/lisa-persist-learning/SKILL.md

@@ -139,7 +139,7 @@ Continue to Phase 3.
 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).
 
 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.
-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`):
+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):
 
    ```bash
    LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')

package/scripts/check-learnings-budget.ts

@@ -14,8 +14,7 @@ const DEFAULT_LEARNINGS_FILE = path.resolve(
   "..",
   "all",
   "create-only",
-  ".claude",
-  "rules",
+  ".lisa",
   "PROJECT_LEARNINGS.md"
 );