@codyswann/lisa 4.49.0 → 4.50.1

package/plugins/lisa/rules/reference/rejection-detection.md

@@ -1,5 +1,74 @@
 # Rejection Detection at Claim Time
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Rejection Detection at Claim Time (load-bearing)
+
+A QA rejection — an item that reached a `review`/`done`-ward state and is now back in the build-ready lane — is a **teaching signal**, not fresh work. Detect it at claim time so the re-claim can reflect on the rejection instead of repeating it.
+
+**One vendor-neutral contract, cited by every build-intake arm** (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never three divergent implementations).
+
+## When it runs
+
+At the **top of build-intake step 3b (Claim), BEFORE the relabel** `$READY → $CLAIMED`. After the relabel the current-lane signal is gone, so detection must read history first. Detection is a pure read — idempotent, headless-safe, no side effects.
+
+## Classify the claimed item
+
+Return exactly one of:
+
+- **`rejection-reclaim`** — history shows the item reached a `review`/`done`-ward lane and is now back in `$READY`.
+- **`forward-only`** — history shows only forward moves (never returned to `$READY` from a later lane).
+- **`never-left-ready`** — history shows the item never left `$READY`.
+- **`unknown`** — the vendor history query failed, was inconclusive, or is absent.
+
+## Vendor history sources (through the access layers only — `integration-access-layer`)
+
+- **GitHub** — `LABELED` / `UNLABELED` timeline events on the configured **ready** label (the Label-Event History surface from `lisa-github-read-issue`).
+- **JIRA** — the `changelog` operation on `lisa-atlassian-access` (`?expand=changelog`, status items).
+- **Linear** — the `history` operation on `lisa-linear-access`, keyed on **workflow-state** history (`fromState.name` / `toState.name`, inlined on each node — no label-ID resolution needed).
+
+**Lane names ALWAYS come from `.lisa.config.json` lanes** (`github.labels.build.{ready,claimed,done}` for GitHub, `jira.workflow.*` and `linear.workflow.*` for the status/state trackers; `src/sync/registry.ts` `BUILD_LABEL_DEFAULTS` and `LINEAR_WORKFLOW_DEFAULTS`). **Never hardcode** `status:ready`, `Ready`, `Todo`, etc.
+
+## Never block the build
+
+`unknown` is a first-class result, not an error. A failing/absent history yields `unknown` and **the build proceeds** to implement the item. Detection never stops a claim.
+
+## Learning-loop exclusion (no learning about learning)
+
+An artifact this flow produced is **never** a rejection-reflection trigger, no matter how it moves. Before classifying as `rejection-reclaim`, exclude items carrying any learning marker — `[lisa-learning-drop]`, `[lisa-learning-pr]`, `[lisa-learning-upstream-handoff]` — or the `learning:needs-triage` label. Such items short-circuit to `forward-only` (treated as normal work) so the detector never fires on the flow's own learning PRs/issues.
+
+## Reflect on a `rejection-reclaim`
+
+On `rejection-reclaim` only, before re-implementing: read the rejection evidence (comments after the backward transition, review threads on the rejected PR) through the access layers, assemble **one** candidate learning with the rejection linked as provenance, and route it to the `lisa-persist-learning` skill. If that skill is absent, record the candidate as a comment that carries a **visible prose line** plus the marker (a bare marker renders as an empty comment bubble) — `Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.` followed by `<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->` — and proceed. **Marker-dedupe** on `<issue>-<backward-transition-timestamp>`: re-claiming twice produces no duplicate. Unreadable/absent evidence → proceed without a candidate, never block.
+
+## Proposal rejection memory (proposal-side — orthogonal to the reclaim path above)
+
+A **loop-proposed** item that a human **closed as _not planned_** is a durable decline. Every *proposing* loop (`lisa-exploratory-qa`, `lisa-project-ideation`, `lisa-monitor`, `lisa-repair-intake`; `lisa-learnings-audit` is the shipped precedent) MUST consult it **before filing a candidate**. This is orthogonal to the `rejection-reclaim` path above — that classification and its reflection are untouched. The memory lives in the **tracker, not a new state file**.
+
+- **Signal:** the prior item is closed *not planned* (GitHub `stateReason == "not_planned"`; the JIRA/Linear equivalent resolved via `config-resolution` — never hardcode). The GitHub compare is **case-insensitive** — raw `gh --json stateReason` returns `NOT_PLANNED` UPPERCASE, so normalize to lowercase (or read via `lisa-github-read-issue`) before comparing, never string-match raw `gh` JSON. Closed as **completed** is NOT a decline — a recurrence after a completed fix is a regression and may file.
+- **Marker:** `<!-- [<loop-marker>] key=<candidate-key> -->`, key computed deterministically `printf '%s' "$normalized" | shasum -a 256 | cut -c1-12`. Search **open AND closed** items for the marker before filing (body-enumeration fallback on search-index lag); **match on the marker, never the title.**
+- **Rule:** a hit on a closed-**not-planned** item **suppresses** the proposal. Re-file **only** with evidence postdating the decline, carrying BOTH the machine token (`declined <date>; recurred <date> in <ref>`) and a human acknowledgment sentence (`You declined this on <date>. It has recurred (<date>, <ref>), so we're raising it once more for your review.`).
+- **Operator footer:** every loop-filed proposal ticket MUST carry, as visible prose, `To stop this from being raised again, close it as **Not planned**. Close it as **Completed** if it was fixed — a later recurrence may be re-filed as a regression.` — so the operator knows which close-reason produces which outcome.
+- **Outcomes:** an all-suppressed cycle ends `nothing-needed` naming the **suppression count**; a memory check that cannot read the tracker ends `recovery-required`, never a silent `nothing-needed` (e.g. `Tracker unreachable during the decline check — restore credentials; nothing was filed this run.`).
+- **Concurrency:** search-then-write = convergence, not mutual exclusion — a transient duplicate is closed by the next run; no cross-run lock.
+
+## Automation-reversal memory (repair-side — orthogonal to both halves above)
+
+A human who **undoes a lifecycle transition this flow made** is correcting the flow, not supplying new state. Every loop that writes a lifecycle role as a **repair** (`lisa-repair-intake`) consults this before re-making a transition. It is a third classification, never merged into `rejection-reclaim`: that one is anchored on the ready lane and answers a rejection with re-implementation; this one lands in `$BLOCKED` and answers a correction by withdrawing a decision.
+
+- **Seam:** top of the repair walk for each item, **before any lifecycle write** — after the write the current-lane signal is gone.
+- **Classify:** `automation-reversal` — a role change **authored by** this flow, then a later **backward** move of that role **authored by** a human, with no automation move after it. Otherwise `no-reversal`. Authorship unavailable or history unreadable → `unknown`.
+- **Authorship is the signal, not the backward move.** An item can return to `$BLOCKED` because a real new blocker appeared — that is the world moving on. Read the `actor` (GitHub timeline, Linear history) or `author` (JIRA changelog) through the access layers; an unexposed actor is `unknown`, never an assumed human. **A marker and a transition on the same item say nothing until you know their order** — compare timestamps, and treat an unorderable pair as `unknown`.
+- **Lanes from config** (`github.labels.build.blocked` + the JIRA/Linear equivalents, `config-resolution`) — never hardcode.
+- **Degrade:** `unknown` is **neither a reversal nor a clearance** — the item is judged by the loop's normal rules and detection **never blocks the sweep**. The learning-loop exclusion above applies unchanged.
+- **Rule:** on `automation-reversal`, do not re-apply the reversed classification; leave the item where the human put it, ensure `human_needed`, and **name the reversed transition in the run record**. Re-attempt **only** on evidence that **postdates the reversal**, cited in the run record — mirroring the re-proposal rule the proposal half enforces.
+- **A changed lifecycle role is no longer a sufficient warrant on its own.** A consuming loop's recurrence brake must carry **authorship and an overturn bit**, not state alone.
+- **Signed per path.** Apply the inversion only where the loop decides whether to re-make a transition. A staleness/keep-alive path where a human comment already *suppresses* action is protective — leave it. One global sign reads as tightening and removes that protection.
+
+---
+
 When QA rejects an item, it moves the item **backward** — from a `review`/`done`-ward lane back to the build-ready lane — usually with a comment naming the defect. Today the re-claiming agent treats that bounced item as fresh work and repeats the rejected approach. This rule turns the backward move into a detectable, teachable signal.
 
 It is a **single vendor-neutral contract** consumed by all three build-intake skills (`lisa-jira-build-intake`, `lisa-github-build-intake`, `lisa-linear-build-intake`). Each vendor arm cites this slug at its claim step rather than re-implementing detection, exactly as the vendor arms cite `leaf-only-lifecycle` and `repo-scope-split`. That is what keeps a rejection detected on JIRA from being missed on Linear.

