@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/rules/reference/tool-access-gate.md

@@ -0,0 +1,114 @@
+# Tool Access Gate
+
+- If you can't reach something you need, such as a repository, a secret, an API, or a connector, say exactly what's missing in your first message and stop. Don't substitute, mock, or guess.
+
+If the missing access is discovered after work begins, say exactly what's
+missing in your next message and stop.
+
+A flow may only take on work it can actually finish. If completing a work item —
+including its empirical verification — requires an external tool or system the
+agent cannot access, the flow must **tell the user exactly what access is missing and stop**, never
+work around it. This is the flow-side arm of the factory
+contract: intake validates that the factory has "the tooling *and provable
+access to that tooling*"; this gate re-proves that promise at execution time and
+enforces it for tools discovered mid-flow.
+
+"Tool" means any external surface the work depends on, for example:
+
+- Cloud/provider CLIs and APIs: AWS (CloudWatch logs, S3, …), GCP, Azure
+- Design sources: Figma
+- Bug/session capture: Jam
+- Observability: Sentry, PostHog, CloudWatch
+- Quality gates: SonarCloud
+- Trackers and docs: JIRA/Confluence, Linear, Notion, GitHub
+- Device/browser harnesses: Playwright, Maestro, Detox, simulators/emulators
+- Databases, deploy targets, and protected environments
+
+## When the gate runs
+
+1. **Preflight** — after the completion condition is defined and before any
+   implementation task starts, enumerate every tool required by (a) the
+   implementation itself, (b) the proof command / verification plan, and
+   (c) remote verification and post-deploy checks. Sources for the enumeration:
+   the work item (description, comments, attachments — a Figma link or Jam
+   capture implies that tool), acceptance criteria, `testing_requirements`,
+   the `verification` metadata, and the deploy pipeline for the target
+   environment.
+2. **Continuously** — the moment a previously unknown tool requirement surfaces
+   mid-flow (e.g. verification turns out to need CloudWatch log capture), probe
+   it right then. If access is unavailable, report it and stop. Otherwise, record
+   the new tool + probe result in the same places the
+   preflight wrote to (the plan/tracker artifact and the affected tasks'
+   `metadata.required_access`) before continuing. Discovery timing changes
+   nothing about the protocol.
+
+## Proving access
+
+Access is proven by a **cheap, read-only probe that actually exercises the
+authenticated surface** — tool presence on PATH is not access.
+
+- Vendors with an access layer MUST be probed through their `*-access` skill
+  (see the `integration-access-layer` rule): `lisa-atlassian-access`,
+  `lisa-notion-access`, `lisa-linear-access`, `lisa-jam-access`,
+  `lisa-sonarcloud-access`, `lisa-sentry-access`, `lisa-posthog-access`,
+  `lisa-expo:play-store-access`. A loud access-skill failure naming a missing
+  env var IS a failed probe.
+- Vendors without an access layer are probed with the cheapest authenticated
+  read the runtime offers (an MCP tool call, a CLI read, a REST GET).
+
+Example probes:
+
+| Tool | Probe |
+|---|---|
+| AWS CLI | `aws sts get-caller-identity`, plus the service-level read the task needs (e.g. `aws logs describe-log-groups --max-items 1`) |
+| GitHub | a repository-scoped read against the target repo (e.g. `gh api repos/<owner>/<repo> --jq .full_name`, or the exact read the work item needs) — `gh auth status` alone only proves host auth, not access to the repository |
+| Figma | a read call against the linked file via the available Figma MCP/API surface |
+| Sentry / Jam / SonarCloud / PostHog / Atlassian / Linear / Notion | the matching `*-access` skill's resolve/auth check |
+| Database | the project's documented read-only connection check |
+| Deploy target | reach the target environment with the credentials the verify step will use |
+| Device/browser harness | the harness's own doctor/smoke entry (e.g. `playwright --version` plus a trivial headless launch) |
+
+Resolve credentials through the documented sources before probing: project
+e2e config/fixtures, `.lisa.config.local.json` and environment variables, then
+documented work-item credentials (e.g. `Sign-in Required`). If the documented
+access path or probe cannot provide the required access, report the gap and
+stop. Do not continue exploring substitute sources after confirming the gap.
+
+Record successful probes in the flow's plan/tracker artifact
+(and task `metadata.required_access` where the flow's task contract carries
+it), so the verifier can confirm the gate ran.
+
+## On failure: break out, never work around
+
+When required access is unavailable, tell the user and stop. Use the first
+message if the gap is already known, or the next message if it is discovered
+mid-task. The message must state:
+
+- the exact resource that cannot be reached and the operation it blocks;
+- the observed failure and, if known, the credential name, role, permission, or
+  invitation needed — never secret values, and never a guessed diagnosis;
+- the read-only probe that must pass before work can resume.
+
+Do not substitute, mock, guess, or continue other tasks as a workaround.
+Reporting does not depend on access to a tracker, and it does not require
+creating a new ticket. Resume after the required access is available and its
+probe passes.
+
+### Forbidden workarounds
+
+None of the following ever substitutes for missing access:
+
+- Swapping the verification for a weaker one the agent *can* run (unit tests or
+  code reading instead of the required log capture / UI observation).
+- Mocking, stubbing, or simulating the inaccessible system to make the proof
+  "pass".
+- Marking work done on artifact-only evidence, or asserting success without the
+  runtime evidence the completion condition demands.
+- Guessing at the tool's contents (e.g. implementing a design without reading
+  the linked Figma file, or "fixing" a bug without the Jam/Sentry evidence the
+  ticket points at).
+- Silently narrowing scope so the inaccessible part is "out of scope".
+
+Keep results already obtained, but stop further work until the required access
+is available. An inaccessible tracker does not prevent reporting the blocker
+to the user. Do not claim blocked acceptance criteria have passed.

