@codyswann/lisa 4.54.13 → 4.55.0

package/plugins/src/base/skills/lisa-repair-intake/SKILL.md

@@ -188,6 +188,7 @@ In addition to the lifecycle roles above, the build lifecycle defines the **`hum
 
 - The blocks repair-intake **itself writes** are the auto-recoverable kind — it files a build-ready fix ticket and moves the item `blocked` *blocked by that ticket*, expecting the next cycle to self-heal. Those are **not** `human_needed`; if such an item arrives carrying a `human_needed` marker **this skill applied on an earlier cycle**, repair-intake **clears** it (the block is no longer waiting on a human).
 - **Never remove a `human_needed` marker this skill did not apply.** "Stale" is a judgment about the block's kind, not about who applied the marker or when — so without this rule an operator's deliberate hold, applied *after* correcting a wrong transition, is indistinguishable from a leftover the sweep is designed to clear, and gets swept. Establish provenance from the label event's actor (`rejection-detection` **Automation-reversal memory** reads the same surfaces); if provenance is not readable, **leave the marker in place**. Removing a human's hold is unrecoverable within the loop; leaving a stale one costs a cycle and is visible.
+- **The one exception is a hold that has recorded its own discharge.** A `[lisa-human-gate-release]` comment naming the hold's `reason=` is not a guess about provenance — it is the hold's stated void condition, recorded on the item by the person who answered it. Clearing the marker there is not overriding a human's judgment; it is *enacting* it. That is the whole of the exception: no other reading of "this looks stale" reopens the question above, and an item whose release cannot be read stays held. See "Release the holds that have been answered" below (#3852).
 - The marker is consulted **before **any** repair transition**, not only before Class C. Class C's hard stop is the strictest reading of it, but a marker that is honoured on one classification path and ignored on the other three is not a guard — and Class A, dependency clearing, is exactly the path an operator reverting a wrongly-cleared blocker is trying to protect. Match it robustly (hyphen/underscore, case-insensitive, label set and note prose) wherever it is read.
 - The blocks the **vendor agent** writes when repair-intake re-dispatches it (its pre-flight gate) carry `human_needed` already — the agent owns that marker. repair-intake leaves it in place.
 
@@ -218,7 +219,7 @@ intakes use. Never call Atlassian MCP or `acli` directly — go through `lisa-at
 | Linear (build) | Linear MCP `list_issues` / `get_issue` / `list_comments` | Linear MCP `save_issue` (labels) / `save_comment` | `lisa-linear-agent` |
 | Notion (PRD) | `lisa-notion-access` (`query`, page comments) | `lisa-notion-access` `write-page` (status) / page comment | `lisa-notion-to-tracker` (dry-run) |
 | GitHub (PRD) | `gh issue list/view` (PRD labels) / GraphQL sub-issues / generated-work section | `gh issue edit` / `gh issue comment` / `gh issue close --reason completed` | `lisa-github-to-tracker` (dry-run) |
-| Linear (PRD) | Linear MCP `list_projects` / `get_project` (+ sentinel feedback issue) | Linear MCP `save_project` (labels) / `save_comment` | `lisa-linear-to-tracker` (dry-run) |
+| Linear (PRD) | `lisa-linear-access` `list-projects` / `get-project` / `list-comments project_id` | `lisa-linear-access` `save-project` (labels) / `save-comment project_id` | `lisa-linear-to-tracker` (dry-run) |
 | Confluence (PRD) | `lisa-atlassian-access` CQL | `lisa-atlassian-access` page `parentId` update / comment | `lisa-confluence-to-tracker` (dry-run) |
 
 ## Staleness model
@@ -267,8 +268,9 @@ exposes, and compare it to `now - stale_after`:
 1. Provider-native status/label **transition** time into the in-progress role, when the provider
    exposes it cleanly (JIRA changelog transition to `claimed` / In Progress, GitHub label event,
    Linear state/label history, Notion/Confluence page move/status history).
-2. Latest human lifecycle/progress **comment** or edit on the item (and, for Linear PRDs, the
-   sentinel feedback issue). Exclude automation self-comments and Lisa audit markers such as
+2. Latest human lifecycle/progress **comment** or edit on the item (for Linear PRDs, the
+   project's own comments via `list-comments project_id`, plus any legacy sentinel feedback
+   issue for projects that predate project-level comments). Exclude automation self-comments and Lisa audit markers such as
    `[claude-build-intake]`, `[codex-build-intake]`, `[lisa-build-intake]`, and
    `[lisa-repair-intake]`.
 3. For build items, latest **PR-side forward-progress activity** on the linked PR: newest commit,
@@ -466,25 +468,49 @@ branch — operate on it the same way.
 
 **4. Classify as a blocker.** Treat any of these as a real external blocker:
 
