@codyswann/lisa 2.351.0 → 2.353.0

package/plugins/lisa-cursor/agents/learnings-synthesizer.md

@@ -44,7 +44,7 @@ Map every finding to exactly one category. When a finding could fit two, pick th
 
 A finding that does not fit any of the eight is itself a signal — surface it under an additional ad-hoc category `Uncategorized` with a note explaining why no category fit. Better to surface than to drop.
 
-The destination column is a **hint for the human triaging the row**, not the routing decision: `lisa-debrief-apply` routes on the category, never on this column. Keep the hint honest anyway — a human decides Accept/Reject partly on where the learning will land. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the committed learnings ledger through the executable contract. Machine-local auto-memory (`project_*.md`, `MEMORY.md`), `PROJECT_RULES.md`, and `AGENTS.md` (whose `CLAUDE.md` is only a `@AGENTS.md` pointer) are **never** destinations — the first is invisible to cloud runs and teammates, and the latter two are human-authored surfaces that agents do not write.
+The destination column is a **hint for the human triaging the row**, not the routing decision: `lisa-debrief-apply` routes on the category, never on this column. Keep the hint honest anyway — a human decides Accept/Reject partly on where the learning will land. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the committed learnings ledger through the executable contract. Machine-local auto-memory (`project_*.md`, `MEMORY.md`), the host-rules directory `.agents/rules/`, and `AGENTS.md` (whose `CLAUDE.md` is only a `@AGENTS.md` pointer) are **never** destinations — the first is invisible to cloud runs and teammates, and the latter two are human-authored surfaces that agents do not write.
 
 ## Dedupe rules
 

package/plugins/lisa-cursor/agents/skill-evaluator.md

@@ -18,7 +18,7 @@ Rungs are ordered by context cost and enforcement strength. Decision vocabulary:
 | Rung | Recommendation | Destination | Enters context | Admission policy |
 | --- | --- | --- | --- | --- |
 | 6 | EXECUTABLE-CONTROL | Lint / ast-grep / type / test / hook / `package.lisa.json` force | Never — diagnostic fires on violation | Mechanically decidable + stable + recurred |
-| 5 | EAGER-RULE | Auto-loaded rules tree | Unconditionally, every session | **Earned by failure evidence** (repeated misses despite retrievability); demotion-biased |
+| 5 | EAGER-RULE | Host rules: `.agents/rules/` (project scope) · plugin `rules/eager/` (upstream scope) | Unconditionally, every session | **Earned by failure evidence** (repeated misses despite retrievability); demotion-biased |
 | 4 | SKILL | `.claude/skills/<name>/SKILL.md` | Description eager; body on invoke | Procedural, complex, recognizable trigger |
 | 3 | WIKI | Wiki page + index entry | Only when routed to | Durable reference knowledge |
 | 2 | KEEP-IN-LEDGER | `PROJECT_LEARNINGS.md` (bounded contract projection) | Bounded projection only | Default landing zone; probationary, expiring |

package/plugins/lisa-cursor/hooks/block-instruction-file-edits.sh

