@codyswann/lisa 4.74.9 → 4.75.1

package/plugins/lisa-devin/rules/reference/pre-flight-autofill.md

@@ -0,0 +1,250 @@
+# Pre-Flight Spec Autofill (Draft-Then-Block)
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Pre-Flight Spec Autofill — Draft-Then-Block (load-bearing)
+
+When the pre-flight gate (`*-agent` Step 2) returns `FAIL` on **ticket-quality**
+gaps, do **not** bounce a raw checklist back to the reporter. Most "missing
+required spec content" gaps are **authorable** from material already on the work
+item (title, description, screenshots, design links, repro steps) plus the
+codebase. **Draft** a best-effort version of every authorable gap, write it into
+the item as clearly-labeled **assumptions/recommendations**, and only **then**
+block — turning the human ask from *"author all this"* into *"confirm or correct
+my draft, then flip back to Ready."* Same shape as `repo-scope-split`: the agent
+does the work it can; the human decides only what only a human can.
+
+This does **not** widen the gate — every required section must still exist
+before build. It replaces an empty demand with a defensible first draft, and it
+breaks the `Ready ↔ Blocked` ping-pong loop that a raw checklist causes (the
+information was already on the ticket; only the structure was missing).
+
+## Two tiers
+
+- **Tier A — authorable (always draft):** Technical Approach, Out of Scope,
+  Gherkin Acceptance Criteria (one scenario per fix), expected-vs-actual +
+  environment, Repository, Relationship Search (actually run the git+tracker
+  search — don't fabricate "none found"), Validation Journey **draft** (via the
+  vendor `*-add-journey` skill), Target Backend Environment. Preserve a bare
+  configured key or `Confirmed: <env>` as human-confirmed. Automation writes
+  `Inferred: <env> — evidence: <title|body|reproduction|hostname>` or
+  `Assumption: <env> — remote default branch <branch>`. Without a unique
+  reverse-map use `Assumption: remote default branch <branch>`; human confirmation
+  replaces the annotation with a bare key or `Confirmed: <env>`. For legacy bare
+  values, use managed draft markers and current ticket content only; provider
+  edit history is not required. A marker proves automation and requires
+  re-annotation; otherwise unknown provenance plus conflicting evidence stops.
+  Human-confirmed wins, then validated `Inferred:`
+  evidence. Otherwise use one unambiguous exact `deploy.branches` key from the
+  title, body, and reproduction steps or a URL hostname, excluding the complete
+  `Target Backend Environment` section and other machine-authored metadata/draft
+  blocks so annotations cannot become evidence. Evidence supersedes only
+  `Assumption:`. Normalize only built-in
+  `prod` ↔ `production` when exactly one is configured; no other aliases exist.
+  Never infer from arbitrary branch text, URL paths/query strings, or substrings.
+  Conflicting signals **stop** autofill. With no environment signal, use the
+  remote default and record the applicable `Assumption:` form; a non-unique
+  reverse-map alone never blocks. Require any selected mapping and remote branch.
+  Never overwrite human prose.
+- **Tier B — irreducibly human:** real credentials/access that exist nowhere on
+  the item or in repo test-user docs; a genuine product/scoping decision with no
+  defensible default. Still propose a recommended default where one exists; ask
+  a specific question only where none does.
+
+## Procedure
+
+1. Enumerate FAIL categories from `*-verify`. If S10 failed, run
+   `repo-scope-split` first (split, not autofill).
+2. Draft each Tier-A gap grounded in item material + codebase; tag every
+   inference as an assumption. **Never overwrite human prose** — add/augment
+   sections only.
+3. Write the draft via the vendor write skill (`jira-write-ticket` /
+   `github-write-issue` / `linear-write-issue`); draft the Validation Journey
+   via `*-add-journey`.
+4. Re-run `*-verify`. Structural gates should now PASS; anything still failing
+   is Tier B — name it in the comment.
+5. Block as usual (`blocked` status + `human_needed` marker + reassign to
+   Reporter) but post the **confirmation comment**, not a checklist: disclose
+   it's a Claude draft, one line per drafted section + its key assumption,
+   Tier-B items as specific questions with defaults, and close with *"correct
+   anything wrong, then flip back to Ready and it builds — or reply with
+   corrections."*
+6. **Loop-safety:** if the item already carries the agent's draft, refine only
+   the still-failing gaps; don't redraft. Re-readying after review is the
+   human's approval — the next claim's `*-verify` PASSes and build proceeds.
+
+## When you genuinely cannot autofill
+
+If drafting would be fabrication (no fix/expected behavior described, no usable
+design ref, uninformative title, no codebase anchor), block as before — but
+phrase each gap as a specific question with a default where defensible. Never a
+bare checklist when a defensible draft is possible.
+
+The agent writes **spec/criteria, never code**, at this gate — authoring AC and
+a validation journey is explicitly permitted here (this supersedes the older
+"the build agent does not author the missing spec content" stance).
+
+---
+
+When the pre-flight gate (`*-agent` Step 2) returns `FAIL` on **ticket-quality**
+gaps, the agent does **not** bounce a raw "here is everything you must write"
+checklist back to the reporter. Most "missing required spec content" gaps are
+**authorable** from material already on the work item (title, description,
+screenshots, design links, reproduction steps) plus the codebase. The agent
+drafts a best-effort version of every authorable gap, writes it into the work
+item as clearly-labeled **assumptions and recommendations**, and only **then**
+blocks — turning the human ask from *"author all of this from scratch"* into
+*"confirm or correct my draft, then flip it back to Ready."*
+
+This is the same shape as the `repo-scope-split` exception: the agent does the
+work it can and reserves the human for what only a human can decide. It does
+**not** widen the gate — every required section must still exist before build;
+autofill just supplies a defensible first draft instead of an empty demand.
+
+## Why this exists
+
+The build + screenshot-diff verification pipeline needs **structured,
+machine-readable** sections — Gherkin acceptance criteria, a Validation Journey
+with `[SCREENSHOT:]`/`[EVIDENCE:]` markers, Sign-in Required, Target Backend
+Environment, Repository. A bug report routinely contains all of that
+*information* in prose, screenshots, or a Figma link, but not the *structure*.
+Dumping the checklist straight back produces a ping-pong loop: the item bounces
+`Ready → Blocked → Ready` on every intake cycle because nobody re-types the
+existing information into headings, and the reporter reasonably objects that the
+information is already there. Drafting the structure breaks the loop and
+respects the reporter's time — the human reviews a draft instead of authoring a
+spec.
+
+## Two tiers of gap
+
+**Tier A — authorable (always attempt a draft):**
+
+- **Technical Approach** — locate the affected component/files in the repo (the
+  title and description usually name the surface, e.g. "Player modal"); state
+  which files likely change and the expected layout. Flag inferences as
+  assumptions.
+- **Out of Scope** — a one-line boundary derived from the fix list.
+- **Acceptance Criteria (Gherkin)** — convert each described fix / expected
+  behavior into `Given/When/Then`. One scenario per discrete fix.
+- **Expected-vs-actual + environment** — restate the bug as explicit expected
+  vs actual, naming the environment the screenshots/description came from.
+- **Repository** — resolve per `config-resolution` repo scoping and state it.
+- **Relationship Search** — actually **run** the git + tracker search; record
+  the queries and results and link anything found. Do not fabricate a
+  "none found" note.
+- **Validation Journey (draft)** — run the vendor `*-add-journey` skill to draft
+  the click-path, markers, and viewports from the reproduction steps. This is a
+  draft for human approval, not the final ratified contract.
+- **Target Backend Environment** — preserve a bare configured key or
+  `Confirmed: <env>` as human-confirmed. Automated evidence must write
+  `Inferred: <env> — evidence: <title|body|reproduction|hostname>`; a generic
+  fallback must write `Assumption: <env> — remote default branch <branch>`.
+  If the default branch has no unique environment reverse-map, instead write
+  `Assumption: remote default branch <branch>` without inventing an environment.
+  Human confirmation replaces an automated annotation with a bare key or
+  `Confirmed: <env>`. For legacy bare values, use managed draft markers and
+  current ticket content only; provider edit history is not required. A marker
+  proves automation and requires re-annotation; otherwise unknown provenance
+  plus conflicting evidence stops for confirmation. A human-confirmed value wins, followed by validated
+  `Inferred:` evidence. Otherwise inspect the title, body, and reproduction
+  steps or a URL hostname for one unambiguous exact `deploy.branches` key,
+  excluding the complete `Target Backend Environment` section and all other
+  machine-authored metadata/draft blocks so annotations cannot become evidence.
+  Clear evidence supersedes only an `Assumption:` value. The sole normalization
+  is `prod` ↔ `production` when exactly one key is configured; no other aliases
+  exist. Never infer from arbitrary branch text, URL paths or query strings, or
+  substrings. Multiple conflicting signals **stop** autofill. With no
+  environment signal, use the remote default and record the applicable
+  `Assumption:` form; a missing/ambiguous reverse-map alone never blocks.
+  Require any selected environment mapping and remote branch. Never overwrite
+  human prose.
+
+**Tier B — irreducibly human (cannot invent — but still propose a default):**
+
+- **Real credentials / access** that exist nowhere on the item or in the repo's
+  known test-user docs. (If credentials are present in prose, that is Tier A —
+  lift them into a Sign-in Required section.)
+- **A genuine product / scoping decision** with no defensible default — the
+  exact expected behavior when the ticket is internally contradictory or the
+  design reference is missing.
+
+For Tier B, still propose a **recommended default** wherever one is defensible,
+and ask a **specific question** only where none is. Never reduce a Tier B item
+to a bare demand.
+
+## Procedure
+
+1. **Enumerate the FAIL categories** from `*-verify`.
+2. **Run `repo-scope-split` first** if S10 (single-repo scope) failed — that is
+   a split, not an autofill. Autofill handles the remaining quality gaps.
+3. **Draft each Tier-A gap** grounded in the work-item material + codebase.
+   Every inferred value is explicitly tagged as an assumption/recommendation
+   (lead the drafted block with a note: *"Drafted by Claude — assumptions
+   flagged inline; please confirm or correct."*). **Never overwrite
+   human-authored prose** — add the missing structured sections; if a section
+   exists but is thin, augment it without discarding the human's words.
+4. **Write the draft into the work item** via the vendor write skill
+   (`jira-write-ticket` / `github-write-issue` / `linear-write-issue`) so
+   relationship and metadata gates stay enforced. Draft the Validation Journey
+   via the vendor `*-add-journey` skill.
+5. **Re-run `*-verify`.** The structural gates should now PASS (the content
+   exists, even if assumed). Any gate that still FAILs is Tier B — leave it and
+   name it precisely in the comment.
+6. **Block as usual** — transition/relabel to the configured `blocked` status,
+   add the `human_needed` marker, reassign to the **Reporter** — but post the
+   **confirmation comment** (below), not a remediation checklist.
+7. **Idempotency / loop-safety.** If the item already carries the agent's draft
+   from a prior cycle, do **not** redraft from scratch — refine only the gaps
+   still failing and refresh the confirmation comment. When the reporter flips
+   the item back to Ready, the next claim re-runs `*-verify`; if it now PASSes,
+   build proceeds on the draft the reporter approved by re-readying it. That is
+   what breaks the `Ready ↔ Blocked` loop.
+
+## The confirmation comment (replaces the remediation checklist)
+
+- **Disclose**: posted by Claude (AI build agent); identify the content as a
+  draft.
+- **Frame it**: the item had the right information but lacked the structured
+  sections the pipeline needs, so the agent drafted them — the report's validity
+  was never in question.
+- **One line per drafted section**, naming the section and the key assumption
+  (e.g. *"Acceptance Criteria — drafted 4 Gherkin scenarios from the fix list;
+  assumed 'Search result' restores the prior query terms."*).
+- **Tier-B items still required**, each as a specific question with a
+  recommended default where one exists.
+- **Close with the action**: *"Review the drafted sections in the description.
+  Correct anything wrong, then flip back to Ready and it builds immediately — or
+  reply with corrections and I'll revise."* Keep the `human_needed` marker until
+  then.
+
+## When you genuinely cannot autofill (fall back to the plain block)
+
+If the item is so underspecified that drafting would be fabrication — no fix or
+expected behavior described, no usable design reference, an uninformative title,
+and the codebase gives no anchor — block as before. Even then, phrase **each gap
+as a specific question** and propose a default wherever one is defensible (the
+"Human-Needed is a last resort" principle). Never bounce a bare checklist when a
+defensible draft is possible.
+
+## Disclosure & safety
+
+- Agent-drafted content is **always attributed to Claude and marked as
+  assumptions**, so a human never mistakes a guess for their own ratified spec.
+- The agent writes **spec/criteria, never code**, at this gate. Drafting
+  acceptance criteria and a validation journey is authoring, not implementation
+  — explicitly permitted here. This **supersedes** the older "the build agent
+  does not author the missing spec content" stance, which produced the
+  bounce-loop.
+
+## Vendor mechanics
+
+- **JIRA** — draft sections via `jira-write-ticket`; Validation Journey via
+  `jira-add-journey`; block + label + reassign + comment via the `jira-agent`
+  Step 2 exception (`transitionJiraIssue`, `editJiraIssue` for the label and
+  assignee, `addCommentToJiraIssue`).
+- **GitHub** — `github-write-issue`; `github-add-journey`; relabel + reassign +
+  comment via `gh`.
+- **Linear** — `linear-write-issue`; `linear-add-journey`; `save_issue` +
+  `save_comment`.

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

@@ -0,0 +1,159 @@
+# Project Learnings
+
+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 v2 entry has eight fields:
+
+- `id`
+- `fingerprint`
+- `rule`
+- `why`
+- `provenance`
+- `first_learned`
+- `last_confirmed`
+- `confidence`
+
+`fingerprint` is the content-version token; `id` is the stable public identity.
+A new entry starts with `id = fingerprint`. Consolidation passes exact
+`{ id, fingerprint }` stamps copied from parsed entries. The writer checks the
+whole target set inside its lock: an exact set is replaced together while the
+deterministic primary id carries forward; any stale stamp removes nothing and
+the new fingerprint is appended safely. Fingerprints are unique, so an
+identical re-capture fails before mutation rather than gaining a sibling.
+
+## v1 compatibility and mutation-only migration
+
+`parseLearningsDocument` accepts both contract versions and reports
+`sourceVersion`, normalized `entries`, `canonicalSource`, and
+`sourceMaxTokens`. A v1 entry is normalized in memory with `fingerprint = id`,
+which records the version-token job its old id already performed. A read never
+rewrites the ledger. The next real writer mutation — append, exact stamped
+consolidation, confirmation, overflow drain, or merge — publishes one atomic v2
+document. Each source version is validated against its own derived budget; do
+not copy either numeric ceiling into instructions. Stable ids and fingerprints
+are bounded machine tokens, and the v2 budget is derived to absorb the maximum
+per-entry fingerprint expansion for every v1 document the compatibility parser
+accepts. That migration-closure invariant prevents an ordinary later mutation
+from discovering that a previously accepted legacy document cannot be
+published.
+
+The three-way merge understands mixed v1/v2 sides. When two branches both
+legitimately replace the same stable id from the same observed fingerprint, it
+keeps both successors deterministically: one retains the stable id and the
+other is keyed by its unique fingerprint. It never guesses when fingerprints
+collide.
+
+## Who writes the ledger
+
+**Contract-mediated writers** — all going through the executable contract
+(`@codyswann/lisa/learnings`), never a hand-edit:
+
+- The **learner agent** at capture time appends or consolidates new entries
+  (`persistLearningEntry` / `persistConsolidatedLearning`) from task learnings.
+  Consolidations pass exact parsed `{ id, fingerprint }` stamps and report a
+  stale snapshot through `onStaleSupersede` instead of overwriting its winner.
+  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 —
+  to the ledger through the same contract (`persistLearningEntry` /
+  `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,
+  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).
+
+Automated promotion of a captured learning to a higher rung (skill, eager rule,
+executable control, upstream ticket) is the gardener's job, gated by a human
+flipping a tracker ticket to `status:ready`.
+
+## Operator-directed standing rules
+
+An operator's instruction to add, revise, or remove a standing rule is already
+authorization for that specific edit. It is not a new machine-captured learning.
+Make the requested change directly, preserving unrelated content; do not require
+learning capture, a promotion ticket, or repeated approval for the same decision.
+"Human-authored" describes who controls the rule, not who types the approved edit.
+
+Use the existing topic file under `.agents/rules/`, or create a short one there,
+when the operator has not specified another destination. The `AGENTS.md` host-rules
+pointer reaches Claude Code, Codex, Cursor, OpenCode, Antigravity, and Copilot.
+These shared rules are not a Claude-only surface, and they do not need to be
+copied into every agent's startup file.
+
+If the operator explicitly named a guarded startup file, do not substitute a
+different destination or switch tools to evade a refusal. Use the runtime's
+authorized edit path, or report the specific remaining runtime restriction.
+The existing instruction-file override is an operator-configured escape hatch,
+not proof of human approval; agents must not set it to work around a refusal.
+No new approval token is needed for ordinary authorized edits to shared host rules.
+
+This does not authorize agents to promote their own incidental findings. Decline
+one-off notes and unnecessary rules; use the existing learning flow only for
+durable knowledge worth maintaining.
+
+## Claim-time confirmation (`last_confirmed`)
+
+`last_confirmed` is advanced at claim time by the build-intake flows (step
+3c.2 of `lisa-{jira,github,linear}-build-intake`) when an entry's rule
+**demonstrably applied** during a claim — the rule was explicitly cited or
+observably followed in the claim's plan or diff. Presence in the eagerly
+loaded context is NOT application: every entry is present in every session,
+so counting mere presence would confirm everything on every claim and defeat
+decay entirely.
+
+The bump goes only through `confirmLearningEntry` from
+`@codyswann/lisa/learnings`: a surgical, lock-protected, atomic write that
+advances only `last_confirmed` (re-validated against the
+`>= first_learned` invariant), returns a structured no-op for a missing
+entry or file instead of throwing, and is idempotent within a claim (a
+same-date repeat returns `unchanged`). A failed bump is reported and never
+blocks the build.
+
+Only entries accepted by the executable contract may influence the session. A
+missing file is expected and silent. Malformed Markdown, invalid JSONL, unsafe
+paths, non-canonical content, or over-budget documents produce one readable
+warning, apply no entry, and do not block unrelated work.
+
+Precedence:
+
+1. System, developer, user, and repo instructions still outrank learnings.
+2. Committed host rules (`.agents/rules/`) remain durable, operator-controlled
+   guidance.
+3. Project learnings add recent operational knowledge, but never rewrite or
+   append to host rules.
+
+## Task telemetry (MLD) is not context
+
+Raw task-end MLD telemetry — the Mistakes / Learnings / Desires an implementing
+agent records into `metadata.learnings`, and the raw yield of debrief mining — is
+rung-1 capture only: it is never read into a later session's instruction surface,
+never required of an agent (empty is valid), and never graded or scored. It reaches
+a durable surface only indirectly — through the learner's validation into the
+ledger (which sessions still consume solely as the bounded projection above), and
+from there through the gardener's ticket-gated promotion a human approved. Injecting
+raw self-reports, or treating their volume as a quality signal, would reward
+plausible commentary over good outcomes and bypass the very budget and validation
+this contract exists to enforce.
+
+Antigravity note: agy does not receive the plugin `rules/` tree. Lisa reconciles
+a bounded `AGENTS.md` bridge that points agy at this same file without copying
+learning bodies or restoring the retired full rules bake.

package/plugins/lisa-devin/rules/reference/promotion-contract.md

@@ -0,0 +1,148 @@
+# Promotion Contract
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Promotion Contract (load-bearing)
+
+When implementing a learnings-ladder **promotion ticket** — turning prose
+knowledge into an executable control (lint / ast-grep / type / test / hook /
+`package.lisa.json` force) — the change must be **atomic**: one PR that
+**enables the control**, **fixes the existing violation population**, **ships a
+remediation-teaching diagnostic** (violated invariant + why + concrete fix),
+and **deletes the superseded prose**. A PR missing any of the four is
+**rejected by rule** — promote-without-remove double-pays forever;
+remove-without-diagnostic strands agents.
+
+Eager-tier admission is **demotion-biased** and earned only by repeated-miss
+evidence; the gardener audits the eager tier every run, including Lisa's own
+shipped eager rules.
+
+---
+
+When a learnings-ladder promotion ticket (PRD #1729) is implemented — turning a
+prose learning, rule section, or ledger entry into an **executable control**
+(lint, ast-grep, type constraint, test, hook, or `package.lisa.json` force) —
+the implementing PR is governed by this contract. The gardener
+(`lisa-learnings-audit`) files the tickets; a human gates them by flipping
+`status:ready`; the factory implements them like any other work item. This rule
+is what makes the resulting PR reviewable **by rule, not by reviewer taste**.
+
+## The atomic promote-and-delete contract
+
+A promotion PR must do **all four** of the following, in **one atomic PR**:
+
+1. **Enable the control.** The lint rule, ast-grep pattern, type constraint,
+   test, hook, or `package.lisa.json` force entry is active and blocking (CI
+   and/or local gates), not merely added in a warn-only or disabled state.
+2. **Fix the existing violation population.** Every current violation of the
+   new control in the repository is migrated in the same PR, so the control
+   lands green. Enabling a control against a red population either blocks all
+   unrelated work or forces a blanket ignore — both defeat the promotion.
+3. **Ship a remediation-teaching diagnostic.** The control's failure message
+   meets the diagnostic-quality bar below. The prose being deleted is not
+   lost — its content is **relocated into the error message**, so the agent
+   that trips the control learns the rule at exactly the moment it matters.
+4. **Delete the superseded prose.** The ledger entry, rules-file section,
+   memory note, or wiki duplication that the control replaces is removed in
+   the same PR. Keeping both means every session keeps paying context tax for
+   knowledge the machine already enforces.
+
+**A PR missing any of the four is rejected by rule.** Reviewers (human, bot,
+or verification lifecycle) cite this contract and reject — no case-by-case
+judgment call is needed. The failure modes are structural, not stylistic:
+
+- **Promote-without-remove double-pays forever**: the control enforces the
+  invariant while the prose keeps taxing every session, and the two drift
+  apart over time.
+- **Remove-without-diagnostic strands agents**: the prose is gone, the control
+  fires, and the violator has no idea what invariant it tripped or how to
+  repair it.
+- **Enable-without-population-fix** reds the build for everyone or breeds
+  blanket ignores that hollow the control out.
+
+The same atomicity applies in reverse to **retirements** the gardener batches:
+a prose deletion whose invariant is claimed to be mechanically owned must cite
+the owning control (rule name, config location) in the deleting PR.
+
+## The diagnostic-quality bar
+
+The error message must **teach the repair**, because it is the only surface
+the violating agent will see. Every promoted control's diagnostic states:
+
+1. **The violated invariant** — what rule was broken, named precisely.
+2. **Why the invariant holds** — the causal story that used to live in the
+   prose (the incident, the failure class, the platform behavior).
+3. **The concrete fix** — what to change, ideally with the typical corrected
+   form inline.
+
+Example shape (from this repo's own lint conventions):
+
+> "Direct `process.env` access is forbidden. Config values bypass validation
+> and typing when read ad hoc (past incidents: silent `undefined` in Lambda
+> cold starts). Use the config module: `getStandaloneConfig().myValue`."
+
+A diagnostic that merely restates the rule name ("no-direct-env: direct env
+access is not allowed") fails the bar and fails the promotion PR with it.
+
+## Eager-tier admission policy (demotion-biased)
+
+The eager rules tier (auto-loaded rules trees) charges **every session,
+unconditionally**. Admission is therefore **earned, never defaulted**:
+
+- A rule enters (or stays in) the eager tier only on cited **repeated-miss
+  evidence** — the knowledge was already retrievable (ledger, wiki, skill,
+  reference body) and agents still failed repeatedly because they did not
+  know to look. Absent that evidence, the content belongs on a cheaper rung.
+- The policy is **demotion-biased**: when in doubt, move down the ladder.
+  A wrongly demoted rule earns its way back with fresh failure evidence; a
+  wrongly admitted rule taxes every session until someone notices.
+- The gardener audits the eager tier **every run** — and that audit includes
+  **Lisa's own shipped eager rules**, not just host-project additions. No
+  rule is grandfathered; kernel rules demonstrating no repeated-miss evidence
+  get demotion tickets like any other candidate, filed upstream
+  (`template-candidate` or `self-hardening` lane as applicable).
+
+## AC template for EXECUTABLE-CONTROL promotion tickets
+
+The gardener embeds the following snippet **verbatim** (markers included) into
+the acceptance criteria of every EXECUTABLE-CONTROL promotion ticket, so
+implementing agents receive the contract inside the work item itself:
+
+<!-- promotion-contract-ac-template:start -->
+### Acceptance Criteria (promotion-to-control contract)
+
+One atomic PR that satisfies all four legs — a PR missing any of the four is
+rejected by rule (see the `promotion-contract` rule):
+
+- [ ] **Enables the control** — the lint / ast-grep / type constraint / test /
+      hook / `package.lisa.json` force entry is active and blocking.
+- [ ] **Fixes the existing violation population** — every current violation is
+      migrated in this same PR, so the control lands green with no blanket
+      ignores.
+- [ ] **Ships a remediation-teaching diagnostic** — the failure message states
+      the violated invariant, why it holds, and the concrete fix.
+- [ ] **Deletes the superseded prose** — the ledger entry / rules section this
+      control replaces is removed in this same PR, citing the new mechanical
+      owner.
+<!-- promotion-contract-ac-template:end -->
+
+Do not paraphrase, reorder, or partially quote the snippet when embedding it —
+verbatim embedding is what keeps the contract identical across every ticket
+and lets reviewers diff against a single source of truth.
+
+## Who consumes this rule
+
+- **Implementing agents** working a promotion ticket: structure the PR around
+  the four legs before writing code.
+- **Review flows** (human, CodeRabbit, `lisa-pull-request-review`,
+  verification lifecycle): reject a promotion PR missing any leg, citing this
+  rule.
+- **The gardener** (`lisa-learnings-audit`): embeds the AC template above into
+  EXECUTABLE-CONTROL promotion tickets and applies the eager-tier admission
+  policy when auditing.
+- **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.