package/plugins/lisa/rules/reference/repo-scope-split.md

@@ -1,5 +1,53 @@
 # Repo Scope & Work-Time Splitting
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Repo Scope & Work-Time Splitting (load-bearing)
+
+**Leaf work units are single-repo.** A leaf is an individually implementable ticket with no open children — the by-design leaf types **Bug, Task, Sub-task, Improvement**, plus a childless **Story** or **Spike** (structurally a leaf per `leaf-only-lifecycle`). Each names exactly one repo. An **Epic**, and any **Story/Spike that still holds child work**, are coordination containers and may span repos.
+
+Enforced at four points: gate **S10** (`*-validate-*`, write time), `task-decomposition` step 1.5 (PRD-decomposition time), claim-time repo scoping (`*-build-intake`), and the work-time split procedure (an existing ticket about to be implemented).
+
+## Choose the right strategy
+
+- **Decomposition-time (no tickets exist yet):** use `task-decomposition` step 1.5 — one work unit per repo under a parent Story.
+- **Work-time (a ticket already exists):** narrow the original to one repo, spin off a sibling per additional repo, link by dependency. Do NOT invent a new parent — siblings inherit the original's existing parent.
+
+## Work-time split (pre-flight gate, agent-performed)
+
+1. **Detect repos.** Parse description + AC + approach, confirm against actual code surfaces. If single-repo, no split.
+2. **Pick the keeper.** Default: the original keeps the consumer / user-facing repo.
+3. **Create one sibling per extra repo**, cloning metadata (re-prefix summary, scope AC, carry parent, env, sign-in).
+4. **Link by dependency.** Producer **blocks** consumer (`is blocked by` on consumer / `blocks` on producer). No clear direction → `relates to`.
+5. **Narrow the original.** Edit summary prefix, Repository section, AC; remove cross-repo references.
+6. **Comment** on the original noting the split, linking each sibling.
+7. **Re-validate.** Run `tracker-verify` (S10) on the original and every sibling. All must PASS single-repo.
+8. **Proceed in dependency order.** Producer siblings first.
+
+## When to BLOCK instead of split
+
+Fall back to the standard BLOCK + reassign-to-Reporter path when:
+
+- Repos cannot be determined confidently from ticket + code.
+- Splitting would strand stakeholder context only the reporter can re-scope.
+- Required clone metadata (parent, env, credentials) is itself missing.
+
+## Claim-time repo scoping (build-intake)
+
+A tracker can oversee multiple repos. Build-intake claims only current-repo tickets. Resolve current repo per `config-resolution` (config `repo` → `github.repo` → git remote basename).
+
+**Query-time pre-filter (do this first, where expressible).** Scope the candidate query to the current repo so sibling-repo tickets never enter the set — on JIRA, append `AND (labels = "repo:<current>" OR labels IS EMPTY)`. This pre-applies only the unambiguous wrong-repo → skip arm; `labels IS EMPTY` keeps unlabeled tickets visible so the per-candidate gate below can still determine + stamp them. Skip it (broad scan) when the current repo can't be resolved or the query already constrains repo. Apply only where the query layer can express `OR labels IS EMPTY`: JIRA does (applied); GitHub issues are inherently single-repo (not needed); Linear's label filter can't, so it keeps the broad query and relies on the per-candidate gate.
+
+Then, for each ready candidate:
+
+1. **Read `repo:<name>` label.** Wrong repo → skip. Current repo → leaf-only gate + claim. Unlabeled → determine + stamp + re-apply.
+2. **Multi-repo leaf → split, never claim.** Each split sibling is created build-ready and stamped with its own `repo:<name>`.
+3. **Wrong-repo single-repo leaf → skip** (label keeps it cheap next cycle).
+
+---
+
 Leaf work units are single-repo. A **leaf work unit** is an individually implementable ticket with no open child tickets — the by-design leaf types **Bug, Task, Sub-task, Improvement**, plus a childless **Story** or **Spike** (a childless Story/Spike is structurally a leaf — see `leaf-only-lifecycle`). Each must name exactly one repository. An **Epic**, and any **Story or Spike that still holds child work**, are coordination containers and may span repos.
 
 This invariant is enforced at four points: gate **S10** in the `*-validate-*` skills (write time), `task-decomposition` step 1.5 (PRD-decomposition time), **claim-time repo scoping** in the build-intake skills (when intake decides whether to claim a ready ticket for the current repo — see below), and the work-time split procedure below (when an agent picks up an existing ticket to implement it).