@@ -117,7 +117,7 @@ WHERE IT GOES INSTEAD — take the first one that fits:
    That is a project rule — but do not write it yourself. Capture it with
    \`/lisa:persist-learning\` so it lands in the learnings ledger with provenance
    and a confidence score. The gardener (\`/lisa:learnings:audit\`) then proposes
-   promotion into \`.claude/rules/PROJECT_RULES.md\` as a human-gated ticket.
+   promotion into the host-rules directory \`.agents/rules/\` as a human-gated ticket.
 
 2. It changes how an existing skill should behave. Edit that skill's SKILL.md.
    Knowledge belongs next to the procedure it modifies, not in a global preamble.

package/plugins/lisa-cursor/hooks/block-shell-json-parsing.sh

@@ -3,7 +3,7 @@
 # Text tools (grep/sed/cut/awk) break on valid JSON — multiline values, escaped
 # quotes, reordered keys, nested objects — producing silently wrong output
 # instead of errors. jq is the required tool for structural JSON reads and
-# writes in shell. Promoted from PROJECT_RULES.md prose to an executable
+# writes in shell. Promoted from host-rules prose to an executable
 # control by the learnings gardener (issue #1787).
 #
 # Precision-first: this hook fires only on high-confidence STRUCTURAL parsing

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

@@ -38,7 +38,6 @@ fi
 {
   "tracker": "jira",
   "source":  "notion",
-  "projectRulesFile": ".claude/rules/PROJECT_RULES.md",
 
   "atlassian":  { "cloudId": "<uuid>", "site": "<host>" },
   "jira": {
@@ -184,12 +183,21 @@ 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. Independent of the learnings ledger — relocating the rules file never moves the ledger. |
+| ~~`projectRulesFile`~~ | — | — | **Retired.** Host-authored rules now live in the fixed, agent-neutral directory `.agents/rules/` — not a configurable file. An existing key is still parsed and preserved so installed projects keep applying, but nothing serves rules from it. See **Host rules** below. |
 | `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. |
 | `health.schedule` | no | `off` | Health cadence contract: `off`, `daily`, or `weekly`. `lisa sync` populates the default with `_lisaSync.populated` provenance and rejects values outside this closed vocabulary. Runtime results live only at the gitignored `.lisa/health/latest.json`, never in either config file. |
 | `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. |
 
+### Host rules (`.agents/rules/`)
+
+Host-authored operating rules live in `.agents/rules/` — **fixed, not configurable**. One directory, every agent.
+
+- **Not a native auto-load tree.** `.claude/rules`, `.cursor/rules`, and `.github/instructions` are; `.agents/rules` deliberately is not. Every agent reaches it through the single Lisa-managed pointer block in `AGENTS.md` (Claude via the `@AGENTS.md` import in `CLAUDE.md`), so no agent loads host rules twice.
+- **Host-owned.** Lisa never writes rule bodies into `.agents/rules/`, and never edits or deletes a file there. Lisa's own rules originate in its plugins and arrive by their own route.
+- **Not the learnings ledger.** `.agents/rules` is reserved in the auto-loaded-tree blocklist, so a `learnings.file` override can never resolve inside it.
+- **Transition.** A project that still has the retired `.claude/rules/PROJECT_RULES.md` keeps it, untouched and authoritative. The pointer block names it so agents whose runtime does not auto-load `.claude/rules/` still find it. Moving that content is a human-gated decision, never an automated rewrite.
+
 ### Wiki source (`wiki`)
 
 Declares **where this repo's LLM Wiki lives** so the query/ingest skills can resolve and (for a remote wiki) mirror it. `wiki.source` has two shapes — **local** (`path`) and **remote** (`url`) — and the block belongs in the **consumer** repo's `.lisa.config.json`, not in `wiki/lisa-wiki.config.json` (which describes a wiki from the inside and is unavailable until a remote wiki is mirrored — chicken-and-egg). The whole `wiki` block is optional; omit it and the resolver falls back to the in-repo `wiki/` convention.
@@ -446,6 +454,13 @@ Every lifecycle skill operates on a fixed set of **roles** (`ready`, `claimed`,
 
 **`ready` must never resolve to the team's DEFAULT state.** `Todo` is where Linear puts a brand-new issue, so using it for `ready` inverts the gate: the lane stops meaning "a human flipped this to build-ready" and starts meaning "nobody has touched this". Measured on the first team migrated: 20 issues in the lane, only 8 ever explicitly marked ready. JIRA avoids this because `jira.workflow.ready` is a dedicated `Ready` status while a fresh ticket lands in the project default.
 
+**That rule is enforced, not merely stated — a correct default is only half the fix.** The default is `Ready`, but any project can override `linear.workflow.ready`, and an override reproduces the inversion exactly. Two arms catch it, deliberately split by what each can see:
+
+- **Static, always-on.** The queue-contract resolver refuses a `ready` naming a stock default created state (`Todo`, `To Do`, `Backlog`, `Triage`) and throws rather than resolving. It needs no network, so it runs everywhere, including offline and in CI. It cannot see a team that renamed its default.
+- **Live, authoritative.** `/lisa:validate-tracker-mapping` compares the configured `ready` against the team's real `defaultIssueState` (surfaced as `isTeamDefault` on `lisa-linear-access operation: list-workflow-states`) and classifies a match as `INVERTED` — never `VALID`, and never auto-repaired, because nothing records what lane the human meant instead.
+
+`INVERTED` is not a name-resolution failure; it is the opposite. The name resolves perfectly, which is precisely why every existence check passes while the gate runs backwards.
+
 **Linear state resolution is `type`-aware.** When a configured name is missing, a lifecycle skill may fall back to the team's states by `type` — `claimed`/`review` → the lowest-position `started`, `blocked` → `started` or `unstarted`, terminal `done` → `completed` — but only to *read*. **`ready` has no fallback on purpose:** every candidate would be the team's default unstarted state, which is exactly the inversion described above. A missing `ready` state is reported, never guessed; it must never invent a state to write into. Missing states are a setup defect, repaired by `/lisa:setup:linear`, not papered over at runtime.
 
 `blocked` is what every vendor agent flips to when triage finds unresolved ambiguities or the build path is blocked by something the agent can't resolve. Different from `claimed` because it explicitly signals "human attention required."

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

@@ -42,9 +42,12 @@ This is the shared slug for the config-bound-transitions policy (the `leaf-only-
 
 ## Project rules and learnings
 
