@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/skills/lisa-usage-accounting/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: lisa-usage-accounting
+description: "Shared usage-ledger utility for Lisa lifecycle flows and artifact writers. Delegates all direct-entry recording and rollup refreshes through one vendor-neutral contract so PRDs, tickets, evidence comments, PRs, and markdown artifacts preserve the canonical `## Lisa Usage` section instead of inventing per-flow formats."
+allowed-tools: ["Skill", "Read", "Bash"]
+---
+
+# Usage Accounting: $ARGUMENTS
+
+Single chokepoint for Lisa usage-ledger writes. Caller skills (`research`, `plan`,
+`implement`, `verify`, `debrief`, `intake`, `prd-source-write`, `tracker-write`,
+`tracker-evidence`, later rollup/monitor flows) MUST delegate usage-entry writes and
+rollup refreshes through this skill rather than hand-editing artifact bodies or comments.
+
+This skill does not define the ledger format itself. The durable schema, token order,
+rewrite invariants, and rollup semantics live in the `usage-accounting` rule. This skill
+applies that contract to real artifacts and chooses the safest writable surface.
+
+## Invocation contract
+
+The caller passes exactly one operation plus its arguments:
+
+```text
+operation: record
+artifact_ref: github:CodySwannGT/lisa#729
+artifact_kind: github-issue
+entry: { ...LisaUsageEntry fields... }
+
+operation: rollup
+artifact_ref: github:CodySwannGT/lisa#724
+artifact_kind: github-issue
+child_refs:
+  - github:CodySwannGT/lisa#729
+  - github:CodySwannGT/lisa#730
+
+operation: record_and_rollup
+artifact_ref: github:CodySwannGT/lisa#724
+artifact_kind: github-issue
+entry: { ...LisaUsageEntry fields... }
+child_refs:
+  - github:CodySwannGT/lisa#729
+```
+
+Required arguments:
+
+- `operation`: one of `record`, `rollup`, or `record_and_rollup`.
+- `artifact_ref`: canonical artifact identifier for the target being updated.
+- `artifact_kind`: the writable host surface (`github-issue`, `github-pr-comment`, `jira-ticket`,
+  `linear-issue`, `notion-page`, `confluence-page`, `markdown-file`, or another caller-defined
+  host string with a matching read/write adapter).
+
+Operation-specific arguments:
+
+- `record` requires `entry`.
+- `rollup` requires `child_refs` (empty is allowed when the caller wants a direct-only refresh).
+- `record_and_rollup` requires `entry` and may also pass `child_refs`.
+
+Optional arguments:
+
+- `attachment_preference`: `body-first` (default) or `comment-only`.
+- `comment_ref`: existing managed comment identifier when the ledger already lives in a comment.
+- `parent_artifact_ref`: explicit parent for callers that need to anchor descendant rollups.
+- `existing_body`: caller-supplied body snapshot when it already owns a fresh read.
+
+The `entry` payload MUST satisfy the canonical usage-entry contract from the rule: stable
+`entry_id`, `flow`, `run_id`, provider/model, source semantics, token fields, pricing fields,
+and artifact refs. Callers do not get to omit the "unavailable" case; when trustworthy usage is
+missing they still pass an explicit entry with `source: unavailable` and nullable token/cost
+fields.
+
+When the runtime exposes only a trustworthy subtotal, callers MUST use `source: measured-subset`,
+write the subtotal to `measured_subset_tokens`, and leave `total_tokens: null`. Do not coerce a
+known subset into `total_tokens`; rollups use `total_tokens` only for complete totals. The
+`measured_subset_tokens` field is optional for backward compatibility with callers that construct
+ordinary observed, estimated, or unavailable entries; the shared serializer normalizes omission
+to `null`. A trustworthy whole-run cost remains valid independently of incomplete token telemetry.
+
+## Return shape
+
+Return structured output so callers can persist or log what happened without reparsing prose:
+
+```yaml
+outcome: updated | comment-fallback | no-op | blocked
+artifact_ref: "github:CodySwannGT/lisa#729"
+surface:
+  kind: body | comment
+  ref: "<artifact or comment identifier>"
+entry_ids:
+  direct:
+    - "<entry-id>"
+  child:
+    - "<rolled-up-child-entry-id>"
+rollup:
+  direct_tokens: 1200
+  child_tokens: 450
+  total_tokens: 1650
+  direct_cost: 0.42
+  child_cost: 0.17
+  total_cost: 0.59
+warnings:
+  - "<warning text>"
+error:
+  code: "<stable-code>"
+  message: "<exact failure text>"
+  remediation: "<next step>"
+```
+
+- `updated` means the preferred writable surface was updated successfully.
+- `comment-fallback` means body/description edits were unsafe, so the canonical ledger landed in a
+  managed comment instead.
+- `no-op` means the requested operation produced byte-identical ledger output.
+- `blocked` means the caller asked for a write that could not be completed; preserve the exact host
+  failure text.
+
+## Workflow
+
+### Step 1 — Read the current managed surface
+
+1. Resolve the target artifact from `artifact_ref` / `artifact_kind`.
+2. Prefer a caller-supplied `existing_body` when present and trustworthy for this write.
+3. Otherwise read the current body/description from the host's native adapter.
+4. If the caller passed `comment_ref`, read that managed comment body too.
+
+Never guess the prior ledger state. Always start from the current managed body/comment so rewrite
+idempotency is preserved.
+
+### Step 2 — Choose the writable surface
+
+Default policy is **body first**:
+
+- If the host body/description is writable by the caller's normal writer path, update the body in
+  place and keep the canonical `## Lisa Usage` section there.
+- If direct body edits are unsafe, unavailable, or likely to clobber other writer-owned content,
+  fall back to a **single managed comment** containing the same canonical section.
+- If the caller explicitly passes `attachment_preference: comment-only`, skip the body attempt and
+  write the managed comment directly.
+
+The fallback is part of the contract, not an error. Writers should prefer the artifact body they
+already own, but evidence comments, immutable PR descriptions, or size-limited hosts may require
+the managed comment path.
+
+### Step 3 — Apply the requested operation
+
+For lifecycle rows, include the optional `effectiveness` observations defined in
+[portable effectiveness reference](references/effectiveness.md): four separate clocks, explicit unknowns, sourced human
+events, Lisa version, and worker configuration revision. Preserve extensions on old
+rows. After the canonical host write passes readback, mirror the row through
+`lisa effectiveness record --input <json-file>` for local status reports. On a
+confirmed recurrence after its control shipped, use `lisa effectiveness recurrence
+--input <json-file>` with the stable source event identity; commit that history
+through normal checks. Do not infer human minutes or invent missing runtime telemetry.
+
+All three operations use the shared utilities and rule contract; they differ only in which inputs
+they require and whether they recompute child totals:
+
+- `record`: upsert exactly one direct usage entry on the target artifact. Rewrite the entire
+  `## Lisa Usage` section in place using the canonical serializer; never append ad hoc rows.
+- `rollup`: recompute the rollup token and visible totals from the target's current direct entries
+  plus usage discovered from `child_refs`. Dedupe strictly by stable `entry_id`.
+- `record_and_rollup`: first upsert the direct entry, then refresh totals against `child_refs` in
+  the same managed write so callers do not produce split-brain ledger states.
+
+The implementation path should use the shared utility layer (`parseLisaUsageSection`,
+`mergeLisaUsageEntries`, `createLisaUsageRollup`, `upsertLisaUsageSection`) rather than duplicating
+token parsing or markdown rendering in each caller.
+
+### Step 4 — Persist, verify by read-back, and report
+
+1. If the rendered ledger body is byte-identical to the current managed surface, return `outcome:
+   no-op`.
+2. Otherwise write the body or managed comment through the host adapter.
+3. **Read the written surface back from the host and parse it.** Run
+   `verifyLisaUsageSectionIntegrity(<stored body>, { entryIds: <ids just written> })`. A write is
+   successful only when that returns `ok: true`. The host's mutation result is not evidence — a
+   Linear `issueUpdate` returned `success: true` while silently discarding every entry token
+   (2026-08-04), which is the defect this step exists to catch.
+4. If verification fails on the body, retry the identical payload as a managed comment and verify
+   that surface the same way. Return `outcome: comment-fallback` with a warning naming the failed
+   surface and the issue codes.
+5. If verification fails on every surface, return `outcome: blocked` with the issue codes in
+   `error.message`. **Never leave a rollup token behind whose `direct_entry_ids` names entries that
+   cannot be parsed from the same surface** — restore the prior managed content rather than
+   reporting success over an unreadable ledger.
+6. Return the exact writable surface used, direct entry ids, rolled-up child entry ids, totals, and
+   any fallback warning.
+
+If the host write fails, preserve the exact error text in `error.message`. Do not collapse write
+failures into a generic "usage update failed."
+
+## Rules
+
+- Never invent a per-flow usage format. All usage-ledger writes go through this skill and the
+  canonical `usage-accounting` rule.
+- Never append a second `## Lisa Usage` section or a second managed usage comment.
+- Never treat missing usage as zero. Callers must record explicit `source: unavailable` entries.
+- Never add a measured subset to complete token totals. A mixed complete-plus-measured-subset
+  direct or child scope has `null` token rollups, while trustworthy whole-run cost rolls up
+  independently.
+- Never discard the optional child-token incompleteness state parsed from an existing rollup when
+  `child_refs` were not refreshed. Preserve it through ordinary direct-entry rewrites.
+- Never skip rollup dedupe. Child totals are keyed by stable `entry_id`, not by child ref count.
+- Never silently drop to comments. Return `outcome: comment-fallback` so the caller can surface the
+  writable surface that actually holds the ledger.
+- Never report `updated` on the strength of a mutation's return value. Verification is read-back
+  and parse, on every surface, every write.
+- Never overwrite unrelated artifact body content. Rewrite only the managed usage section/comment.