package/plugins/lisa/rules/reference/reset-seed-coverage.md

@@ -1,5 +1,60 @@
 # Reset/Seed Coverage & State Classification
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Reset/Seed Coverage & State Classification (load-bearing)
+
+**Every persistent entity a project owns carries exactly one declared reset policy, and a work item that adds or changes persistent state is not done until the reset/seed contract covers it.** An entity the running system holds but the contract does not classify is a contract violation, and the check that finds it **fails closed** — an unclassified entity is never treated as safe to keep and never treated as safe to delete.
+
+**One vendor-neutral contract, cited by** `lisa-research`, `lisa-acceptance-criteria`, `lisa-task-decomposition`, `lisa-test-strategy`, `lisa-implement`, `lisa-codify-verification`, `lisa-verification-lifecycle`, and `lisa-verify` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-skill prose). It never names a database engine, cloud, identity provider, or test runner — those are project configuration.
+
+## Why this exists
+
+Test suites create state. Without a contract, cleanup is a habit: a flow creates a uniquely-marked record and deletes it on the happy path only, so every early failure leaks one more. Nothing sweeps it, nothing complains, and the suite degrades until someone reads a flake as a product bug. The observed shape is always the same — leaked records accumulate silently until a list view, a uniqueness constraint, or a count assertion breaks. Per-flow self-cleanup is not coverage; it is the failure mode.
+
+## Membership
+
+Membership is **state, not repo name, ticket label, or storage engine**: an entity is in scope the moment something the project writes **outlives the process that wrote it**. That includes rows and tables, but rows are only one kind of state. Also in scope: identity-provider objects (accounts, groups, memberships, sessions), object storage (buckets, prefixes, uploaded files), search indexes, queues and topics (in-flight and dead-letter), caches with a persistence tier, materialized/derived views and projections, feature-flag and configuration overrides, scheduled jobs created at runtime, and analytics or third-party side effects a run leaves behind. Out of scope: values that live only in memory for the duration of one process.
+
+A work item is in scope when it **adds** such an entity, **changes what owns or writes** one, or **changes the lifetime** of one. Renames count as changes, not as new entities plus deletions.
+
+## The four policies
+
+Every entity is classified as exactly one of:
+
+- **`fixture-owned`** — the reset may create, mutate, and delete rows here, but only those it owns. Ownership is declared as a predicate (a reserved id shape, a reserved account or namespace, a marker attribute), never as "everything in this entity."
+- **`preserve`** — the reset must leave this untouched. Catalog, reference data, anything a migration seeds, anything expensive or impossible to rebuild, and any state belonging to someone who is not the fixture.
+- **`derived-rebuild`** — not authored by anyone; recomputed from its sources after the reset (projections, materialized views, search indexes, caches). The reset rebuilds it rather than clearing or preserving it, and proves it converged.
+- **`forbidden`** — the reset must be structurally unable to touch it: ledgers, payments, wallets, withdrawals, audit trails, anything irreversible. Declaring `forbidden` obliges naming the enforcement outside the script — a least-privilege role, a revoked grant, a separate account or credential boundary — because a script-only promise dies in the refactor that drops the safe caller.
+
+**Classify by provenance, never by observation.** "The table looked empty" is not evidence it is unused; runtime statistics are approximations, and a table that has never been analyzed reports rows it holds. Ask who writes it and whether anything can put it back.
+
+## Keep-lists are a detector, not the safety model
+
+Deriving the clear-list by subtracting a keep-list from a schema listing is a **useful detector** — run it, and let it flag entities the contract has not seen. It is not the boundary. It cannot model renames, multiple schemas, framework-generated entities, views, partitions, row-level ownership, or any of the non-DB state above, and "new entities are cleared unless exempted" erases unrelated data the first time something adds one. The boundary is the classification; subtraction only tells you the classification is stale.
+
+## Required assurances
+
+A reset contract is not complete until it declares, and points at evidence for, all of: non-fixture and catalog data survive; reserved fixture identifiers are rejected on collision with anything real; foreign references into preserved entities are refused rather than cascaded; every write is **acknowledged** (a mutation reported by the caller and not confirmed by the system is a failure, not a success); a second apply converges to the same state and reports no further change; the post-state is verified by **exact expected counts**, not "at least one"; and production fails closed with no override of any kind. Where the platform can enforce a boundary with roles, grants, or constraints, it does — the in-process guard remains as defense in depth, never as the primary control.
+
+## Definition of done
+
+A work item that adds or changes persistent state is not done until: (1) every entity it introduces or changes is classified in the project's state contract with a reason and an owner; (2) `fixture-owned` entities it introduces declare their ownership predicate **and** are actually swept by the reset — an entity a suite creates but nothing removes is the leak this rule exists to prevent; (3) `preserve`/`forbidden` entities it introduces name their enforcement; (4) any seed the suite depends on covers the new state, with the verify step asserting exact counts; and (5) the state-classification check passes in the same PR. **A missing or stale classification is a verification failure, not a warning** — it blocks completion exactly as a `PARTIAL` spec-conformance verdict does, and is never demoted to "optional", "if cheap", or a follow-up without a linked build-ready ticket created before merge.
+
+## Bootstrap, noop, and degradation
+
+A project with no state contract yet is not exempt: the first work item touching persistent state scaffolds the minimum (the contract file, its own entities classified, the check wired into CI) and covers **its own** state. It never backfills the whole system — pre-existing unclassified entities are recorded as burndown with an owner and a date, not treated as this item's blocker. A project that genuinely holds no persistent state declares a **machine-readable noop** (`mode: "declared-noop"` with reason, owner, and a capability-manifest reference) which the check verifies against the repo rather than taking on faith — a bare exit 0 is indistinguishable from a successful destructive run and never satisfies this rule. A project that cannot produce a runtime inventory records the checked sources and the absence, exactly as the regression-spec absence path in `verification` does; a silent skip is never one of the exits.
+
+## Command envelope
+
+Every reset, seed, verify, inventory, and classification adapter answers the **same interface** — one validated JSON result on stdout, exit 0 only when the operation both completed **and** verified, `--dry-run` mandatory before anything destructive, and a requested stage always re-checked against server-resolved identity rather than trusted. The envelope is specified in the reference body and is what makes "every repo answers the same question the same way" checkable instead of aspirational.
+
+**The production arm of this is executable, not advisory.** `scripts/lisa-destructive-guard.mjs` ships to every adopter and is wired into the envelope itself: a destructive run against a production-resolved — or unresolvable — environment has **no representable success envelope**, so it can never exit 0, and there is no parameter, field, or environment variable anywhere in the guard that changes the answer. A dry run is not an exemption, and `--dry-run` is the default rather than an opt-in. Read this as what it is: a check at the one interface every adapter passes through, which an adapter that misreports its own environment still defeats. The end state is a destructive capability that is **not deployed to production at all** — non-existence beats refusal — and that design, with the failure modes it must still close, is recorded in `docs/design/reset-production-absence.md`.
+
+---
+
 Automated suites create state, and the state outlives them. The historical pattern is per-flow
 self-cleanup: a flow creates a uniquely-marked record at the top and deletes it as its last step, so
 the record survives every failure that happens in between. Nothing sweeps the survivors and nothing

