@codyswann/lisa 4.74.9 → 4.75.0

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

@@ -0,0 +1,177 @@
+# 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 [the rule index](../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`,
+`lisa-github-validate-issue`, `lisa-linear-validate-issue`), which cite this
+rule so the bar cannot drift per vendor.
+
+## The design principle
+
+A readiness gate is justified by exactly one thing: **its absence forces a
+human question.** The goal state is that a stateless agent — fresh session, no
+memory of any prior conversation — claims any ready item and drives it to its
+terminal state with zero human clarification. Every requirement below is an
+answer to a question agents otherwise ask mid-flight, which is the most
+expensive time to ask it: the item is claimed, the human is absent, and the
+choice is stall (blocked, human round-trip) or guess (rework when wrong).
+
+The bar is **type-keyed** because work types break autonomy differently. A
+Story with perfect Gherkin but no design source makes the agent guess visuals.
+A Bug with perfect prose but no executable repro makes the agent guess whether
+it even fixed anything. One generic checklist over-asks some types (Gherkin on
+a Spike is noise) and under-asks others (three bullets on a Bug).
+
+## Bug — the defect anatomy
+
+Modeled on the ISTQB defect-report content list, IEEE 1044, and
+minimal-reproducible-example practice, tightened for a machine executor:
+
+1. **Agent-executable reproduction.** Numbered steps a stateless agent can run
+   mechanically: exact entry point, named account/role (consistent with the
+   Sign-in Required section when authenticated), concrete data state, exact
+   actions. "Open the dashboard and click around until it breaks" is
+   human-followable, not agent-executable — it FAILs. A linked failing test
+   satisfies this requirement outright and is the preferred form.
+2. **Expected vs. actual, with the source of "expected."** Name or link where
+   the expected behavior comes from — spec, PRD requirement, prior release. A
+   fix target must be a fact, not an opinion, or the agent can confidently fix
+   to the wrong behavior.
+3. **Environment and version.** Where reproduced, and the build/commit
+   observed. Include last-known-good when known — that regression window is
+   what makes bisection possible. `unknown` is acceptable but must be stated.
+4. **Reproducibility rate.** Always vs. intermittent (with observed
+   frequency). An intermittent bug invalidates run-the-repro-once as a
+   verification plan; the verifier needs to know to run it N times or
+   instrument instead.
+5. **Occurrence evidence.** At least one link or attachment proving the bug
+   happened: error-tracker issue, log excerpt, stack trace, screenshot or
+   recording. Input evidence, distinct from the output evidence manifest.
+
+**Terminal state:** the reproduction (or failing test) fails before the fix
+and passes after — both runs captured under the evidence manifest. This is
+what makes a Bug autonomously closable: done-ness is a mechanical check, not a
+judgment.
+
+## Story
+
+The generic gates (three audiences, Gherkin, Out of Scope, source precedence)
+were designed around Stories, so Stories are the best-covered type already.
+The additional expectations:
+
+- UI-touching stories SHOULD name the non-happy-path states — error, empty,
+  loading — in the AC. These are the states product-walkthroughs flag as
+  missing after the fact; naming them up front converts a review finding into
+  a requirement.
+- Keep stories INVEST-small: a story too large to hold in one session is the
+  leading cause of mid-flight questions. Prefer decomposition over heroics.
+
+**Terminal state:** every AC scenario exercised against the running product.
+
+## Task
+
+A Task is "do this specific thing" — its risk is a fuzzy finish line, not a
+fuzzy user. It must carry an observable done-state and the command or check
+that proves it ("`bun run verify:x` exits 0", "the workflow file validates and
+the job appears in CI"). **Terminal state:** that check passes.
+
+## Improvement — the measured delta
+
+An Improvement without numbers has no verifiable terminal state by
+construction: "make it faster" can never be autonomously closed. Required:
+
+1. **Metric + measurement method** the agent can run (command, query,
+   dashboard export — something mechanical).
+2. **Baseline** — the current measured value. A number, not an adjective.
+3. **Target** — the numeric value or bound that defines done.
+
+If no baseline exists yet, measuring it is the first task — file it as such.
+**Terminal state:** the measurement method reports a value meeting the target.
+
+## Spike — the investigation contract
+
+A Spike's output is knowledge, so its readiness is about making knowledge
+checkable:
+
+1. **The question** being answered.
+2. **The decision it enables**, and the options being weighed — so the answer
+   is written to be decidable against, not merely interesting.
+3. **A timebox** — spikes without one become open-ended research.
+4. **Deliverable format and location** — decision doc, prototype, findings
+   page, and *where it will live* (wiki page, decision record, attachment).
+
+Gherkin AC is intentionally N/A for Spikes (S4 already exempts them).
+**Terminal state:** a deliverable exists at the named location **and answers the
+question** — it records the findings, the recommended decision, and the
+options weighed. An empty or placeholder document at the right path is not
+terminal.
+
+## Sub-task
+
+Always has a parent (no stranded-leaf exception), and otherwise carries the
+bar of its own nature — a bug-shaped sub-task carries the bug anatomy.
+
+## Epic and containers
+
+Containers are never build-ready (`leaf-only-lifecycle`); their readiness
+question is decomposition completeness — does every PRD requirement trace to a
+leaf (`prd-ticket-coverage`) — not buildability.
+
+## The stateless-pickup dry-run (gate S18)
+
+Structure gates are proxies; this gate checks the property directly. The
+validator simulates a stateless read of the item plus its resolvable links —
+session knowledge deliberately excluded, because the next claimant will not
+have it — and lists every question it would need answered before starting,
+before choosing between materially different implementations, or before
+declaring done. Zero questions = PASS. Each question found is emitted verbatim
+as its own remediation line; those lines are exactly the clarifying comments
+the caller posts to the source. This is the enforcement of the intake
+contract's core promise, and of TASC AC8.6: *ready means zero-clarification
+executable.*
+
+## Relationship to the lifecycle
+
+- **Write time** — `*-write-*` runs the applicable pre-write gates; a spec
+  failing the type-keyed bar is repaired or rejected before it exists. S18 is
+  not a write-time gate — most specs are not yet build-ready when written.
+- **Ready time** — the bar is what the build-ready role asserts, and S18 runs
+  here, on build-ready leaves only, making the assertion checked rather than
+  hoped.
+- **Claim time** — `ticket-triage` remains the analytical deep-check against
+  the codebase (edge cases, duplicate work, rework classification). With this
+  bar enforced upstream, triage's ambiguity phase should find nothing a
+  validator could have caught — its findings become a monitoring signal for
+  gaps in this rule.

package/plugins/lisa-devin/rules/reference/work-item-trailer-definition.md

@@ -0,0 +1,129 @@
+# Work-Item Trailer Definition — What Counts As One, And Which Reader Is Authoritative
+
+Read this **before** writing anything that reads, counts, audits, or verifies a
+`Work-Item:` reference in a commit message or a pull-request body. There are two
+plausible definitions of "a `Work-Item:` trailer", they disagree about real
+commits in this fleet, and the obvious tool — git's own trailer parser — is the
+wrong one.
+
+## The two definitions
+
+**Definition A — git's.** `git log --format='%(trailers:key=Work-Item)'` and
+`git interpret-trailers --parse` read only the **final contiguous block** of
+`Key: value` lines. Any non-trailer line after a trailer ends that block, and
+everything above it becomes invisible to the parser.
+
+**Definition B — Lisa's.** A `Work-Item:` line is any line of the **whole
+message** whose first character begins the ASCII-case-insensitive prefix
+`Work-Item:` at **column zero**, with a non-empty value after it. Position in
+the message carries no information. Repeats of the same reference are accepted.
+
+## Definition B is authoritative. This is settled, not open.
+
+Definition A was tried and abandoned in CodySwannGT/lisa#2672: it reported
+`found 0` about messages that plainly contained a trailer, because a blank line
+before the `Co-Authored-By:` attribution block — or a bot appending release
+notes below it — was enough to end the block. Making Definition A work would
+require that nothing ever append to a commit message, which is precisely the
+assumption #2672 recorded as false.
+
+The `🤖 Generated with Claude Code` convention puts boilerplate **after** the
+trailer by default, so under Definition A a large share of this repository's own
+commits read as untrailered. **The failure is the common case, not the edge
+case.**
+
+### Measured, not asserted
+
+Both definitions run over real history, non-merge commits, counting only commits
+where at least one definition finds a reference:
+
+| Range | Commits naming an item | Agree | A finds none, B finds one | Other disagreement |
+|---|---|---|---|---|
+| A single multi-agent branch | 51 | 4 | **47 (92%)** | 0 |
+| Full default-branch history | 1,730 | 1,248 | **477 (27.6%)** | 5 |
+
+The five "other" disagreements are commits carrying a bare `Work-Item: #1234`
+above the block as well as the canonical reference inside it; B sees both, A
+sees only the one in the final block.
+
+**The undercount is clean, plausible and well-formed**, which is why it survives
+review. `%(trailers)` printing nothing is genuinely convincing evidence until
+you know this rule exists — which is why at least three separate audits have
+shipped confident, specific, wrong findings from it, including an instruction to
+amend a commit whose trailer was fine.
+
+## Do not reimplement it. Import it.
+
+`workItemLines(message)` and `soleWorkItem(text, contract, subject)` are
+exported from the shipped `scripts/lisa-work-item.mjs`. They are the definition.
+A second parser is a second answer to "which item is this?", and two answers is
+the state this rule exists to end.
+
+```js
+import { workItemLines } from "./lisa-work-item.mjs";
+```
+
+`workItemLines` returns every value found, in order of appearance, untouched
+beyond trimming. `soleWorkItem` canonicalizes them against the tracker contract
+and refuses a text naming two **different** items.
+
+## What each layer owns, and why the shape filter stays at the call site
+
+`workItemLines` deliberately does **not** validate the shape of a value. It
+answers "what does this text say?" — nothing more. Canonicalization,
+repository-membership, and the refusal of the full issue-URL form all live in
+`canonicalizeRef`, above it.
+
+That split is load-bearing and must not be converged away. A reader that
+filtered malformed values out during the scan would make a bad value
+**invisible** rather than **refused**: `Work-Item: https://github.com/o/r/issues/7`
+would read as no trailer at all, and the gate would report "no Work-Item trailer
+anywhere in the commit message" about a message containing exactly one, which is
+the #2672 failure re-created one layer down. The reader sees everything; the
+layer above decides what is acceptable.
+
+The consequence a caller must respect: **a filter you apply to `workItemLines`'
+output is your filter, not the definition.** State what it drops.
+
+## Column zero is part of the definition
+
+The prefix is anchored at column zero, so `# Work-Item: …` in a comment never
+matches, and neither does a unified-diff line — every one of those carries a
+space, `+` or `-` in that column. A reader that tolerates leading whitespace
+matches the **context line of a verbose commit's own diff**. Measured over full
+default-branch history: 2,059 `Work-Item:` lines at column zero, **zero**
+indented ones. There is no real input that needs the looser form and one class
+of false positive that needs the anchor.
+
+The prefix is matched with a non-Unicode `/i` regex rather than
+`toLowerCase().startsWith(…)` on purpose: `toLowerCase()` applies full Unicode
+case mapping, so U+212A KELVIN SIGN would fold to `k` and `WorK-Item:` written
+with it would be accepted — a form this has never accepted.
+
+## Testing a trailer reader
+
+**A checker exercised only against well-formed messages passes under either
+definition.** That is why three audits shipped with the bug undetected. The only
+input that distinguishes them is a `Work-Item:` line sitting **above** a
+non-trailer line, and any test of a trailer reader must pin one:
+
+```
+feat: something
+
+Work-Item: owner/repo#123
+
+🤖 Generated with Claude Code
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Under Definition A this message has no work item. Under Definition B — the
+authoritative one — it names exactly one. Assert **present**.
+
+## Related
+
+- `tracked-work` (eager) — the obligation to carry the ref on every commit
+- `settled-decisions` — why this is recorded as closed rather than re-litigated
+- CodySwannGT/lisa#2672 — where Definition A was tried and abandoned
+- CodySwannGT/lisa#3747 — where the decision was made discoverable
+- CodySwannGT/lisa#3859 — the same undercount measured on the audit side