package/plugins/lisa-devin/skills/lisa-usage-accounting/references/effectiveness.md

@@ -0,0 +1,63 @@
+# Delivery observations (optional extension)
+
+Keep the primary 17-field usage token unchanged. New writers attach
+`LisaUsageEntry.effectiveness`; the shared serializer emits the adjacent
+`lisa:usage-effectiveness` token correlated by `entry_id`. Older readers may ignore
+the extension. New writers preserve it when rewriting historical rows.
+
+Each observation has `schema: 1` and all these fields, using `null` for unknown:
+
+- `lisaVersion`, `workerConfigRevision`: observed version/revision tags.
+- `workerWallMs`: actual execution duration for this run.
+- `feedbackMs`: measured blocking request-to-response samples in milliseconds.
+  Start when this worker issues the request; stop when its response is available.
+  Waiting on another agent is queue latency and is excluded. `[]` means a measured
+  run with no such requests; `null` means unavailable telemetry.
+- `workerSource`: runtime evidence identifier for wall time and feedback samples.
+- `attention`: observed `{id, source}` human interventions. Derive these from
+  non-bot ready-role flips, blocked-item answers, and review interventions. Dedupe
+  by stable tracker event identity. `[]` means the relevant history was inspected
+  and contained no interventions; `null` means it was not measured. Never infer
+  human minutes from gaps between comments.
+- `readyAt`, `acceptedAt`: canonical UTC timestamps from the configured ready-role
+  flip and terminal accepted outcome. The elapsed clock excludes pre-ready intake.
+  A merge or queued deployment alone is not acceptance. `lifecycleSources` holds
+  the tracker/release evidence for these timestamps.
+- `reworkSources`: observed reclaims, QA bounces, or reverts. The existing
+  `lisa-delivery-effectiveness` skill owns rework rates and other outcome measures;
+  these are observations, not a competing score.
+
+At the existing implement, verify, and intake accounting milestones, supply these
+observations even if every measurement is unknown. Collect runtime observations
+as work proceeds; do not reconstruct feedback samples from memory at the end.
+Runtime APIs differ across agents: unavailable measurements remain null on any
+agent rather than being estimated from tool/PR/token counts.
+
+After the canonical usage row is read back, mirror `{entryId, artifactRef,
+effectiveness}` with `lisa effectiveness record --input <json-file>`. Mirrors under
+`.lisa/effectiveness/` are ignored and disposable; reconstruct them from usage
+extensions when needed. Do not commit timing reports or store secrets in sources.
+The command refuses a non-ignored destination. Report write failures explicitly;
+they must not erase the canonical accounting row or claim measurement succeeded.
+
+Record an actual post-control failure using `lisa effectiveness recurrence --input
+<json-file>`. The object contains `invariant`, `surface`, `controlRef`,
+`controlShippedAt`, `occurrenceRef`, and `occurredAt`. Both timestamps use canonical
+UTC ISO strings with milliseconds. Verify that the control/learning really shipped
+before this occurrence; initial failures and unshipped proposals are not recurrences.
+Use a stable occurrence source, such as a test-run failure or tracker event, so
+replays and reports from different agents identify the same event.
+
+`.lisa/RECURRENCES.jsonl` is committed history: distinct occurrence identities are
+the durable count. Its existing built-in `merge=union` attribute retains concurrent
+branch appends, and the reader deduplicates replayed events. Never hand-increment
+a counter, compact away occurrences, or add counts to the bounded learnings ledger.
+Normal review, secret checks, and push requirements still apply to this file.
+The writer refuses missing merge setup and conflicting evidence for one identity.
+
+`lisa effectiveness report` is read-only. Its per-run feedback distribution, wall
+time, attention count, and ready-to-accepted duration remain separate. Attention
+ratios cover only the locally observed accepted outcomes, with the reported sources
+and denominator. Missing local records are unknown coverage, not zero factory effort.
+Rebuild local records for the requested reporting scope before making a scope-wide
+claim; never extrapolate a local subset to the whole queue.