package/plugins/lisa-devin/rules/reference/tracked-work.md

@@ -0,0 +1,49 @@
+# Tracked Work
+
+Apply `do-it-now` before creating work from incidental findings. Declining an observation needs no new ticket. Related small accepted repairs may share one bounded maintenance leaf; traceability does not require a separate item for every nit.
+
+The project tracker is the durable operator-facing record for project work. Every session that will produce a durable project outcome must establish exactly one live configured-tracker leaf before the first durable mutation. Durable outcomes include code, tests, configuration, documentation, committed research or plans, investigation findings, commits, and pull requests. Read-only questions, discussion, and repository orientation are exempt until they turn into durable work.
+
+## Resolve, claim, bind
+
+Use `lisa-track` as the single entry point:
+
+1. An explicit ticket is live-read through `lisa-tracker-read` and rejected if it is missing, inaccessible, terminal, a container, outside the configured project, or outside the current repository.
+2. A plain-text request or specification file is searched conservatively within the configured project. Reuse only one uniquely high-confidence matching live leaf. If no unique match exists, create exactly one complete single-repository leaf through `lisa-tracker-write`; never create a thin placeholder or a container.
+3. Idempotently claim the resolved leaf through `lisa-tracker-claim`, which reuses the vendor build-intake claim semantics and post-read verifies the claimed-or-later state.
+4. Before any durable repository work, persist the canonical reference with `node scripts/lisa-work-item.mjs link <ref>` and verify the worktree-local binding.
+
+`link` is the spelling to use. `bind` is accepted as a permanent alias for the identical operation, but some agent harnesses — Claude Code's worktree isolation among them — refuse any command line containing the bare token `bind`, because it names a shell builtin that evaluates a string. Inside an isolated worktree that refusal makes the `bind` spelling unrunnable, so reach for `link` and never work around a blocked binding by hand-writing `Work-Item:` trailers.
+
+The sequence is strict: **live validate/create -> claim -> link -> durable work**. A tracker answer of no, and any claim or binding failure, blocks the work. A tracker that cannot be reached — `gh` absent, or its credential refused — does not block a commit: the offline checks still run, the skip is loud on stderr, and the required `Work-Item Traceability` check re-runs the live checks with credentials before anything merges. Any other tracker failure still blocks. Tool presence or stale session text is not access.
+
+## A pull request that carries several work items
+
+One work item per pull request is the default and is what almost every branch
+should do. It is not, however, a rule the commits can express on their own: an
+integration or stacking branch that gathers several finished items before one
+pull request has no edit to any commit that makes its range name a single item.
+
+So the rule lives on the pull-request BODY, which is where an author can say
+what a pull request is about and a reviewer can check it. The body must declare
+EXACTLY the set of work items its commits carry — one `Work-Item:` line per
+item. An item the commits carry and the body omits is refused; an item the body
+declares and no commit carries is refused too, so padding the declaration is not
+a way out. Every declared item is still proved live, open, repo-scoped, a leaf,
+and (under `workItem.verify: "full"`) separately backlinked.
+
+Batching is likewise a property of the push rather than of a branch: `git push`
+carrying several ref updates validates each pushed ref on its own, exactly as if
+each branch had been pushed alone.
+
+## One canonical identity
+
+The binding is authoritative for the worktree. Branches, commits, pull requests, usage accounting, evidence, and tracker-sync operations all carry the same canonical ref. Branch names are helpful discovery metadata but are not authoritative. After branch creation, `node scripts/lisa-work-item.mjs attach-branch` may attach the local branch to the binding.
+
+Linkage is unconditional for an Implement flow because its input gate always establishes a work item. PR creation must pass the ref to `lisa-git-submit-pr`; `lisa-tracker-sync` must prove the reverse native link or its managed fallback.
+
+## Binding lifetime
+
+Binding state is local machine state and must remain untracked. Keep it through interruptions and blocked outcomes. Run `node scripts/lisa-work-item.mjs clear` only after true terminal completion: required merge/deploy/verification is complete, evidence and two-way PR linkage are recorded, and the tracker item is in its terminal state. Verify that no current binding remains before ending the completed flow.
+
+Git hooks and CI enforce this contract but never create work items. Their recovery message directs the operator to mention the related ticket or run `/lisa:track <description>` to create and bind one.