-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 machine-managed
+Host-authored project rules live in the fixed, agent-neutral directory
+`.agents/rules/` — not a configurable file. Every agent reaches it through the
+Lisa-managed pointer block in `AGENTS.md`, so it is read once, on demand. A
+project that still carries the retired `.claude/rules/PROJECT_RULES.md` keeps
+it, untouched and authoritative; the pointer names it too. Automated
+learnings never append to host rules: 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

package/plugins/lisa-cursor/rules/intent-routing-reference.mdc

@@ -228,7 +228,7 @@ Sequence:
    - **PRD defect** — the ticket faithfully captured the PRD, but the PRD itself was wrong, ambiguous, or missing the failing case
    - **Missing tool access** — an agent lacked a tool, credential, environment, or permission the work required
 
-   The three knowledge categories (recurring gotcha, process friction, convention drift) persist to the committed learnings ledger through the executable contract — never to machine-local memory, `PROJECT_RULES.md`, or `AGENTS.md`.
+   The three knowledge categories (recurring gotcha, process friction, convention drift) persist to the committed learnings ledger through the executable contract — never to machine-local memory, host rules (`.agents/rules/`), or `AGENTS.md`.
 4. **Produce the human-triage document** — a markdown file with one row per candidate learning showing: category, summary, evidence (links to the source ticket comment / PR comment / commit), recommended persistence destination, and a checkbox-style disposition field the human will mark (Accept / Reject / Defer). Surface step-1 anomalies (work items missing PRs, etc.) in a separate section. The document is exhaustive — it lists every candidate, even ones the synthesizer rates low confidence — because the human, not the agent, decides what is worth keeping.
 5. **Record Debrief usage on the triage document** — invoke `lisa-usage-accounting` against the generated markdown artifact so the document carries its own direct `debrief` usage entry in the canonical `## Lisa Usage` section. If runtime usage is unavailable, write the entry with `source: unavailable` and nullable token/cost fields rather than skipping it.
 6. **Stop and hand the document to the human.** Debrief does NOT persist accepted learnings itself. The human triages, marks dispositions, and runs the **`/lisa:debrief:apply`** command (skill: `debrief-apply`) to route the accepted items to their destinations.

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

@@ -39,7 +39,7 @@ Each persisted entry has seven fields:
 
 - 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
+  It is capture-only: it never appends to host rules, creates skills, or
   files upstream issues — promotion is the gardener's ticket-gated job.
 - **`lisa-debrief-apply`** routes accepted debrief findings in the three
   knowledge categories — recurring gotcha, process friction, convention drift —
@@ -47,7 +47,8 @@ Each persisted entry has seven fields:
   `persistConsolidatedLearning`, with consolidation-at-write), provenance drawn
   from the triage row's evidence links and a `high` starting confidence because
   a human Accept is corroboration. It no longer writes to machine-local memory,