package/plugins/lisa-devin/skills/lisa-use-the-product/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: lisa-use-the-product
+description: Shared methodology for actually USING a project's product the way its real end user would — across product types (DOM web app, HTTP/API backend, canvas game, CLI/library, IaC/CDK). Detects the product's consumer-facing interface, drives it as that consumer, gated by a per-environment mutation policy read from .lisa.config.json (so the agent never mutates production data by accident), and lensed through the project's personas/subagents when it defines them. Invoked by exploratory-qa (files defect/UX tickets) and product-walkthrough (grounds planning in the live product); rarely run standalone.
+---
+
+# Use the Product
+
+## The one idea
+
+Every product has a **consumer-facing interface**. To evaluate a product you (1) **detect** that interface, (2) **resolve where you're allowed to drive it and how much you may change**, and (3) **drive it as the real consumer would** — through the project's personas when it has them. This skill owns steps 1–4 below; the **caller** decides what to *do* with what you find (`exploratory-qa` files tickets, `product-walkthrough` grounds planning).
+
+Driving the product means **interacting** with it. Static route scans, HTTP fetches, screenshots-alone, and reading the code are *supporting evidence only* — never a substitute for actually using it.
+
+## 1. Detect the product type & interface
+
+Infer from the repo; if genuinely ambiguous, ask one concise question.
+
+| Signals | Type | Consumer-facing interface |
+|---|---|---|
+| `vite`/`next`/`angular`/`svelte` + `index.html`, DOM UI | **DOM web app** | the rendered UI in a real browser |
+| API server (`nest`/`express`/`fastify`/serverless handlers), OpenAPI, no frontend | **HTTP / API backend** | the API endpoints |
+| `phaser`/`pixi`/canvas game | **Canvas game** | the canvas + input (keyboard/pointer), read visually |
+| `cdk.json` / Terraform / IaC | **IaC / CDK** | the resources it provisions (+ synth output) |
+| `bin/` CLI or published library, no server | **CLI / library** | the commands / public API |
+
+## 2. Resolve the environment & mutation policy — the gate
+
+Read the `exploration` block from `.lisa.config.json` (a repo-local config overrides a global one):
+
+```jsonc
+"exploration": {
+  "default": "<env-name>",              // which env to use when none is passed
+  "environments": {
+    "<name>": {
+      "url": "https://dev.example.io",  // web/API target (omit for local CLI/game)
+      "provision": true,                // IaC/ephemeral: stand up, then tear down
+      "mutation": "forbidden | read-only | full",
+      "identity": "<test-account ref>", // which login to use (env var / 1Password ref)
+      "prodMutationAck": "<one sentence>" // REQUIRED to allow `full` on a production-named env
+    }
+  }
+}
+```
+
+Resolve the target env: explicit argument → `default` → infer. Then the **mutation level governs everything**:
+
+- **`read-only`** — only non-mutating interactions: read endpoints (`GET`), view UI without submitting, `cdk synth`/`diff`, `--help`/dry-run. Never create / edit / delete.
+- **`full`** — create / edit / delete allowed, but **only as the `identity` test account** and under Mutation Discipline (§5).
+- **`forbidden`** — do not exercise this environment at all.
+
+**Safety rules — enforced regardless of config:**
+
+- **No `exploration` block, or an unconfigured env → treat as `read-only`.** Never mutate without an explicit policy.
+- **A production-named env (`prod` / `production`) defaults to `forbidden`.** It may be raised to `full` **only** when a written `prodMutationAck` justification is present (this is how a single-environment app — e.g. a local-only game whose only "env" is production and whose mutations are the user's own local save — deliberately opts in). A bare `production: { "mutation": "full" }` with **no** `prodMutationAck` is downgraded to `forbidden`, and you warn.
+- **Never sign in as a real user or an admin** — only the `identity` test account.
+- If evaluating something *requires* a mutation the policy forbids, stop at that boundary and report it — never escalate your own permissions.
+
+## 3. Discover personas & subagents — soft-detect
+
+Look for the project's personas: `wiki/personas/**` (target-player archetypes, stakeholders) and persona subagents (e.g. the `lisa-phaser` `target-player` / `player-advocate` agents).
+
+- **Present** → drive the product **through each relevant persona**: adopt the archetype's constraints (device, session length, goals, patience, genre-literacy) and evaluate as them; run each archetype for breadth.
+- **Absent** → drive as a single **generic representative end user** of the app's stated audience, and say so.
+
+## 4. Drive the product — per type
+
+Apply the interface's *read-only* actions always; the *mutate* actions only when the policy is `full`.
+
+- **DOM web app** — a real browser controlled interactively through any capable backend (in-app Browser/Chrome, Playwright MCP/API/ad hoc script, CDP, computer use, the opt-in Lisa-owned Kane adapter, or equivalent). Land cold on the entry page, then click / type / select / submit visible controls and attempt real tasks; sweep viewport widths. The controller is an implementation detail; a missing preferred backend is not a blocker when another can drive the same live journey. A Playwright test run alone is not this evidence. Kane is selected only via `lisa-kane-browser`, only after `lisa kane probe` succeeds, and only for an allowed non-production env whose mutation policy is `full`; use a more directly controlled backend for `read-only` journeys. *(The caller's lens supplies the specific things to look for.)*
+- **HTTP / API backend** — the consumer is a client, not a browser. Read-only: read the OpenAPI/routes and call safe `GET`s (`curl`/`httpie`). Mutate: exercise representative `POST`/`PUT`/`DELETE` flows with test data as the `identity`; check status codes, payload shapes, and error responses.
+- **Canvas game** — a real browser, but the UI is **drawn to a canvas, not the DOM**. Boot it (e.g. `bun run dev` + Playwright), drive via **keyboard/pointer into the canvas**, and read state **visually via screenshots** (not the accessibility tree). Mutation is usually local save state. Judge readability, game-feel, and input responsiveness — not DOM breakpoints.
+- **CLI / library** — the interface is the command / public API. Read-only: `--help`, read-only commands, dry-runs. Mutate: run state-changing commands with disposable inputs.
+- **IaC / CDK** — the "user" is whoever **consumes the resources the stack provisions** (plus the operator). **Read-only (default):** `cdk synth` → read the generated template; `cdk diff` vs. the deployed env; verify the resources, IAM, and outputs express what a consumer would expect. Flag over-broad IAM, missing/opaque outputs, resources that don't serve their stated purpose, and drift. **Mutate (only when `mutation: "full"` *and* `provision: true` on an ephemeral/sandbox env):** `cdk deploy` to the sandbox → recurse into the API/web playbook against the provisioned resources → `cdk destroy`. Never deploy to a real account without explicit sandbox-provisioning config.
+
+## 5. Mutation Discipline — only when the policy is `full`
+
+A real user creates, edits, and deletes things — exercise those flows when, and only when, the policy allows and always as the `identity` account.
+
+- Use unique names with a clear prefix such as `qa-` or `codex-`.
+- Before mutating, identify the cleanup path. After mutating, make a best effort to clean up, then verify it. If cleanup is unavailable, that itself is a finding.
+- Avoid destructive bulk actions unless the account/data is clearly disposable.
+- Record every mutation performed, cleanup attempts, and any residue left behind.
+
+## What you return
+
+Structured, raw observations for the caller — **what** you did, **as whom** (which persona / generic user), **where** (env + mutation level), **what you saw**, and **what you could not reach and why** (especially policy boundaries you stopped at). You do **not** file tickets or write plans; the caller does.