-- **True merge conflict** — `gh pr update-branch` (step 3) reported a conflict, or
-  `git merge-tree --write-tree origin/<base> <head>` exits non-zero. A
-  merely `BEHIND` branch is **not** here — it was re-synced in step 3. Unlike the other classes below, a
-  conflict is **resolvable by re-running the build**, so step 5 gives it one in-place re-dispatch before
-  filing — see its conflict-first rule.
-
-  **`mergeable = CONFLICTING` and `mergeStateStatus = DIRTY` are hints that
-  START this check, never the verdict that ends it.** Both are cached
-  computations that go stale — measured, GitHub reported `DIRTY` for two
-  branches at the same moment while only one actually conflicted, and a single
-  response has carried `MERGEABLE` and `DIRTY` together
-  (CodySwannGT/lisa#3694). Confirm with `merge-tree` before classifying, and
-  say in the run summary which answer you acted on.
-
-  **This class matters more here than in `lisa-drive-pr-to-merge`.** There a
-  spurious `DIRTY` costs a wasted resolve, which a human sees. Here it files a
-  BLOCKER against a pull request with nothing wrong with it, unattended — so
-  the wrong answer becomes durable tracker state that a later cycle reads as
-  fact. Verify before filing, never after.
+- **True merge conflict** — confirmed by a **merge trial**, never by a cached field.
+  `mergeable = CONFLICTING` and `mergeStateStatus = DIRTY` are hints that say *go look*: both are
+  computed asynchronously, and a stale one is served often enough that GitHub reported `DIRTY` for two
+  branches at the same moment while only one of them actually conflicted (#3694). Re-derive from
+  primary evidence at the moment of asking:
+
+  ```sh
+  base=$(gh pr view <pr> --json baseRefName --jq .baseRefName)
+  head=$(gh pr view <pr> --json headRefOid --jq .headRefOid)
+  git fetch --quiet origin "$base" "pull/<pr>/head" || readable=no
+  git rev-parse --verify --quiet "origin/$base^{commit}" >/dev/null || readable=no
+  git rev-parse --verify --quiet "$head^{commit}" >/dev/null || readable=no
+  out=$(git merge-tree --write-tree "origin/$base" "$head" 2>/dev/null); code=$?
+  ```
+
+  `merge-tree --write-tree` merges into the object store only — no working tree, no index and no
+  branch is touched — so it is safe inside an unattended scanner.
+
+  **Read the exit code together with stdout; the exit code alone cannot separate the three states.**
+  Measured on git 2.53.0: a trial naming a ref that does not exist exits `1`, the same code a genuine
+  conflict returns, printing nothing on stdout and `merge-tree: <ref> - not something we can merge`
+  on stderr. A trial that ran always prints the resulting tree OID on its first line; one that could
+  not run prints nothing. Three states, and the third is not optional:
+
+  - `code == 1` **and** `$out` non-empty → **CONFLICTED**. A real external blocker. Unlike the other
+    classes below, a conflict is **resolvable by re-running the build**, so step 5 gives it one
+    in-place re-dispatch before filing — see its conflict-first rule.
+  - `code == 0` → **CLEAN**. Not a blocker, whatever the API said. Write nothing, leave the item
+    `claimed`, and let a later cycle re-ask.
+  - `readable=no`, `$out` empty, or any other exit → **NOT DETERMINED**. The trial could not run — an
+    unresolvable ref, an unreachable remote, a git older than 2.38 — which is an absence of evidence,
+    not a verdict. Write nothing, file nothing, leave the item `claimed`, and record it as
+    `not_determined` in the run summary so a later cycle re-asks.
+
+  A `gh pr update-branch` (step 3) that reported a conflict it cannot apply also counts as
+  CONFLICTED — that is a merge actually attempted, not a cached answer. A merely `BEHIND` branch is
+  **not** here — it was re-synced in step 3.
+
+  **Filing on a cached field is the expensive direction here.** In a fix-mode loop a false
+  CONFLICTED wastes a resolve, which a human sees; in this scanner it files a
+  BLOCKER against a pull request that has nothing wrong with it, unattended — so the wrong answer
+  becomes durable tracker state that a later cycle reads as fact, and intake will keep doing that
+  without anyone noticing. Verify before filing, never after.
 - **Failing required checks** — `statusCheckRollup` has a `FAILURE`/`ERROR`/`TIMED_OUT` conclusion,
   or `mergeStateStatus = UNSTABLE`/`BLOCKED` due to checks.
 - **Change requests outstanding** — `reviewDecision = CHANGES_REQUESTED`, or unresolved CodeRabbit
@@ -905,8 +931,8 @@ intake runs per item**, targeted at this single PRD and **skipping the claim** (
 ### PRD `blocked` → re-validate if new answers exist
 
 1. Determine whether **new clarifying answers** exist: any comment/update on the PRD newer than
-   the last `[lisa-repair-intake]` note or the original `blocked` note. For Linear include the
-   sentinel feedback issue and anchored sub-issue comments; for Confluence include inline/footer
+   the last `[lisa-repair-intake]` note or the original `blocked` note. For Linear include the project's own
+   comments, anchored sub-issue comments, and any legacy sentinel feedback issue; for Confluence include inline/footer
    comments where the access layer exposes them; for Notion include page comments and
    `last_edited_time`.
 2. If new answers exist → run the `lisa:<source>-to-tracker` dry-run validate→route pipeline as
@@ -1023,6 +1049,50 @@ with labels like `build-ready`, or with no Lisa status label at all, that are in
    substring match whose precision is a separate open defect (#3815). Refusing and reporting is
    the safe failure direction without the latch. Count these under `held_for_person`, never under
    `normalized_ready`.
+
+   **Pass the item's `comments`.** The planner reads a recorded `[lisa-human-gate-release]` comment
+   as the discharge of the hold naming the same `reason=`, and an item read without its comments is
+   an item whose discharge cannot be seen. That fails closed — it stays held — which is the safe
+   direction and precisely why the omission is invisible.
+
+2b. **Release the holds that have been answered.** This is step 2a's inverse and it is the reason
+   this sweep is where it lives: applying a hold had a path and lifting one had none, so a person
+   could supply exactly what a held item asked for, record the decision on the item, and the item
+   stayed held forever (CodySwannGT/lisa#3852). The expensive part — getting a person's attention,
+   framing the question, obtaining a judgment — was already paid for, and the system discarded the
+   answer.
+
+   Enumerate items carrying the configured `human_needed` marker **or** a `[lisa-human-gate]` marker
+   in the body, and for each call
+   `planHumanGateRelease({ labels, body, comments, humanNeededLabel, readyLabel, lifecycleLabels, alreadyNotified })`
+   from `scripts/intake-blocker-reprobe.mjs`. Apply exactly the actions it returns: remove the
+   human-needed marker, add the configured build `ready` label back, and post
+   `formatHumanGateReleaseNote()` once. Do **not** re-implement the discharge test, and do **not**
+   decide it from labels alone — the hold and its release are body and comment surfaces.
+
+   Three refusals make this safe to run on every cycle, and each one is in the planner rather than
+   in this prose so it cannot drift:
+
+   - **Still held plans nothing.** Every outstanding reason holds the whole item; an item whose
+     second question is unanswered is not half-released.
+   - **Never held plans nothing.** Without that this would be a path that adds the build-ready role
+     to arbitrary items — a promotion mechanism wearing a release mechanism's name.
+   - **An item that has moved on is not dragged back.** The ready role is restored only when the
+     item carries no other configured lifecycle label.
+
+   This is a genuine exception to "never remove a `human_needed` marker this skill did not apply",
+   and the exception is narrow enough to state exactly: provenance is the wrong question when the
+   *hold itself* names the condition that voids it and that condition is recorded. The general rule
+   stands because "stale" is otherwise a judgment about the block's kind; here nothing is being
+   judged — a release naming the hold's own reason is on the item, or it is not.
+
+   **Never edit a description to clear a hold**, here or anywhere. The only body write this plugin
+   has is a whole-body replacement, so deleting one line means rewriting the record and hoping
+   nothing was dropped. That is why holds accumulated: each individual release was a small gamble
+   with a large downside. The hold note stays in the body as history; the release is a comment
+   beside it. Count these under `released_to_queue`, and name them in the cycle summary via
+   `summarizeHumanGateReleases([...])` — printed even when it is zero, because a release path that
+   has stopped working and a cycle with nothing to release read identically otherwise.
 3. Classify the issue:
    - **PRD** if it has PRD labels/markers (`prd`, `type:PRD`, `kind:prd`), PRD structure
      (`## Problem`, `## Goals`, `## Validation Journey`, generated-work/backlink sections), or

package/plugins/src/base/skills/lisa-rework-triage/SKILL.md

@@ -41,8 +41,34 @@ first-attempt work.
    comment posted by `lisa-tracker-evidence` (`[lisa-evidence]` / the vendor evidence
    header). Only markers proving a prior *implementation* attempt qualify —
    `[lisa-rework-triage]` comments and other unrelated `[lisa-*]` annotations never do.
-4. **Explicit rework marker.** A `rework`, `qa-fail`, or `regression` label applied by QA or
-   the verify lifecycle.
+4. **Explicit rework marker.** A `rework` or `regression` label applied by QA or the verify
+   lifecycle, or a **live** QA-failure signal.
+
+   The QA-failure signal is transient, so its bare presence is not the signal — its
+   liveness is. Ask the resolver, never the label list:
+
+   ```bash
+   RESOLVER="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-plugins/lisa}}/scripts/qa-signal-lifecycle.mjs"
+   node "$RESOLVER" --vendor "<jira|linear|github>" --item bundle.json
+   # bundle.json: { "labels": [...], "comments": [<bodies, oldest first>], "role": "<current>" }
+   ```
+
+   Branch on `action`, never on the label being there:
+
+   | `outcome` | Meaning | What triage does |
+   |---|---|---|
+   | `live` | the failure is unresolved | signal 4 fires — this is rework |
+   | `stale` | a later QA pass, or the certified/terminal role, voided it | signal 4 does **not** fire; **remove the label** (same tracker surface that applied it) and note the repair in the triage comment. Keep evaluating signals 1–3 |
+   | `absent` | no signal | signal 4 does not fire |
+   | `unchecked` | a declared void condition has no predicate | treat as `live` and surface it — a control nothing can evaluate is a defect to report, not an exemption |
+
+   Clearing a stale signal here is the repair path for items labelled before the signal had
+   an inverse; without it that backlog never drains. The `[lisa-qa-fail]` comments are the
+   history and are never touched — a stale signal removed still leaves the failure fully
+   readable, and signal 3 still reads those comments.
+
+   `rework` and `regression` are matched on presence as before. Whether they have the same
+   shape is **unverified** and not claimed here.
 
 Record which signal fired — it is part of the evidence trail.
 
@@ -170,3 +196,7 @@ which blocks per the normal triage rules.
   bypass the quality gates this loop exists to strengthen.
 - Noise discipline: one triage comment per bounce (fingerprinted), no upstream issue without
   the dedupe search, and upstream issues describe failure *classes*, not single incidents.
+- Never key on a durable mark whose inverse you have not checked. A signal with no expiry
+  degrades toward meaning "this item has been around a while"
+  (`state-changes-without-inverses`), and a deterministic input that degrades is
+  deterministically wrong.

package/plugins/src/base/skills/lisa-setup-linear/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-setup-linear
-description: "Configure Linear as the destination tracker and/or the PRD source for this project. Verifies Linear access (MCP OAuth or a personal API key in OS keychain), resolves the workspace slug and team key, scaffolds the build-queue **workflow states** (`linear.workflow`) when Linear is the tracker and/or the PRD-lifecycle project-label namespace (`prd-*` + issue-level sentinel) when Linear is the PRD source, writes the `linear` section into `.lisa.config.json`, and offers to set top-level `tracker: \"linear\"` and/or `source: \"linear\"`. Idempotent — re-running updates the existing section and reuses existing labels. No /lisa:setup:atlassian prerequisite."
+description: "Configure Linear as the destination tracker and/or the PRD source for this project. Verifies Linear access (MCP OAuth or a personal API key in OS keychain), resolves the workspace slug and team key, scaffolds the build-queue **workflow states** (`linear.workflow`) when Linear is the tracker and/or the PRD-lifecycle project-label namespace (`prd-*`) when Linear is the PRD source, writes the `linear` section into `.lisa.config.json`, and offers to set top-level `tracker: \"linear\"` and/or `source: \"linear\"`. Idempotent — re-running updates the existing section and reuses existing labels. No /lisa:setup:atlassian prerequisite."
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion", "mcp__linear-server__authenticate", "mcp__linear-server__complete_authentication"]
 ---
 
@@ -13,7 +13,7 @@ The two lifecycles run on different primitives, and conflating them is the most
 - **Build queue → native workflow STATES**, read from `linear.workflow.*`. Not labels. See "Why Linear uses states, not labels" in `config-resolution`, and Step 3a below. `lisa-linear-build-intake` reads only these.
 - **PRD lifecycle → PROJECT labels** (`prd-*`), because a PRD is a Linear Project.
 
-Project labels and issue labels are distinct namespaces in Linear and are NOT interchangeable — creating an issue label named `prd-ready` will not work for the PRD flow. The one issue label this skill creates is the sentinel feedback marker, which belongs to the PRD flow despite being an issue label (Linear's MCP has no project-level comments — see `linear-prd-intake`).
+Project labels and issue labels are distinct namespaces in Linear and are NOT interchangeable — creating an issue label named `prd-ready` will not work for the PRD flow. Every PRD-lifecycle label this skill creates is a **project** label; the PRD flow needs no issue label at all, because clarifying-question comments go on the project itself (see `linear-prd-intake`).
 
 **A `status:*` issue-label namespace is no longer scaffolded or read.** It was the pre-state-model build lane; see "Migrating a project that predates the state model" below for what to do with a config that still carries it.
 
@@ -280,7 +280,7 @@ Probe with `lisa-linear-access operation: list-project-labels`. Create missing o
 | `ticketed` | `prd-ticketed` | project label |
 | `shipped` | `prd-shipped` | project label |
 | `verified` | `prd-verified` | project label |
-| `sentinel` | `prd-intake-feedback` | **issue** label (marks the sentinel feedback issue — create via `create_issue_label`) |
+| `sentinel` | `prd-intake-feedback` | **Legacy, not created.** An issue label that marked the fabricated feedback issues earlier versions used before project-level comments were wired up. Configured only so the rollup can recognise and exclude an existing one; a fresh workspace never needs it |
 
 #### 3c. Handle name collisions / renames
 
@@ -357,7 +357,7 @@ jq -e '.linear.workspace' .lisa.config.json >/dev/null
 [ "$(jq -r '.tracker // empty' .lisa.config.json)" = "linear" ] && jq -e '.linear.teamKey' .lisa.config.json >/dev/null
 ```
 
-Confirm what was scaffolded is present: `list-workflow-states` for every build role when Linear is the tracker, `list_project_labels` for `prd-*` (including the terminal `prd-verified`) and `list_issue_labels` for the sentinel when Linear is the PRD source. Do NOT expect a `status:*` namespace — it is not part of this model. Report success with the resolved workspace, team key (if any), which namespaces were scaffolded (created vs. already existed), any non-default overrides, and whether `tracker` / `source` were set. Direct the user to `/lisa:intake` to test.
+Confirm what was scaffolded is present: `list-workflow-states` for every build role when Linear is the tracker, `list_project_labels` for `prd-*` (including the terminal `prd-verified`) when Linear is the PRD source. Do NOT expect a `status:*` namespace — it is not part of this model. Report success with the resolved workspace, team key (if any), which namespaces were scaffolded (created vs. already existed), any non-default overrides, and whether `tracker` / `source` were set. Direct the user to `/lisa:intake` to test.
 
 ## Idempotency
 
@@ -369,7 +369,7 @@ Confirm what was scaffolded is present: `list-workflow-states` for every build r
 
 - Never write the API key to `.lisa.config.json`. It stays in keychain or `LINEAR_API_KEY`.
 - Never accept the API key via this skill's stdin/chat — always the platform clipboard-pipe pattern, so the value never enters the LLM context.
-- Never conflate the two label kinds: build labels are **issue** labels, PRD labels are **project** labels. The sentinel is an issue label. Creating the wrong kind silently breaks the corresponding intake flow.
+- Never conflate the two label kinds: build labels are **issue** labels, PRD labels are **project** labels. Creating the wrong kind silently breaks the corresponding intake flow.
 - Never create a duplicate label for a role that already has a (differently-named) label — map and record an override instead.
 - Never set `tracker` / `source` without explicit confirmation — they're project-wide switches.
 - Never invent a workspace slug or team key. Derive from the validated identity / team list and confirm; if resolution fails, ask the user.

package/plugins/src/base/skills/lisa-track/SKILL.md

@@ -78,5 +78,5 @@ Otherwise:
 - Branch setup may call `node scripts/lisa-work-item.mjs attach-branch` after the feature branch exists.
 - Keep the binding across ordinary interruptions and blocked outcomes so resumed work remains attributable.
 - Clear it only after true terminal completion — merged, deployed/verified where required, tracker evidence/backlink complete, and the work item terminal — by running `node scripts/lisa-work-item.mjs clear` and verifying no current binding remains.
-- A held filing writes no binding at all, so there is nothing to clear. The gate is released by a human, not by this skill: a human removes the `[lisa-human-gate]` marker and flips the leaf into the build-ready role, and a later invocation then resolves it on the ordinary path.
+- A held filing writes no binding at all, so there is nothing to clear. The gate is released by a human decision, but not by a human edit: the person records the decision as a comment on the leaf beginning `[lisa-human-gate-release]` and repeating the hold's `reason=` verbatim, and the next intake sweep takes the human-needed marker off and puts the leaf back in the build-ready role on its own (`planHumanGateRelease` in `scripts/intake-blocker-reprobe.mjs`). A later invocation then resolves it on the ordinary path. **Do not tell anyone to delete the marker from the description, and do not delete it here.** The only description write available is a whole-body replacement, so clearing one line means rewriting the entire record — which is why, before this, the rational move was always to leave a hold in place and answered holds only accumulated (CodySwannGT/lisa#3852). The hold stays in the body as history; the release is recorded beside it.
 - A tracker outage, invalid item, failed claim, or failed binding blocks durable work. Never continue untracked and never ask a Git hook to create the item.

package/plugins/src/base/skills/lisa-tracker-build-intake/SKILL.md

@@ -62,6 +62,15 @@ Shared helpers own both, so the vocabulary cannot drift per vendor:
 blocker re-probe carries an absolute human gate: an item carrying the configured human-needed label
 or a `[lisa-human-gate]` marker is never auto-selected, whatever a probe returns.
 
+That gate has an inverse, and it is forwarded identically: a hold ends when a
+`[lisa-human-gate-release]` comment naming the same `reason=` is recorded on the item. Every vendor
+scanner passes the item's `comments` into the gate helpers so the discharge is visible, and calls
+`planHumanGateRelease(...)` to take the marker off and put the item back in the queue. **No vendor
+scanner clears a hold by editing the description** — the only body write any of them has is a
+whole-body replacement, so a release that went through the description would risk destroying the
+record it was releasing, which is why holds accumulated with no way out (CodySwannGT/lisa#3852).
+The hold note stays in the description as history and the release sits beside it as a comment.
+
 Measured: sweeping one team by lane name saw 39 of 343 open rows; by category it sees 100. The
 61-row gap produced 31 consecutive false "dry lane" cycles, every record honest and every
 conclusion wrong (#2657).

package/plugins/src/harper-fabric/hooks/inject-rules.sh

@@ -1,10 +1,21 @@
 #!/usr/bin/env bash
-# Reads all .md files from the plugin's rules/ directory and injects them
-# into Claude context at session/subagent start.
+# Reads the plugin's EAGER rules and injects them into the session context.
+#
+# `rules/eager/` only, and deliberately with NO fallback to a flat `rules/`.
+# This plugin's rules and this script ship in the same directory and are
+# installed as one unit, so there is no vintage in which a split script meets an
+# unsplit rules tree. A fallback here would buy nothing and cost the thing it
+# already cost once: this plugin shipped its whole rule body flat for months and
+# no surface complained, because a fallback that quietly succeeds is
+# indistinguishable from a tree that was never split (#3993). With the branch
+# gone, an unsplit tree injects nothing and is noticed.
+#
+# Reference bodies under `rules/reference/` install alongside and are read only
+# when an eager breadcrumb points at one.
 set -euo pipefail
 
 ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}}"
-RULES_DIR="$ROOT/rules"
+RULES_DIR="$ROOT/rules/eager"
 
 [ -d "$RULES_DIR" ] || exit 0
 

package/plugins/src/harper-fabric/rules/eager/harper-fabric.md

@@ -0,0 +1,31 @@
+# Harper/Fabric Project Rules (load-bearing)
+
+These rules apply to Harper/Fabric component apps managed by Lisa. The head
+below is what changes behaviour in a session that never asks for it; the full
+contract — deploy surface, documentation sync, design-system detail — lives in
+the reference body.
+
+## Mandatory
+
+1. **Build the real thing.** If a change needs a Harper resource, schema
+   update, seed path, or deploy script change, make that change. Do not ship a
+   client-side workaround, a stub, or a partial path for missing backend
+   behaviour unless the user explicitly asks for a stop-gap.
+2. **TypeScript under `src/` is the source.** Every `.js` at the harper-app root
+   (`harper-app/*.js`), plus `harper-app/web/**/*.js` and `harper-app/lib/**`,
+   is a generated deploy artifact. Never edit one — change the matching
+   TypeScript and run `bun run build`.
+3. **`harper-app/config.yaml` does not merge with Harper defaults.** Keep every
+   required top-level extension declared when editing it.
+4. **UI is composed from the project design system.** Extend the design-system
+   component first, then consume it through the barrel. No raw colours, no ad
+   hoc spacing. Every UI change needs Playwright verification with screenshots —
+   typecheck and unit tests are not enough for a visual change.
+5. **Immutable data flow.** `readonly` types, pure transformations, `const` over
+   `let`. Do not mutate parameters, singletons, fixtures, or config objects. No
+   `any`, broad casts, or `ts-ignore` outside a typed adapter.
+6. **Verify before reporting completion.** `bun run build`, `bun run typecheck`,
+   and the smallest relevant test command; plus the project smoke command for
+   deploy-affecting changes. If a command cannot run, report it and the blocker.
+
+Full prose: [reference/harper-fabric.md](../reference/harper-fabric.md).

package/plugins/src/phaser/hooks/inject-rules.sh

@@ -1,10 +1,21 @@
 #!/usr/bin/env bash
-# Reads all .md files from the plugin's rules/ directory and injects them
-# into Claude context at session/subagent start.
+# Reads the plugin's EAGER rules and injects them into the session context.
+#
+# `rules/eager/` only, and deliberately with NO fallback to a flat `rules/`.
+# This plugin's rules and this script ship in the same directory and are
+# installed as one unit, so there is no vintage in which a split script meets an
+# unsplit rules tree. A fallback here would buy nothing and cost the thing it
+# already cost once: this plugin shipped its whole rule body flat for months and
+# no surface complained, because a fallback that quietly succeeds is
+# indistinguishable from a tree that was never split (#3993). With the branch
+# gone, an unsplit tree injects nothing and is noticed.
+#
+# Reference bodies under `rules/reference/` install alongside and are read only
+# when an eager breadcrumb points at one.
 set -euo pipefail
 
 ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}}"
-RULES_DIR="$ROOT/rules"
+RULES_DIR="$ROOT/rules/eager"
 
 [ -d "$RULES_DIR" ] || exit 0
 

package/plugins/src/phaser/rules/eager/phaser.md

@@ -0,0 +1,44 @@
+# Phaser 4 Project Rules (load-bearing)
+
+This is a **Phaser 4** (npm `phaser@^4.2.0`) TypeScript game project on the
+official `template-vite-ts` layout. Phaser 4 is the only supported target —
+never introduce Phaser 3 idioms. These decisions are **locked** and most are
+**lint-enforced**; do not disable a rule, fix the code.
+
+## Read the official skills first
+
+Phaser ships 28 authoritative agent skills inside the installed package at
+`node_modules/phaser/skills/<topic>/SKILL.md` (`scenes`, `physics-arcade`,
+`tweens`, `tilemaps`, `v3-to-v4-migration`, …). **For any Phaser API or
+subsystem question, read the matching official skill rather than relying on
+memory.** The `lisa-phaser` skills deliberately cover only the opinionated,
+lint-enforced project layer.
+
+## Mandatory
+
+1. **Thin scenes over a pure-logic core.** All game rules live in `src/logic/**`
+   as plain TypeScript with **zero `phaser` imports** — lint-enforced, and it is
+   what makes the game unit-testable.
+2. **Determinism.** No `Math.random()`, `Date.now()`, or `performance.now()` in
+   game code. Use the seeded `Phaser.Math.RND` and the scene clock.
+3. **Nothing created or allocated inside `update()`** — no `this.add.*`,
+   `tweens.add`, `time.addEvent`, `new Phaser.*`, object/array literals, or
+   `map`/`filter`/`reduce` chains. Create in `create()`; pool via `Group`s.
+4. **Events and state.** Cross-cutting events go through one dedicated
+   `EventsCenter`; **never reuse `game.events`**. Every external `.on()` needs a
+   matching `.off()` in the scene's `shutdown`. Global state goes through the
+   typed registry wrapper; persistence goes through SaveService, never raw
+   `localStorage`.
+5. **No raw keys, no placeholder art.** Texture/audio/animation/scene/event keys
+   are typed constants generated into `src/assets.ts`. Art must be real and
+   licensed per `phaser-asset-sourcing`; procedural `generateTexture`
+   placeholders are tracked art debt and need a linked issue.
+6. **No hardcoded user-facing strings** — use the typed i18n catalog.
+7. **Verify before reporting complete:** `bun run typecheck`, `bun run lint`,
+   `bun run test`, `bun run build`. For rendering or input changes, also verify
+   in a real browser (`bun run dev` plus a Playwright check). A green typecheck
+   alone is not proof a game works.
+
+Full prose — the ten locked architecture decisions, the enforced lint rules, the
+performance contract, and the game-development persona subagents:
+[reference/phaser.md](../reference/phaser.md).

package/plugins/src/rails/hooks/inject-rules.sh

@@ -1,7 +1,17 @@
 #!/usr/bin/env bash
-# Reads all .md files from the plugin's rules/ directory and injects them
-# into the session context via hookSpecificOutput.additionalContext.
-# Used by SessionStart and SubagentStart hooks.
+# Reads the plugin's EAGER rules and injects them into the session context.
+#
+# `rules/eager/` only, and deliberately with NO fallback to a flat `rules/`.
+# This plugin's rules and this script ship in the same directory and are
+# installed as one unit, so there is no vintage in which a split script meets an
+# unsplit rules tree. A fallback here would buy nothing and cost the thing it
+# already cost once: this plugin shipped its whole rule body flat for months and
+# no surface complained, because a fallback that quietly succeeds is
+# indistinguishable from a tree that was never split (#3993). With the branch
+# gone, an unsplit tree injects nothing and is noticed.
+#
+# Reference bodies under `rules/reference/` install alongside and are read only
+# when an eager breadcrumb points at one.
 set -euo pipefail
 
 INPUT=$(cat 2>/dev/null || true)
@@ -12,7 +22,7 @@ else
 fi
 
 ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
-RULES_DIR="$ROOT/rules"
+RULES_DIR="$ROOT/rules/eager"
 
 # Bail silently if no rules directory
 [ -d "$RULES_DIR" ] || exit 0

package/plugins/src/rails/rules/eager/rails-conventions.md

@@ -0,0 +1,23 @@
+# Rails Coding Conventions (load-bearing)
+
+Rails-specific standards for this project. The head below is what changes
+behaviour in a session that never asks for it; the worked examples for every
+point live in the reference body.
+
+## Mandatory
+
+1. **Fat models, skinny controllers.** Controllers handle HTTP concerns only.
+   Business logic belongs in a model or a service object under `app/services/`.
+2. **Strong parameters always, `permit!` never.** Enumerate the permitted keys.
+3. **No N+1 queries.** Use `includes` / `preload` / `eager_load` on any
+   association you iterate. Bullet is installed to catch the ones you miss.
+4. **Never edit `db/schema.rb` by hand.** Change it through a migration, honour
+   the `strong_migrations` constraints, and index every foreign key and
+   commonly-queried column.
+5. **Scopes, not class methods,** for chainable queries. Prefer built-in
+   validators; keep callbacks to simple normalization and push complex side
+   effects into a service object.
+6. **RSpec with `factory_bot` and `shoulda-matchers`,** not fixtures. Use
+   `described_class` and keep one assertion concept per example.
+
+Full prose and Ruby examples: [reference/rails-conventions.md](../reference/rails-conventions.md).

package/rails/copy-overwrite/scripts/check-threshold-ratchet.mjs

@@ -22,10 +22,20 @@
  * every entry carries a written decision.
  *
  * Human override: `.lisa.config.json` → `thresholdRatchet.allow` entries
- * ({ file, key, reason }). Honored ONLY from the baseline side (HEAD /
+ * ({ file, key, reason, until }). Honored ONLY from the baseline side (HEAD /
  * merge-base), never from the change under review — an agent cannot grant
  * itself an exception in the same change that weakens a gate. `key: "*"`
- * allows every key in the file.
+ * allows every key in the file, and reports as file-wide so it is not mistaken
+ * for a key-scoped one.
+ *
+ * Exemptions END (#3856). `until` is a `YYYY-MM-DD` day the entry is live
+ * through; past it the entry stops exempting and the weakening it permitted is
+ * refused again, naming the entry, its scope, its reason and the remedy. An
+ * entry naming no evaluable condition still exempts — that keeps a project
+ * mid-migration off a red wall — but is reported on every run until somebody
+ * gives it a condition or deletes it. Modelled on `_thresholdsDivergence` in
+ * `stryker.conf.json`, the sibling exemption that already stops exempting when
+ * it goes stale; see `threshold-ratchet-families.mjs` `ALLOW_STATE`.
  *
  * One exception, and only one: a PROMOTION between deploy-chain branches
  * (`--base` + `--head`, both named in `deploy.branches`, head upstream of
@@ -49,6 +59,7 @@ import {
 import {
   applyAllowList,
   compareFile,
+  describeAllowList,
   formatReport,
 } from "./threshold-ratchet-compare.mjs";
 
@@ -390,6 +401,13 @@ function run(mode, baseRef, onlyFiles, headRef) {
     );
   }
 
+  const allow = resolveAllowList(
+    root,
+    plan.baselineRef,
+    mode,
+    baseRef,
+    headRef
+  );
   const findings = watched.flatMap(f =>
     compareFile(
       f,
@@ -397,28 +415,60 @@ function run(mode, baseRef, onlyFiles, headRef) {
       plan.readCurrent(f)
     )
   );
-  if (findings.length === 0) return 0;
+  // The allow-list inventory is printed whether or not the change produced
+  // findings. An exemption that has outlived its condition is dead weight the
+  // moment the condition passes, and reporting it only when something else has
+  // already failed is how a list nobody reads stays a list nobody reads.
+  if (findings.length === 0) {
+    reportAllowList(allow.entries, []);
+    return 0;
+  }
+  return reportFindings(findings, allow, mode);
+}
 
-  const allow = resolveAllowList(
-    root,
-    plan.baselineRef,
-    mode,
-    baseRef,
-    headRef
-  );
+/**
+ * Print the allow entries a human has to act on, minus the ones a refusal is
+ * about to name in full.
+ * @param {object[]} entries The resolved allow list
+ * @param {Array<{ message: string }>} expired Refusals already being printed
+ * @returns {void}
+ */
+function reportAllowList(entries, expired) {
+  for (const line of describeAllowList(entries)) {
+    if (expired.some(item => item.message.startsWith(line))) continue;
+    process.stdout.write(`threshold-ratchet: ${line}\n`);
+  }
+}
+
+/**
+ * Print the verdict for a change that produced findings.
+ * @param {object[]} findings Findings from every watched file
+ * @param {{ entries: object[], promotion: boolean, note: string | null }} allow
+ *   The resolved allow list and its provenance
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @returns {number} Process exit code (2 for hook mode, 1 otherwise; 0 clean)
+ */
+function reportFindings(findings, allow, mode) {
   const split = partitionCarriedEntries(findings, allow.promotion);
-  const { blocked, allowed } = applyAllowList(split.rest, allow.entries);
+  const { blocked, allowed, expired } = applyAllowList(
+    split.rest,
+    allow.entries
+  );
   if (allow.note) process.stdout.write(`${allow.note}\n`);
+  reportAllowList(allow.entries, expired);
   for (const finding of split.carried) {
     process.stdout.write(
       `threshold-ratchet: carried forward by this promotion, approved upstream — ${finding.message}\n`
     );
   }
-  for (const finding of allowed) {
+  for (const item of allowed) {
     process.stdout.write(
-      `threshold-ratchet: allowed by .lisa.config.json exception — ${finding.message}\n`
+      `threshold-ratchet: ${item.message} (.lisa.config.json exception)\n`
     );
   }
+  for (const item of expired) {
+    process.stderr.write(`threshold-ratchet: refused — ${item.message}\n`);
+  }
   if (blocked.length === 0) return 0;
   process.stderr.write(`${formatReport(blocked)}\n`);
   return mode === "hook" ? 2 : 1;