package/plugins/lisa/rules/reference/usage-accounting.md

@@ -1,5 +1,43 @@
 # Usage Accounting
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Usage Accounting (load-bearing)
+
+Lisa attaches AI usage and cost telemetry to every artifact it creates/updates. The format is a single canonical managed section.
+
+## Managed section
+
+Every artifact with inline body content gets exactly one section:
+
+```markdown
+## Lisa Usage
+```
+
+**Canonical. Rewrite in place; never append a second usage section.** If the host can't safely edit body, write the same section in a comment and treat that comment as the managed artifact for future rewrites.
+
+## Required field semantics
+
+Each direct entry records ONE logical Lisa run on ONE artifact. `entry_id` is the stable dedupe key — rewriting the same logical run with the same `entry_id` updates in place; a different run gets a different `entry_id`.
+
+- **`source`**: `observed` (runtime supplied) / `estimated` (derived from trustworthy metadata + pricing contract) / `measured-subset` (a trustworthy subtotal exists, but the complete run total is unknown) / `unavailable`.
+- **`measured_subset_tokens`**: optional measured subtotal for `measured-subset` entries only. Omission is normalized to `null` for backward-compatible callers. Keep `total_tokens = null` so rollups do not treat a subset as a complete total.
+- **`pricing_status`**: same trinary plus `missing` (cost not known but should be).
+- **Absence ≠ zero.** `null` means unknown; `0` means explicitly zero. Always write the entry — never silently omit.
+- Do NOT replace observed counts with estimates.
+
+## Rollup
+
+Container artifacts (Epic, PRD, etc.) roll up usage from their direct children. Roll-up is recursive — a parent's `## Lisa Usage` aggregates its descendants' direct entries. Re-writes are idempotent: re-running an intake or lifecycle skill must not duplicate entries.
+
+Measured-child incompleteness is durable across ordinary rewrites through the optional
+`lisa:usage-rollup-token-status` extension. Do not infer completeness merely because a rewrite did
+not re-fetch child ledgers.
+
+---
+
 Lisa usage accounting is a vendor-neutral contract for attaching AI usage and cost telemetry to the artifacts Lisa creates or updates. It governs the section shape, machine-readable tokens, source/pricing semantics, rollup behavior, and idempotent rewrite rules. Writer skills and lifecycle skills attach telemetry by following this contract; they do not invent artifact-local formats.
 
 ## Managed section