package/plugins/lisa-devin/rules/reference/upstream-to-lisa.md

@@ -0,0 +1,26 @@
+# Upstream To Lisa
+
+A root cause in a Lisa-distributed artifact determines the destination of a worthwhile repair. First apply `do-it-now`'s **Worth doing** guidance. Ownership, a missing guard, or a reproducible edge case alone does not justify another issue.
+
+## Accepted repairs
+
+A concrete delivery failure, credible material safety risk, or recurring costly friction in a Lisa template, rule, skill, agent, hook, or CI workflow belongs upstream.
+
+| Template class | Local fix survives `lisa apply`? | Why repair upstream? |
+| --- | --- | --- |
+| **copy-overwrite** | No | Prevent the local repair being replaced by the broken source. |
+| **create-only** | Yes | Stop new projects inheriting the defect. |
+
+A header saying `Lisa will not overwrite it` is a positive upstream ownership signal, not a reason to keep an accepted defect local. It does not establish priority or value.
+
+1. **Unblock the current task if needed.** Apply the smallest safe local stopgap. Keep it scoped and attributable; do not stall useful delivery waiting for an upstream release.
+2. **Search before filing.** Search open AND closed issues in the configured upstream repository (`hardening.upstreamRepo`, default `CodySwannGT/lisa`). Reuse a matching open issue. Honor **Not planned** decisions under `rejection-detection`'s **Proposal rejection memory**, including legacy unmarked issues. Check actual behavior before treating a completed issue as a regression.
+3. **File only the accepted work.** Use `lisa-github-write-issue` against the upstream repository, with the explicit readiness declaration from `ready-role-filing`. State the owning source, observed consequence or credible risk, smallest durable fix, and any local stopgap. Follow the public-safe attribution/projection procedure; never publish host names, credentials, or private source paths.
+
+Bundle related minor repairs into one bounded maintenance item when the combined benefit warrants it. Declined observations require no ticket or escalation. A generalizable governance pattern still has to justify its recurring cost across consumers; generality alone is insufficient.
+
+## Access and scope
+
+If an accepted upstream repair cannot be filed because access is missing, prepare the public-safe issue and explain the access problem. Do not ask a human to file observations already declined on value.
+
+Do not mistake editing an installed artifact for changing Lisa's source. Inside Lisa itself, use the existing tracked task, repair the shared source, and regenerate equivalent agent surfaces; no second upstream issue is needed.

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