-  `PROJECT_RULES.md`, or `AGENTS.md` (the human-authored source of truth, of
+  the host-rules directory `.agents/rules/` (or a surviving legacy
+  `PROJECT_RULES.md`), or `AGENTS.md` (the human-authored source of truth, of
   which `CLAUDE.md` is only a `@AGENTS.md` pointer) for these categories.
 - The **build-intake flows** advance `last_confirmed` at claim time
   (`confirmLearningEntry`, below).
@@ -82,9 +83,10 @@ warning, apply no entry, and do not block unrelated work.
 Precedence:
 
 1. System, developer, user, and repo instructions still outrank learnings.
-2. Committed project rules remain durable human-authored guidance.
+2. Committed host rules (`.agents/rules/`) remain durable human-authored
+   guidance.
 3. Project learnings add recent operational knowledge, but never rewrite or
-   append to `PROJECT_RULES.md`.
+   append to host rules.
 
 ## Task telemetry (MLD) is not context
 

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

@@ -20,7 +20,8 @@ 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
-block unrelated task work. Never append automated learnings to
-`PROJECT_RULES.md`; project learnings are a separate machine-managed document.
+block unrelated task work. Never append automated learnings to host rules
+(`.agents/rules/`, or a surviving legacy `PROJECT_RULES.md`); project learnings
+are a separate machine-managed document.
 
 Full prose: [reference/project-learnings.md](project-learnings-reference.mdc).

package/plugins/lisa-cursor/rules/promotion-contract-reference.mdc

@@ -126,6 +126,7 @@ and lets reviewers diff against a single source of truth.
 - **The gardener** (`lisa-learnings-audit`): embeds the AC template above into
   EXECUTABLE-CONTROL promotion tickets and applies the eager-tier admission
   policy when auditing.
-- **PROJECT_RULES.md owners**: that file is human-authored only; machine
+- **Host-rules owners** (`.agents/rules/`, plus any surviving legacy
+  `PROJECT_RULES.md`): that surface is human-authored only; machine
   writes go to the learnings ledger, and promotions out of it arrive as
   gardener tickets governed by this contract.

package/plugins/lisa-cursor/scripts/queue-contract-resolution.mjs

@@ -32,6 +32,24 @@ const DEFAULT_LINEAR_BUILD_DONE = {
   production: "Done",
 };
 
+// The state names a stock Linear team creates brand-new Issues into. `ready`
+// must name a lane a human moves an Issue INTO, so it may never be one of
+// these: the claimable lane would stop meaning "a human flipped this to
+// build-ready" and start meaning "nobody has touched this", and build-intake
+// would dispatch work nobody approved.
+//
+// This list is a STATIC backstop for the stock names, which is the case that
+// actually bit us. It cannot see a team that renamed its default — only the
+// live `Team.defaultIssueState` can, which is why `/lisa:validate-tracker-mapping`
+// carries the authoritative arm (`INVERTED`) and this one carries the arm that
+// needs no network and therefore always runs.
+const LINEAR_STOCK_DEFAULT_CREATED_STATES = [
+  "todo",
+  "to do",
+  "backlog",
+  "triage",
+];
+
 const DEFAULT_GITHUB_LINEAR_PRD_ROLES = {
   draft: "prd-draft",
   ready: "prd-ready",
@@ -272,6 +290,35 @@ export function resolvePrdLifecycleRoles(
   }
 }
 
+/**
+ * Reject a Linear `ready` override that names a state a stock team creates
+ * brand-new Issues into.
+ *
+ * Failing loudly is the safe direction. An operator staring at a hard error has
+ * a broken queue; an operator with a silently inverted gate has agents shipping
+ * work no human approved, which is the failure mode that produced this guard.
+ *
+ * @param {string} configured The resolved `linear.workflow.ready` name.
+ * @returns {string} The same name, once it is proven not to be a default lane.
+ * @throws {Error} When the name is a stock default created state.
+ */
+function assertLinearReadyIsNotDefaultState(configured) {
+  const normalized = configured.trim().toLowerCase();
+
+  if (!LINEAR_STOCK_DEFAULT_CREATED_STATES.includes(normalized)) {
+    return configured;
+  }
+
+  throw new Error(
+    `linear.workflow.ready is set to "${configured.trim()}", which is where Linear puts a ` +
+      "brand-new Issue. That inverts the build-ready gate: the claimable lane would mean " +
+      '"nobody has touched this" instead of "a human marked this ready", so intake would ' +
+      "claim untouched backlog items. Point linear.workflow.ready at a dedicated state a " +
+      "human moves Issues into (the default is `Ready`), then re-run /lisa:setup:linear to " +
+      "create it if the team does not have one."
+  );
+}
+
 /**
  * Resolve the build lifecycle roles for the configured tracker vendor.
  *
@@ -307,7 +354,9 @@ export function resolveBuildLifecycleRoles(
         vendor: "linear",
         kind: "workflow",
         roles: {
-          ready: config.linear?.workflow?.ready || "Ready",
+          ready: assertLinearReadyIsNotDefaultState(
+            config.linear?.workflow?.ready || "Ready"
+          ),
           claimed: config.linear?.workflow?.claimed || "In Progress",
           review: config.linear?.workflow?.review || "In Review",
           blocked: config.linear?.workflow?.blocked || "Blocked",

package/plugins/lisa-cursor/skills/lisa-debrief/SKILL.md

@@ -72,7 +72,7 @@ A markdown triage document at `./debrief/<initiative-slug>-<YYYY-MM-DD>.md` (or
    - `Summary` — one sentence
    - `Category`
    - `Evidence` — links to the source ticket comment / PR comment / commit / test file (multiple allowed)
-   - `Recommended persistence destination` — the agent's best guess for where this should land if accepted (e.g., "Edge Case Brainstorm checklist → Navigation & URL state", "learnings ledger via the executable contract", "new tooling-gap ticket", "upstream Lisa issue"). Never name machine-local auto-memory, `PROJECT_RULES.md`, or `AGENTS.md` — those are not persistence destinations.
+   - `Recommended persistence destination` — the agent's best guess for where this should land if accepted (e.g., "Edge Case Brainstorm checklist → Navigation & URL state", "learnings ledger via the executable contract", "new tooling-gap ticket", "upstream Lisa issue"). Never name machine-local auto-memory, the host-rules directory `.agents/rules/`, or `AGENTS.md` — those are not persistence destinations.
    - `Disposition` — empty checkbox-style field the human will fill: `[ ] Accept` / `[ ] Reject` / `[ ] Defer` plus a free-text reason
 4. **Source map** — appendix listing every work item and PR walked, so the human can verify completeness.
 

package/plugins/lisa-cursor/skills/lisa-debrief-apply/SKILL.md

@@ -18,7 +18,7 @@ A path or URL to a Debrief triage document produced by `lisa-debrief`. The docum
 
 1. **Verify the doc exists and parses.** If the file cannot be read or the expected sections are missing, stop and report — do not guess.
 2. **Confirm dispositions exist.** If every row is unmarked, stop and ask the human to triage first. A pristine doc is a no-op, not an error to silently swallow.
-3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), the committed learnings ledger path (resolve it — never hardcode — via `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md`), tracker for new tickets. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the ledger now; machine-local auto-memory and `PROJECT_RULES.md` / `AGENTS.md` are no longer knowledge destinations (see [Ledger persistence](#ledger-persistence-knowledge-categories)).
+3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), the committed learnings ledger path (resolve it — never hardcode — via `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md`), tracker for new tickets. The three knowledge categories (recurring gotcha, process friction, convention drift) all land in the ledger now; machine-local auto-memory and host rules (`.agents/rules/`) / `AGENTS.md` are no longer knowledge destinations (see [Ledger persistence](#ledger-persistence-knowledge-categories)).
 
 ## Routing rules
 
@@ -61,13 +61,13 @@ For each such Accepted row:
    - `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`).
    - `confidence` = **`high`**. A human marking the row **Accept** is corroboration — an independent human judgement that the learning is real — so a debrief-accepted entry starts higher than the learner's single-occurrence auto-capture (which defaults to `low`). The writer re-asserts the entry and token budgets; an over-budget failure means consolidate harder or drop, never truncate by hand.
 
-**Machine-local memory is no longer a knowledge destination.** Auto-memory (`project_*.md`, `MEMORY.md`) remains available only for the assistant's *personal* collaboration notes — it is invisible to cloud runs and to teammates, so it can never hold shared project knowledge. **`AGENTS.md` is human-authored** agent operating instruction — it is the source of truth, and `CLAUDE.md` is only a one-line `@AGENTS.md` pointer — and `PROJECT_RULES.md` is durable human-authored guidance; `apply` never writes to any of the three for these categories.
+**Machine-local memory is no longer a knowledge destination.** Auto-memory (`project_*.md`, `MEMORY.md`) remains available only for the assistant's *personal* collaboration notes — it is invisible to cloud runs and to teammates, so it can never hold shared project knowledge. **`AGENTS.md` is human-authored** agent operating instruction — it is the source of truth, and `CLAUDE.md` is only a one-line `@AGENTS.md` pointer — and the host-rules directory `.agents/rules/` is durable human-authored guidance; `apply` never writes to any of the three for these categories.
 
 ## Idempotency
 
 `apply` is safe to re-run. Each Accepted row carries an evidence link that doubles as a fingerprint. Before writing, check whether the destination already cites that fingerprint:
 
-- **Knowledge categories (gotcha, friction, drift) → ledger.** Parse the ledger once with `parseLearningsFile` from `@codyswann/lisa/learnings` and scan the entries' `provenance` for the row's evidence link. If any entry's provenance already contains it, the row is already persisted — skip the write. This replaces the old scattered-file greps (memory files, `PROJECT_RULES.md`, `AGENTS.md`): provenance in the single governed ledger is now the one fingerprint surface.
+- **Knowledge categories (gotcha, friction, drift) → ledger.** Parse the ledger once with `parseLearningsFile` from `@codyswann/lisa/learnings` and scan the entries' `provenance` for the row's evidence link. If any entry's provenance already contains it, the row is already persisted — skip the write. This replaces the old scattered-file greps (memory files, host rules, `AGENTS.md`): provenance in the single governed ledger is now the one fingerprint surface.
 - **Other categories** keep their existing destination check (the tracker for the ticket marker, the PRD for the defect comment, `intent-routing.md` for the edge-case citation).
 
 If the fingerprint is already present, skip the write and note the row as `already-applied` in the run summary. This lets the human triage a doc incrementally (mark a few, run apply, mark more, run apply again) without producing duplicates.

package/plugins/lisa-cursor/skills/lisa-doctor/SKILL.md

@@ -56,7 +56,10 @@ as applicable to the current repo:
    and `source` only. If a required CLI, MCP surface, or auth context is unavailable in the current
    runtime, report that explicitly instead of pretending the repo is ready.
 4. **Runtime distribution surfaces** — confirm the command, skill, hook, and related distribution
-   surfaces relevant to this repo are present where Lisa expects them on the active runtime.
+   surfaces relevant to this repo are present where Lisa expects them on the active runtime, and
+   that the Lisa-owned enforcement artifacts (`scripts/lisa-hooks/*`,
+   `scripts/lisa-enforcement-fallback.sh`) match the installed Lisa version rather than an older
+   copy. Present-but-stale is a finding: a guard whose fix never landed enforces the old behavior.
 5. **Automation readiness** — inspect whether the configured queue source/tracker and scheduling
    prerequisites are observable, but do **not** create, edit, or delete automations during doctor.
 6. **Optional GitHub Project coordination** — when `github.projects.v2` is configured, delegate

package/plugins/lisa-cursor/skills/lisa-improve-harness/SKILL.md

@@ -341,7 +341,7 @@ Any durable lesson the loop produced is **submitted** to `lisa-persist-learning`
 only write path per the `project-learnings` rule) as a candidate; its hostile-default judge — not
 this skill, and not the caller — decides the disposition. A dropped candidate is recorded in
 `Known limits`, never reported as routed or owned. This skill never writes the learnings file,
-`PROJECT_RULES.md`, or `CLAUDE.md` itself, and never promotes a learning to a higher rung (that
+host rules (`.agents/rules/`), or `CLAUDE.md` itself, and never promotes a learning to a higher rung (that
 is the gardener's ticket-gated job).
 
 ## Idempotency
@@ -483,5 +483,5 @@ its face, because a single-trajectory loop always has limits.
 - **Bounded claims.** One trajectory supports one trajectory's claim. No comparative,
   longitudinal, or population claims; `Known limits` is never empty.
 - **One write path for learnings.** Durable lessons are submitted to `lisa-persist-learning` for
-  judgment; this skill never edits the learnings ledger, `PROJECT_RULES.md`, or a rules tree,
+  judgment; this skill never edits the learnings ledger or any rules tree (host `.agents/rules/` included),
   and never promotes a learning to a higher rung.

package/plugins/lisa-cursor/skills/lisa-learnings-audit/SKILL.md

@@ -49,9 +49,12 @@ memorized list:
    — stronger than an omission count, because room was not merely tight, a real
    capture was turned away. Drain it every run (see The audit cycle).
 3. **Rules trees** — the plugin `rules/eager/` + `rules/reference/` pairs AND
-   the host project's `.claude/rules/` (e.g. `PROJECT_RULES.md`, which is
-   human-authored only — its existing sections are still audit candidates;
-   first-run candidates come from exactly there).
+   the host project's canonical host-rules directory `.agents/rules/`, plus any
+   retired-but-surviving single-file rules the project still carries
+   (`.claude/rules/PROJECT_RULES.md`, or a legacy `projectRulesFile` path).
+   All of it is human-authored only — the gardener proposes, it never rewrites —
+   and its existing sections are still audit candidates; first-run candidates
+   come from exactly there.
 4. **Skills** — `.claude/skills/` and the plugin skill roots the runtime
    exposes (descriptions are eager context; bodies load on invoke).
 5. **The wiki index** — `wiki/index.md` when the project has a wiki.

package/plugins/lisa-cursor/skills/lisa-linear-access/SKILL.md

@@ -106,6 +106,40 @@ linear_graphql() {
 Map operation names to Linear GraphQL queries/mutations in this access skill.
 Consumers pass business-shaped arguments only; they do not embed GraphQL.
 
+## `list-workflow-states` — the team's states, and which one it creates into
+
+`list-workflow-states team:<ID>` returns one node per state with `id`, `name`,
+`type`, `position`, and **`isTeamDefault`**.
+
+`isTeamDefault` is `true` for the single state named by the team's
+`defaultIssueState` — where Linear puts every brand-new Issue. Callers need it to
+enforce the rule that `linear.workflow.ready` must be a lane a human moves an
+Issue **into**: pointing `ready` at the default inverts the gate, so the
+claimable lane means "nobody has touched this" rather than "a human marked this
+ready", and build-intake dispatches unapproved work. `/lisa:setup:linear` refuses
+to resolve `ready` onto it, and `/lisa:validate-tracker-mapping` classifies a
+config that already does as `INVERTED`.
+
+It belongs on this operation rather than in a separate `get-team` call because
+every caller that needs it is already enumerating states, and a second round trip
+is a second chance for the two answers to disagree. A team with no
+`defaultIssueState` set yields `isTeamDefault: false` on every node — report that
+honestly; do not fall back to guessing by name or position.
+
+```graphql
+query($teamId:String!){
+  team(id:$teamId){
+    defaultIssueState{ id }
+    states(first:100){ nodes{ id name type position } }
+  }
+}
+```
+
+Set `isTeamDefault` per node by comparing `node.id` against
+`team.defaultIssueState.id`. On the MCP substrate, which exposes states without
+the team's default, resolve the default through the team record and join on `id`
+the same way.
+
 ## `history` — transition history (read-only)
 
 `history id:<ID>` returns an Issue's ordered past state changes — the raw

package/plugins/lisa-cursor/skills/lisa-validate-tracker-mapping/SKILL.md

@@ -71,7 +71,8 @@ Resolve the **effective** role → name mapping using the same defaults `/lisa:i
 - **Missing / empty tracker**: report `UNRESOLVABLE` with setup guidance (`/lisa:setup:jira`, `/lisa:setup:github`, or `/lisa:setup:linear`). Do not default to JIRA.
 - **JIRA build workflow** (`jira.workflow`): `ready`, `claimed`, optional `review`, `blocked`, and each `done.<env>` (`dev` / `staging` / `production`). Defaults: `Ready`, `In Progress`, `Code Review`, `Blocked`, `{dev: "On Dev", staging: "On Stg", production: "Done"}`.
 - **GitHub build/prd labels** (`github.labels.build`, `github.labels.prd`): each configured label string.
-- **Linear build/prd labels** (`linear.labels.build`, `linear.labels.prd`): each configured label/state string.
+- **Linear build workflow** (`linear.workflow`): `ready`, `claimed`, `review`, `blocked`, and each `done.<env>` — native workflow **states**, the Linear analogue of `jira.workflow`, not of `github.labels`. Defaults: `Ready`, `In Progress`, `In Review`, `Blocked`, `{dev: "On Dev", staging: "On Stg", production: "Done"}`.
+- **Linear labels** (`linear.labels`): the `prd.*` map plus the one surviving build-lane key, the `human_needed` marker (`linear.labels.build.human_needed`). A config that predates the state model may still carry `ready` / `claimed` / `blocked` / `done` under `linear.labels.build`; those are **inert** — nothing reads them. Do not audit them against the live label set, and do not report them as drift. Report them once as a migration note pointing at `/lisa:setup:linear`, which removes them.
 - **Notion PRD values** (`notion.values`): each configured select-option value, validated against the `notion.statusProperty` property's options.
 - **Confluence PRD parents** (`confluence.parents`): each configured parent page id, validated by existence.
 
@@ -103,7 +104,9 @@ gh label list --repo "$REPO" --limit 200 --json name -q '.[].name'
 
 ### Linear / Notion / Confluence
 
-Enumerate via the corresponding access surface (Linear MCP workflow states + labels; Notion data-source select options for `notion.statusProperty`; Confluence page-exists check per parent id). Same compare-exact-case contract as JIRA.
+Enumerate via the corresponding access surface (`lisa-linear-access` workflow states + labels; Notion data-source select options for `notion.statusProperty`; Confluence page-exists check per parent id). Same compare-exact-case contract as JIRA.
+
+For Linear, `lisa-linear-access operation: list-workflow-states` returns each state's `name`, `type`, `position` and `isTeamDefault` (the access layer sets it from the team's `defaultIssueState`). **Keep `isTeamDefault`** — Step 4 needs it, and it is the only authoritative answer to "which state does this team create Issues into". Do not approximate it with a name guess: `Todo` is merely the stock name, and a team that renamed its `defaultIssueState` is exactly the case a name guess misses.
 
 ## Step 4 — Compare (exact case)
 
@@ -113,10 +116,14 @@ For each `(role, configured-name)` pair, classify against the live name set:
 - **CASE_DRIFT** — a case-insensitive match exists but no exact-case match (e.g. config `"On Stg"` vs live `"ON STG"`). Canonical = the live exact name.
 - **MISSING** — no case-insensitive match exists. The name was renamed beyond recognition or deleted.
 
+One role carries a further check that name-existence cannot express:
+
+- **INVERTED** — Linear only, `ready` only: the configured state exists, but it is the team's **default created state** (`isTeamDefault`). This is worse than a name that does not resolve. The name resolves perfectly, so every existence check passes while the gate runs backwards: `ready` is supposed to mean "a human moved this Issue here", and the team's default means "nobody has touched this". Build-intake claims from that lane, so an INVERTED mapping dispatches work no human ever approved. Measured on the first team it hit: 20 Issues in the claimable lane, 12 never marked ready — including decision tickets shaped like leaves, which the leaf-only gate cannot catch either. Report it even when every other role is VALID.
+
 A project's verdict:
 
 - **VALID** — every role is VALID.
-- **DRIFTED** — at least one CASE_DRIFT or MISSING role, none of which is UNRESOLVABLE.
+- **DRIFTED** — at least one CASE_DRIFT, MISSING, or INVERTED role, none of which is UNRESOLVABLE. An INVERTED `ready` is never VALID, no matter how cleanly it resolves.
 - **UNRESOLVABLE** — the live set couldn't be enumerated (auth mismatch, missing tracker config, access failure). Distinguish this loudly from VALID — an unresolved audit is not a passing audit.
 
 ## Step 5 — Report
@@ -134,7 +141,17 @@ Per project, print a terminal-first section:
   done.production Done              Done                VALID
 ```
 
-End with a roll-up: counts of VALID / DRIFTED / UNRESOLVABLE projects and the exact next command (`… repair=true` when drift is auto-repairable; an admin note when a status is genuinely MISSING).
+An INVERTED `ready` gets a full line rather than a one-word status, because the operator reading it is not necessarily an engineer and the word alone does not convey the stakes:
+
+```
+  ready           Todo              Todo                INVERTED
+      "Todo" is the state this Linear team puts every NEW issue into, so the
+      build queue is currently claiming issues nobody marked ready. Pick or
+      create a state a person moves an issue into (Lisa's default is "Ready")
+      via /lisa:setup:linear, then set linear.workflow.ready to it.
+```
+
+End with a roll-up: counts of VALID / DRIFTED / UNRESOLVABLE projects and the exact next command (`… repair=true` when drift is auto-repairable; an admin note when a status is genuinely MISSING; `/lisa:setup:linear` when a `ready` is INVERTED).
 
 ## Step 6 — Repair (only when `repair=true`)
 
@@ -166,6 +183,18 @@ Compute the closest live candidates (case-insensitive token/substring overlap, t
 
 Only write on an explicit pick. Never auto-select. If the user leaves it unchanged, keep the project `DRIFTED` and surface the admin remediation (add the status back, or fix it in the tracker).
 
+### INVERTED — never auto-repair
+
+**Never auto-repair an INVERTED `ready`, even with `repair=true`.** Every other classification has one correct answer that the live tracker already knows: CASE_DRIFT has the canonical casing, MISSING has a shortlist of near-matches. INVERTED has neither. The configured name is live and correctly cased; what is wrong is which lane the project chose to mean "build-ready", and nothing in the config or the tracker records what the human intended instead. Guessing would silently repoint the queue at a lane that may hold nothing, or worse, at another lane the team fills automatically — swapping one wrong answer for a quieter one.
+
+The team may also genuinely not have a dedicated ready lane yet, in which case the repair is to **create a state**, not to rewrite a string — `/lisa:validate-tracker-mapping` audits config, it does not mutate the tracker.
+
+So: present the team's non-default states via `AskUserQuestion`, and write `linear.workflow.ready` only on an explicit pick. If none fits, or the user declines, leave the config untouched, keep the project `DRIFTED`, and hand off:
+
+> Linear has no dedicated build-ready state on this team. Run `/lisa:setup:linear` — it offers to create `Ready` and records the mapping.
+
+Until then, say plainly that the build queue is claiming unapproved work and that pausing build intake is the safe interim.
+
 ### Invalidate the verification cache
 
 After any JIRA repair, clear the `setup-jira` reachability cache so it re-verifies the new mapping:

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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.351.0",
+  "version": "2.353.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"