package/plugins/lisa/rules/reference/work-item-definition-of-ready.md

@@ -1,5 +1,37 @@
 # Work-Item Definition of Ready — Reference
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Work-Item Definition of Ready (type-keyed)
+
+**`ready` means: a stateless agent can claim this item and drive it to its terminal state with zero human clarification.** Every readiness gate exists because its absence forces a question; the bar is type-keyed because different work types break autonomy differently.
+
+## Shared core (every leaf, enforced by `*-validate-*` S1–S16)
+
+Three-audience description · Gherkin acceptance criteria (except Spike) · Out of Scope · single-repo scope · relationship search · typed evidence manifest on runtime changes · Source Requirement traceability when PRD-sourced · provable read access to every named external surface · declared reachability for any **existing** test the item pins as a red-before-green control (`control-reachability`, gate S20 — `N/A` when the item introduces a new test instead).
+
+## Per-type additions
+
+| Type | Must additionally carry | Terminal state is |
+|---|---|---|
+| **Bug** | agent-executable reproduction (or a failing test) · expected-vs-actual with the *source* of "expected" · environment + version observed, last-known-good when known · reproducibility rate (always / intermittent + frequency) · at least one occurrence evidence link | the same repro/test fails before the fix and passes after |
+| **Story** | user-visible AC; SHOULD name non-happy-path states (error / empty / loading) for UI stories · design source precedence when artifacts exist | every AC exercised on the running product |
+| **Task** | an observable done-state and the command/check that proves it | the verification check passes |
+| **Improvement** | metric + measurement method the agent can run · measured baseline value · numeric target | measured value meets the target |
+| **Spike** | the question · the decision it enables + options weighed · a timebox · deliverable format **and location** | a deliverable at the named location that answers the question — findings, decision, options weighed |
+| **Sub-task** | a parent, always · otherwise the bar of its own type | per its type |
+| **Epic / container** | never build-ready (`leaf-only-lifecycle`) · judged on decomposition completeness, not buildability | all required children terminal |
+
+## The stateless-pickup test (S18)
+
+The final gate checks the property itself instead of proxies for it: read the item as a fresh agent with no session context, using only the item and what it links to. List every question you would have to ask a human before starting, choosing between materially different implementations, or declaring done. **Ready = zero questions.** Each question found is the FAIL remediation, verbatim.
+
+Sources this bar distills: INVEST (stories) · ISTQB / IEEE 1044 defect anatomy and minimal-reproducible-example practice (bugs) · SMART (improvements) · Scrum's Definition of Ready (the framing) · TASC AC8.6 (the normative criterion).
+
+---
+
 The eager head carries the table; this reference carries the reasoning, the
 failure modes each requirement prevents, and worked examples. The enforcing
 gates live in the three tracker validators (`lisa-jira-validate-ticket`,

package/plugins/lisa/scripts/intake-blocker-reprobe.mjs

@@ -37,6 +37,143 @@ function normalizeLabels(labels) {
     .filter(label => label.length > 0);
 }
 
+/**
+ * Decoration a declaration may sit behind, and nothing more.
+ *
+ * Whitespace, blockquote arrows, list bullets or numbers, emphasis, a comment
+ * hash, and an opening HTML comment. `#` is there on EVIDENCE rather than
+ * taste: a shell script declares a hold as `# <marker> reason=…` — a bare
+ * marker behind a SHELL comment, with no HTML comment anywhere — and that form
+ * is in this repository's own guard fixtures. A single character class plus two
+ * optional groups —
+ * deliberately not a nested-quantifier pattern, because this runs over
+ * untrusted work-item bodies and `sonarjs/slow-regex` is right about that
+ * shape.
+ */
+const LEADING_DECORATION =
+  /^[ \t>*_+#-]*(?:\d+[.)][ \t]*)?(?:<!--[ \t]*)?[ \t]*/u;
+
+/**
+ * The body with fenced blocks and inline code spans removed.
+ *
+ * Documentation of a declaration is not a declaration, and a fenced example is
+ * how the declaration form gets written ABOUT. The same move
+ * `pr-arming-sweep.mjs` makes for the auto-merge-off marker
+ * (CodySwannGT/lisa#3986), and the same one `block-direct-issue-create.sh`
+ * makes when it strips heredoc bodies before tokenising argv.
+ * @param {unknown} body - The raw item body
+ * @returns {string} The body with quoted and code regions blanked out
+ */
+function declarativeText(body) {
+  return String(body ?? "")
+    .replace(/```[\s\S]*?```/gu, "")
+    .replace(/`[^`\n]*`/gu, "");
+}
+
+/**
+ * Whether an HTML comment on this line carries the marker.
+ *
+ * The second declaration form, and it is not a concession: an HTML comment is
+ * invisible when the body is rendered, so nobody writes one to TALK about the
+ * marker — a quotation has to be visible to be a quotation. Prose about the
+ * marker is written in sentences, code spans and fenced examples, all of which
+ * this rule already excludes.
+ *
+ * Scanned rather than pattern-matched. A regular expression with two lazy
+ * `[^\n]*?` runs around a literal is the ambiguous shape this module avoids
+ * elsewhere, and an indexOf walk is both linear and easier to be sure about.
+ * @param {string} line - One line of the body
+ * @returns {boolean} True when a comment on this line contains the marker
+ */
+function commentCarriesMarker(line) {
+  const segments = line.split("<!--");
+  for (let index = 1; index < segments.length; index += 1) {
+    const close = segments[index].indexOf("-->");
+    const inside =
+      close === -1 ? segments[index] : segments[index].slice(0, close);
+    if (inside.includes(HUMAN_GATE_MARKER)) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether one line DECLARES a hold rather than mentioning one.
+ *
+ * Two accepted forms, and the corpus says they cost nothing to combine:
+ * measured over this repository's 42 matching bodies, line-leading alone and
+ * line-leading-or-comment hold the SAME 29. The comment branch exists because
+ * the filing guard reads inputs that are not markdown documents — a one-line
+ * `--body` string and a shell script — where a declaration legitimately sits
+ * after other text on its line.
+ * @param {string} line - One line of the body
+ * @returns {boolean} True when the line declares a hold
+ */
+function declaresOnLine(line) {
+  if (line.replace(LEADING_DECORATION, "").startsWith(HUMAN_GATE_MARKER)) {
+    return true;
+  }
+  return commentCarriesMarker(line);
+}
+
+/**
+ * Count what a body says about the hold marker, split by what it MEANS.
+ *
+ * ## Why the substring test had to go
+ *
+ * `isHumanGated` asked one question — does the body contain the marker
+ * anywhere — and that form was deliberate, documented, and correct when it was
+ * written: *"it is a marker with no other meaning, so its presence IS the
+ * declaration."* The premise expired. The marker acquired a second meaning —
+ * **being discussed** — the moment the feature became something people file
+ * tickets about, so a sentence quoting it, a Gherkin line naming it, and a
+ * ticket about it all read as declared holds (CodySwannGT/lisa#3815).
+ *
+ * The consequence is not one skipped cycle. `planHumanGateReconciliation`
+ * removes the ready role and applies the human-needed label, so a false
+ * positive rewrites the item's own metadata and every later sweep agrees with
+ * the first. And the affected population GROWS with the documentation: 38
+ * matching bodies measured 2026-09-04, 42 on 2026-09-05.
+ *
+ * ## The rule
+ *
+ * A declaration is POSITIONAL — the marker leads its line, behind at most
+ * blockquote, list, emphasis or opening-comment decoration — evaluated after
+ * code regions are removed. Measured over this repository's 42 matching bodies:
+ * this holds 29 of them and correctly releases the two live ready-lane items
+ * that only discussed the marker.
+ *
+ * The stricter HTML-comment-only rule was measured and REJECTED: it holds only
+ * 18, dropping declarations that carry `human-needed` today. Losing a real hold
+ * is the unsafe direction and would need a retrofit of the tracker.
+ *
+ * ## Why it counts rather than answering yes or no
+ *
+ * A heuristic that silently drops candidates is indistinguishable from one that
+ * found none. Every occurrence this rule declines to honour is counted and
+ * reported, so "the rule demoted 33 mentions" is a fact an operator can read
+ * rather than an absence they must infer.
+ * @param {unknown} body - The item body
+ * @returns {{ total: number, declared: number, demoted: number }} Occurrences,
+ *   those that declare a hold, and those demoted to mentions
+ */
+export function humanGateMentions(body) {
+  const raw = String(body ?? "");
+  const total = raw.split(HUMAN_GATE_MARKER).length - 1;
+  const declared = declarativeText(raw)
+    .split("\n")
+    .filter(line => declaresOnLine(line)).length;
+  return { total, declared, demoted: total - declared };
+}
+
+/**
+ * Whether a body declares a hold, as opposed to discussing one.
+ * @param {unknown} body - The item body
+ * @returns {boolean} True when at least one line declares a hold
+ */
+export function bodyDeclaresHold(body) {
+  return humanGateMentions(body).declared > 0;
+}
+
 /**
  * Whether an item is held for a person, on either surface.
  *
@@ -64,7 +201,7 @@ export function isHumanGated(input) {
     return true;
   }
 
-  return String(input.body ?? "").includes(HUMAN_GATE_MARKER);
+  return bodyDeclaresHold(input.body);
 }
 
 /**
@@ -432,6 +569,26 @@ export function formatHumanGateNote() {
  * @param {readonly unknown[]} held - Item references held this cycle
  * @returns {string} One summary line
  */
+/**
+ * Render the cycle-summary line naming what the precision rule DEMOTED.
+ *
+ * The counterpart of {@link summarizeHumanGateHolds}, and it exists for the
+ * same reason: a mutation nobody can see afterwards is the problem this whole
+ * area keeps having. A rule that quietly declines to honour half the marker
+ * occurrences it sees reads exactly like a rule that saw none, so the count is
+ * printed even when it is zero — measured across this repository's matching
+ * bodies, 33 of 62 occurrences are mentions rather than declarations.
+ * @param {unknown} demoted - How many occurrences were mentions, not declarations
+ * @returns {string} One summary line
+ */
+export function summarizeHumanGateMentions(demoted = 0) {
+  const count = Number.isFinite(Number(demoted))
+    ? Math.trunc(Number(demoted))
+    : 0;
+  const shown = count > 0 ? String(count) : "none";
+  return `Marker mentions demoted (not declarations): ${shown}.`;
+}
+
 export function summarizeHumanGateHolds(held = []) {
   const names = (Array.isArray(held) ? held : [])
     .map(item => trimmedString(item))

package/plugins/lisa/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -1136,10 +1136,26 @@ not there, and a lifecycle step performed by hand is one nothing can verify
 happened.
 
 **The backstop, for the ones that still slip:** `lisa-work-item.mjs sweep`
-reports every claimed item that already has a merged pull request, and
+reports every open item — in the **ready** lane as well as the **claimed** one —
+that a commit on a deploy branch DECLARES via its `Work-Item:` trailer, and
 `--apply` completes them. Reporting is the default deliberately — a sweep that
 closes things as a side effect of being run is not one anyone runs twice.
 
+You do not need to run it. The `🧹 Lifecycle Drift Sweep` workflow runs it
+daily and files a deduplicated issue when drift exists, because a report with
+no consumer and no report are the same thing with different amounts of code.
+
+Two properties worth knowing, because both were once the other way round:
+
+- **Credit requires a declaration, never a mention.** Evidence is a commit
+  reachable from a deploy branch whose own trailer names the item. It used to
+  be a timeline cross-reference, which any pull request that so much as *named*
+  `#N` created — so one merged land-stack pull request made every sibling in
+  its batch look shipped. Measured: 8 of 53 reported items had no commit
+  declaring them, and every one of the 8 had live work open against it.
+- **A clean result names the lanes it examined.** "No drift" over a subject
+  list that excluded the ready lane was true and unusable.
+
 ## 4. Terminal states
 
 Loop until one of:

package/plugins/lisa/skills/lisa-github-build-intake/SKILL.md

@@ -332,6 +332,10 @@ other gate's verdict — however conclusive — may promote an item a person par
 4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
+   Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
+   — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
+   A rule that quietly declines to honour half the occurrences it sees reads exactly like a
+   rule that saw none, so the count is printed even when it is zero.
 5. **Continue to the next candidate.** A held item does not end the cycle.
 
 

package/plugins/lisa/skills/lisa-jira-build-intake/SKILL.md

@@ -237,6 +237,10 @@ other gate's verdict — however conclusive — may promote an item a person par
 4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
+   Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
+   — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
+   A rule that quietly declines to honour half the occurrences it sees reads exactly like a
+   rule that saw none, so the count is printed even when it is zero.
 5. **Continue to the next candidate.** A held item does not end the cycle.
 
 

package/plugins/lisa/skills/lisa-linear-build-intake/SKILL.md

@@ -231,6 +231,10 @@ other gate's verdict — however conclusive — may promote an item a person par
 4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
+   Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
+   — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
+   A rule that quietly declines to honour half the occurrences it sees reads exactly like a
+   rule that saw none, so the count is printed even when it is zero.
 5. **Continue to the next candidate.** A held item does not end the cycle.
 
 

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

@@ -994,7 +994,10 @@ with labels like `build-ready`, or with no Lisa status label at all, that are in
    instead — it says that nothing was changed and how a person resumes the item, which is the
    opposite of what the reconciliation note says and must not be substituted for it. A promotion
    declined silently is invisible, which is the quieter version of the failure this step exists to
-   prevent, so name every held item in the cycle summary via `summarizeHumanGateHolds([...])`.
+   prevent, so name every held item in the cycle summary via `summarizeHumanGateHolds([...])`. Report what the
+   precision rule skipped beside it via `summarizeHumanGateMentions(n)`: the marker
+   occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815),
+   because a rule that silently drops candidates reads like one that found none.
 
 ### Ungated non-ready filing → surface as an incomplete handoff (read-only)