@@ -0,0 +1,261 @@
+# 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 [the rule index](../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
+
+Artifacts that support inline body/description content use a single managed section:
+
+```markdown
+## Lisa Usage
+```
+
+The section is canonical. Rewrite it in place; never append a second usage section under a different heading. If an artifact host cannot safely edit the body, write the same section format in a comment instead and treat that comment body as the managed usage artifact for future rewrites.
+
+The visible body is for humans; the hidden tokens are for machines. Both are required.
+
+## Direct-entry schema
+
+Each direct usage entry records one logical Lisa run or sub-run on one artifact. The required semantic fields are:
+
+| Field | Meaning |
+|---|---|
+| `entry_id` | Stable dedupe key for this logical usage entry. Unique within the artifact graph. |
+| `flow` | `research`, `plan`, `implement`, `verify`, `debrief`, `intake`, `repair-intake`, `monitor`, or a command slug. |
+| `run_id` | Runtime/session identifier when available; empty only when the runtime exposes no stable run id. |
+| `provider` | Model provider name. |
+| `model` | Model identifier. |
+| `source` | `observed`, `estimated`, `measured-subset`, or `unavailable`. |
+| `input_tokens` | Prompt/input tokens, or `null` when unavailable. |
+| `cached_input_tokens` | Cached/reused input tokens, or `null` when unavailable/not exposed. |
+| `output_tokens` | Output/completion tokens, or `null` when unavailable. |
+| `reasoning_tokens` | Reasoning/internal tokens, or `null` when unavailable/not exposed. |
+| `total_tokens` | Total trustworthy tokens for the entry, or `null`. |
+| `measured_subset_tokens` | Optional trustworthy measured subtotal for a known subset of the run. Omission is normalized to `null` so callers written before this field remain source-compatible. |
+| `cost` | Observed or estimated cost for this entry, or `null`. |
+| `currency` | ISO currency code when `cost` is known, otherwise `null`. |
+| `pricing_status` | `observed`, `estimated`, `missing`, or `unavailable`. |
+| `pricing_source` | Runtime billing source, config/pricing snapshot ref, or `null`. |
+| `artifact_ref` | Canonical ref of the artifact carrying the entry. |
+| `parent_artifact_ref` | Canonical parent artifact ref when the entry is attached below a parent, otherwise empty. |
+
+`entry_id` must be stable across rewrites of the same logical run. Rewriting an existing entry with the same `entry_id` updates it in place. A different run gets a different `entry_id` and is appended as a new direct entry.
+
+## Source semantics
+
+`source` describes how trustworthy the token counts are:
+
+- `observed`: the runtime supplied the usage directly. Do not replace observed counts with estimates.
+- `estimated`: Lisa derived counts or cost from trustworthy runtime metadata plus an explicit pricing contract. Estimates are allowed only when the derivation inputs are real and attributable to the run.
+- `measured-subset`: Lisa measured a known subset of the run, but not enough to claim a complete `total_tokens` value. Preserve the subtotal in `measured_subset_tokens`, keep `total_tokens = null`, and keep rollup totals unknown instead of treating the subset as the whole run.
+- `unavailable`: Lisa could not obtain trustworthy usage data. Write the entry anyway with `null` token/cost fields rather than silently omitting the row.
+
+The absence of data is never treated as zero. `null` means unknown; `0` means explicitly observed or derived zero.
+
+For example, an unavailable Verify run still records a direct entry with `source = unavailable`,
+`pricing_status = unavailable`, and `null` token/cost fields so downstream readers can distinguish
+"missing telemetry" from "zero usage." A Plan run with measured sub-agent usage but unmeasured
+main-loop usage records `source = measured-subset`, `measured_subset_tokens = <subtotal>`, and
+`total_tokens = null` so the subtotal is durable without being misrepresented as the complete run
+total.
+
+## Pricing semantics
+
+`pricing_status` describes how trustworthy the money fields are:
+
+- `observed`: runtime supplied a trustworthy monetary cost.
+- `estimated`: Lisa calculated cost from trustworthy token counts plus explicit pricing metadata.
+- `missing`: token counts are known but no trustworthy price source exists yet.
+- `unavailable`: the runtime exposed neither trustworthy cost nor enough trustworthy token data to estimate cost.
+
+Runtime-observed cost always wins over estimates. Estimated cost never overwrites an observed value. Missing pricing preserves token counts and a `null` cost.
+Token completeness and cost trust are independent: a `measured-subset` entry may still carry an
+observed trustworthy whole-run cost. Token rollups remain unknown, but that cost participates in
+cost rollups under the normal pricing and currency rules.
+
+## Machine-readable tokens
+
+Every visible direct entry row has a corresponding backward-compatible 17-field primary token:
+
+```text
+<!-- lisa:usage-entry entry_id=<id> flow=<flow> run_id=<run-id> provider=<provider> model=<model> source=<source> input_tokens=<n|null> cached_input_tokens=<n|null> output_tokens=<n|null> reasoning_tokens=<n|null> total_tokens=<n|null> cost=<decimal|null> currency=<code|null> pricing_status=<status> pricing_source=<ref|null> artifact_ref=<ref> parent_artifact_ref=<ref-or-empty> -->
+```
+
+**Entry tokens are never rendered inside a table row.** They occupy their own lines below the
+visible table, and they correlate to their rows by `entry_id`, not by position. Hosts that
+normalize markdown re-serialize a table from its parsed cell model and discard anything that is
+not a cell: measured against Linear on 2026-08-04, an HTML comment trailing a table row is
+destroyed on write while the same comment on its own line round-trips byte-identically. The
+row-trailing layout therefore produced a ledger that reported a successful write, rendered
+correctly for humans, and enumerated **zero** entries — with a surviving rollup token still naming
+them. Parsing is position-agnostic and always has been, so sections written in the historical
+row-trailing layout still enumerate, and migrate to the own-line layout on their next rewrite.
+
+The primary token is immediately followed on the same line by a correlated measured-subset
+extension. Writers serialize an omitted value as `null` instead of `undefined`:
+
+```text
+<!-- lisa:usage-entry-measured-subset entry_id=<id> measured_subset_tokens=<n|null> -->
+```
+
+The primary field order is fixed and deliberately matches the pre-measured-subset contract so
+legacy 17-field readers continue to enumerate entries. Current readers correlate the extension by
+its percent-encoded `entry_id`. They also accept the `@codyswann/lisa@2.222.0` transitional marker,
+which placed `measured_subset_tokens` between `total_tokens` and `cost`, and migrate it to the
+primary-plus-extension layout on rewrite. Only that transitional additive field accepts the literal
+`undefined` emitted by an older caller and normalizes it to `null`; established numeric fields
+remain strict. String fields are percent-encoded before rendering and decoded after parsing, so
+whitespace, commas, and HTML comment terminators inside source values cannot split or truncate the
+token.
+
+Every managed section also ends with exactly one rollup token:
+
+```text
+<!-- lisa:usage-rollup direct_entry_ids=<csv> child_entry_ids=<csv> child_refs=<csv> direct_tokens=<n|null> child_tokens=<n|null> total_tokens=<n|null> direct_cost=<decimal|null> child_cost=<decimal|null> total_cost=<decimal|null> currency=<code|null> -->
+```
+
+- `direct_entry_ids` enumerates the entries attached directly to the current artifact.
+- `child_entry_ids` enumerates deduped descendant entry ids included in the rollup.
+- `child_refs` enumerates the child artifacts consulted for the rollup.
+- `total_*` fields equal direct plus child totals over the deduped entry set.
+
+If a direct entry or freshly resolved child entry is `measured-subset`, the corresponding token
+scope and combined `total_tokens` are `null`; a measured subtotal is never added to complete token
+counts. Other established nullable-entry behavior is unchanged. Cost rollups are computed
+independently, so a trustworthy whole-run cost is not discarded merely because token completeness
+is unknown.
+
+When freshly resolved child work contains a measured subset, the primary rollup token is followed
+by this optional backward-compatible extension:
+
+```text
+<!-- lisa:usage-rollup-token-status child_tokens_incomplete=true -->
+```
+
+The extension preserves child-token incompleteness across ordinary direct-entry rewrites that do
+not resolve children again. It is omitted when child token totals are not known to be incomplete,
+so legacy rollup objects and readers retain their established shape.
+
+The rollup token is the machine-readable summary. The visible rollup table mirrors it for humans. List fields are comma-delimited after encoding each item independently; commas inside an item are encoded as data, not treated as separators.
+
+## Visible rendering contract
+
+The canonical body layout is:
+
+```markdown
+## Lisa Usage
+
+_Managed by Lisa. Regenerated on each usage update; do not edit by hand._
+
+### Direct Usage
+
+| Flow | Model | Source | Tokens | Cost |
+|---|---|---|---:|---:|
+| ...human-readable rows, cells only, no tokens... |
+
+<!-- lisa:usage-entry ... --> <!-- lisa:usage-entry-measured-subset ... -->
+
+### Rollup
+
+| Scope | Tokens | Cost |
+|---|---:|---:|
+| Direct | ... | ... |
+| Child | ... | ... |
+| Total | ... | ... |
+
+<!-- lisa:usage-rollup ... -->
+```
+
+Every machine-readable token sits on its own line, outside every table. One entry contributes one
+token line; multiple entries contribute consecutive token lines in the same order as their visible
+rows.
+
+Writers may add host-specific surrounding prose, but they must preserve the heading, the managed-note line, the direct-entry tokens, and the single rollup token.
+
+## Write verification
+
+A write surface can accept a section, report success, and silently destroy part of it. **Verify
+every managed write by reading the stored bytes back and parsing them — never by the mutation's
+return value.** A write is successful only when the stored surface satisfies the rollup/entry
+agreement invariant below. A caller that cannot verify a surface must fall back to one it can, or
+fail loudly; it must never report success over an unreadable ledger.
+
+- Every `entry_id` in the rollup's `direct_entry_ids` resolves to a parseable direct entry in the
+  same section.
+- Every parseable direct entry in the section appears in the rollup's `direct_entry_ids`.
+- Every entry the caller just wrote is parseable from the stored surface.
+
+`verifyLisaUsageSectionIntegrity` in the shared utility layer implements exactly these checks and
+returns structured issue codes (`missing-section`, `missing-entry-token`, `missing-rollup-token`,
+`unrecorded-entry`). Callers run it against the read-back body, not against the payload they sent.
+
+## Rollup and dedupe behavior
+
+Rollups aggregate descendant usage from native tracker hierarchy, documented generated-work references, and explicit `parent_artifact_ref` links. Within one artifact rollup:
+
+- Dedupe strictly by stable `entry_id`.
+- Count each `entry_id` at most once even if the same descendant is discoverable through more than one path.
+- Preserve direct totals separately from child totals.
+- Exclude descendant entries whose `entry_id` is already present in the artifact's direct-entry set.
+
+Concrete example: if child artifact A and child artifact B both surface descendant entry
+`verify-123`, the parent rollup lists `verify-123` once in `child_entry_ids`. If the parent also
+records `verify-123` directly, exclude that descendant copy from child totals and keep the entry in
+the direct half only.
+
+The rollup contract is additive across the hierarchy: PRDs may roll up Epics/Stories/leaves, and leaves may roll up evidence or verification artifacts, without double counting shared descendants.
+
+## Idempotent rewrite rules
+
+- There is exactly one managed `## Lisa Usage` section per artifact body/comment.
+- Recompute the entire section on every write; never append ad hoc rows.
+- Sort direct entries deterministically by `(flow, run_id, entry_id)`.
+- Preserve existing entries with unchanged `entry_id` and refreshed field values.
+- Re-running with the same logical entry set must produce byte-identical output. Rewriting a legacy
+  primary-only marker or the 2.222.0 transitional marker migrates once to the canonical
+  primary-plus-extension layout; subsequent rewrites are byte-identical.
+- Do not add timestamps to the section preamble or primary usage token. Sourced
+  lifecycle timestamps belong only in the optional effectiveness extension.
+
+Idempotency is enforced by `entry_id` for direct entries and by the fixed rollup token field order for totals.
+## Delivery observations
+
+Read `references/effectiveness.md` in the `lisa-usage-accounting` skill for the optional effectiveness extension, clock definitions, and recurrence storage contract shared by every supported agent. The primary 17-field usage token remains unchanged.