@codyswann/lisa 2.119.0 → 2.121.0

package/plugins/lisa-cursor/skills/tracker-source-artifacts/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: tracker-source-artifacts
+description: "Canonical, vendor-neutral taxonomy and rules for handling source artifacts (Figma, Lovable, Loom, screenshots, design docs, data samples) when generating or evaluating tracker tickets (JIRA, GitHub Issues, Linear). Defines: (1) artifact domains, (2) classification rules per tool, (3) source precedence (which artifact is authoritative for which question), (4) inheritance from epic to story to sub-task, (5) cross-axis conflict handling. Invoke this skill from any flow that extracts, attaches, or reasons about external design/UX/data artifacts so the rules don't drift across skills."
+allowed-tools: []
+---
+
+# Tracker Source Artifact Taxonomy and Rules
+
+This skill is doctrine, not action — it defines the rules. Skills that need to extract, classify, attach, or reason about external artifacts (design files, prototypes, recordings, data samples) invoke this skill to load the taxonomy and apply it. The taxonomy is vendor-neutral: it applies equally to JIRA tickets, GitHub Issues, and Linear Issues.
+
+The reason this lives in one place: silent drift across skills is the failure mode this body of rules exists to prevent. If the rules differ between `lisa:notion-to-tracker`, `lisa:tracker-create`, and `lisa:tracker-write`, agents will silently route artifacts wrong and developers will lose source of truth. Edit here, propagate everywhere.
+
+## 1. Domains
+
+Every artifact is classified into exactly one domain. The domain determines what the artifact is the source of truth for, and which tickets inherit it.
+
+| Domain | What it defines | Examples |
+|--------|-----------------|----------|
+| `ui-design` (mocks) | **Visual treatment only** — layout, spacing, typography, color, iconography | Figma design frames, Framer static frames, bare screenshots, mockup PNGs |
+| `ux-flow` (prototypes) | **Interaction and flow only** — navigation, transitions, state changes, timing, empty/error/loading states | Lovable output, Loom walkthroughs, Figma prototype links, annotated screenshots, Miro/Mural flow diagrams, user journey maps |
+| `data` | Request/response shape, schema constraints, contracts | Example JSON, SQL schemas, GraphQL snippets, API contracts, sample payloads |
+| `ops` | Deployment / runtime context | Runbooks, dashboards, Terraform refs, deployment diagrams |
+| `reference` | Cross-cutting context | Confluence, Notion peer pages, Google Docs, related PRDs, RFCs |
+
+## 2. Classification rules per tool
+
+These rules exist because agents consistently misclassify Figma and Lovable artifacts, which are the two most common sources of dropped or misrouted context.
+
+- **Figma**: classify as `ux-flow` if the URL is a prototype share link — it contains `/proto/`, has `starting-point-node-id=` in the query, or the sharing context labels it "prototype" / "play mode". Otherwise classify as `ui-design`. Never assume; inspect the URL.
+- **Figma file with both design frames and a prototype**: emit two entries — one `ui-design` for the file, one `ux-flow` for the prototype URL — so both propagate correctly.
+- **Lovable output**: always `ux-flow`. Lovable ships working code, but its code, styling, and any embedded business rules are NOT authoritative. Treat strictly as a UX/flow reference. Implementation uses existing project components; business rules come from the PRD body, not from Lovable.
+- **Loom / video walkthrough**: `ux-flow` in the vast majority of cases. The rare exception — a video that's purely a static-frame design review with no interaction — is still `ux-flow` for routing purposes (both UX and UI stories benefit).
+- **Screenshot**: bare unannotated screenshot → `ui-design`. Screenshot with arrows between frames, flow labels, or numbered steps → `ux-flow`. Side-by-side gallery of state variants (empty/error/loading) → `ui-design` with the state variants noted.
+- **Confluence / Notion peer / Google Doc**: `reference` unless it is specifically a runbook (`ops`) or contains canonical API contracts (`data`).
+- **Grafana / Datadog / Sentry**: `ops`.
+- **Code blocks with example payloads** (JSON, SQL, GraphQL, cURL): `data`.
+
+When an artifact could plausibly fit multiple domains and the rules above don't disambiguate, err on the side of inclusion — emit it under both, or use the broader domain. Misclassification is caught downstream by the preservation gate; underclassification is silent drop.
+
+## 3. Source precedence
+
+When artifacts disagree, silent reconciliation is a known failure mode. The rules below define which source wins which question. **Record this precedence on every ticket that carries design artifacts** (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't reconcile silently.
+
+| Question | Authoritative source |
+|----------|---------------------|
+| Does this field exist? Is it required? Who can see/edit it? What validation applies? Permission rules, edge cases, data constraints? | **Description / PRD body** (business rules) |
+| What does it look like — layout, spacing, typography, color, iconography? | **Mocks (`ui-design`)** |
+| How does it flow — navigation, transitions, state changes, timing, empty/error/loading states? | **Prototypes (`ux-flow`)** |
+| Where does the data come from, what shape is it, what are the API contracts? | **`data` artifacts** |
+| Where does it run, who's on call, what's the dashboard? | **`ops` artifacts** |
+
+## 4. Cross-axis conflict handling
+
+Conflicts MUST be surfaced under `## Open Questions` on the affected ticket — never silently reconciled.
+
+- Mock shows a field the description doesn't mention → BLOCKER: "Figma shows field `X` not in PRD; confirm it exists, and if so add business rules (required/optional, validation, permissions)."
+- Description mandates behavior the prototype contradicts → BLOCKER: "PRD says Y, prototype shows Z; which is correct?"
+- Prototype shows a flow the mocks don't cover (e.g., an error state) → Note: "Error state flow from prototype; no mock exists. Use existing error component or request mock."
+- Multiple artifacts of the same domain disagree (two Figma links showing different layouts) → BLOCKER: list both, ask which is current.
+- Lovable output without a description covering business rules → BLOCKER: "Business rules missing. Lovable's embedded logic is not authoritative; PRD must explicitly state required fields, validation, permissions, and edge cases."
+
+## 5. Coverage smells
+
+Incomplete artifact sets are a common root cause of implementation drift. Surface these on the epic when extracting:
+
+- **Zero artifacts on a non-trivial PRD**: almost always an extraction bug, not a design decision. Say so explicitly.
+- **`ux-flow` present, `ui-design` absent**: flag "missing UI mocks". UI will be inferred from prototype frames — note that prototype styling is typically placeholder and must NOT be treated as visual source of truth.
+- **`ui-design` present, `ux-flow` absent**: flag "missing UX prototype". UX will be inferred from static mock states (empty/error/loading/hover) — any flow not explicitly depicted must be raised as a BLOCKER with recommendation + alternatives, not silently invented.
+
+## 6. Inheritance: epic → story → sub-task
+
+Artifacts attach as Jira remote links and propagate down the hierarchy.
+
+- **Epic**: gets EVERY artifact, regardless of domain. The epic is the canonical hub — anyone working on the epic or its descendants must reach the full set from one place. No filtering.
+- **Story**: inherits the artifacts whose domain matches its scope:
+
+  | Story type | Inherits domains |
+  |------------|------------------|
+  | Frontend / UI | `ui-design`, `ux-flow`, `reference` |
+  | Backend / API / data model | `data`, `reference` |
+  | Infrastructure | `ops`, `reference` |
+  | Mixed / setup ("X.0") | All domains |
+
+  When classification is ambiguous, err on the side of inclusion — a developer can ignore an extra link, but they can't follow one that wasn't attached.
+
+- **Sub-task**: inherits via the parent story link. Do NOT re-attach the same artifacts on every sub-task — that creates noise. Only attach an artifact directly on a sub-task when the sub-task depends on something the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame the broader story doesn't cite).
+
+## 7. Existing-component reuse (UI-touching tickets)
+
+Mocks define visual *intent*, not implementation shortcut. Every UI-touching ticket description must include:
+
+> Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the mock specifies different styling — flag the design-vs-code divergence as a discussion item on this ticket rather than pixel-matching from scratch.
+
+If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation. Lovable-generated components are never the reuse target — always use the project's own components.
+
+## 8. Preservation gate (run after creating tickets)
+
+Before declaring done, verify every extracted artifact is reachable from the created tickets.
+
+1. Build a preservation matrix: `artifact URL → [ticket keys that reference it]`.
+2. For every artifact:
+   - It MUST appear on the epic it belongs to (no exceptions).
+   - It SHOULD appear on at least one story whose scope matches its domain (except `reference`-domain artifacts, which may be epic-only if no story is domain-matched).
+3. Any artifact with zero references anywhere, or missing from its epic: FAIL LOUDLY — list the dropped artifacts with domain, title, and source page; surface to the human; re-attach before continuing.
+4. If classification looks misrouted (e.g., a Figma link landed on a backend story and nowhere else), surface the misroute and offer to re-propagate.
+
+Skipping this gate is the most common cause of silent artifact loss. Do not skip it.

package/plugins/lisa-cursor/skills/tracker-sync/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: tracker-sync
+description: "Vendor-neutral wrapper for posting milestone updates to the linked ticket/issue. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-sync, lisa:github-sync, or lisa:linear-sync. Posts at: plan created, implementation in progress, PR ready, PR merged. Suggests (never auto-transitions) the next status."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Sync: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor sync skill.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa:tracker-write`).
+2. Dispatch:
+   - `jira` → invoke `lisa:jira-sync` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa:github-sync` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa:linear-sync` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Pass through the output.
+
+`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below) and `--update-label`. The shim never interprets these — the vendor skill does.
+
+If `$ARGUMENTS` is empty, all vendor skills auto-detect a ticket reference from the active plan file (most recently modified `.md` in `plans/`).
+
+## Parent status rollup (`--rollup`)
+
+When the caller passes `--rollup` after the milestone, the dispatch target additionally **derives the parent/container's lifecycle state from its children** instead of acting on the work item directly. This is the vendor-neutral implementation of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy here. The shim is dispatch only; the rollup mechanics live in the vendor sync skill (`lisa:github-sync`, `lisa:jira-sync`, `lisa:linear-sync`), which resolves child membership via its `*-read-*` skill and evaluates the state machine below.
+
+The state machine (first match wins, evaluated over the **required** leaves only):
+
+| If among the required leaves… | …the parent rolls up to | Role |
+|---|---|---|
+| any leaf is **blocked** | blocked / attention-needed | `blocked` |
+| else any leaf is **in progress** (claimed or in review) | active / in-progress | `claimed` |
+| else **all** required leaves are **terminal** | the configured rollup terminal | `done` (or `review` where supported) |
+| else (leaves exist, none started) | unchanged | — |
+
+- **Blocked dominates** — one blocked leaf surfaces blocked on the parent even while others progress.
+- **The parent never carries `ready`** — `ready` is a human "claim this leaf" signal; rollup only moves a parent between non-ready container states.
+- **Rollup is recursive** — an Epic rolls up from its Stories, each of which rolls up from its own leaves. Evaluate bottom-up.
+- **The terminal is the configured env-keyed `done`** — multi-env projects roll up to whichever `done` value matches the env their leaves shipped to (see `config-resolution` "Env-keyed `done`"). **Single-environment collapse (this repo):** `deploy.branches` declares only `production: main`, so `done` is a single value and the GitHub build lifecycle collapses to `ready → claimed (in-progress) → done`; the rollup terminal is simply `done` (or the PRD-side `ticketed` for PRD containers), with **no** dev/staging promotion hops and **no** env-keyed multi-entry chain to resolve.
+
+**Safe-by-default when not yet supported.** A vendor sync path that has not implemented native rollup MUST be a documented no-op that surfaces the derived state as a suggestion/comment rather than guessing a transition — never an unsafe default. Without `--rollup`, the sync skills behave exactly as before (milestone comment on the work item; no parent derivation).
+
+## Rules
+
+- Idempotent updates — running sync at the same milestone twice should not produce duplicate comments. Vendor skills enforce this.
+- Never auto-transition the underlying state. Linear's label-based transition (`status:*`) is the canonical signal and is updated only when the caller passes `--update-label`. Native states stay as suggestions.
+- Parent rollup derives state from children per the `leaf-only-lifecycle` rule; it never sets a parent to `ready` and never resolves a dev/staging `done` in this single-environment repo.

package/plugins/lisa-cursor/skills/tracker-validate/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tracker-validate
+description: "Vendor-neutral wrapper for the pre-write quality gate. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-validate-ticket, lisa:github-validate-issue, or lisa:linear-validate-issue. Read-only — never writes to any tracker. Used by tracker-write Phase 5.5 (pre-write gate), tracker-verify (post-write checks), and the *-to-tracker dry-run paths. Output is structured PASS/FAIL per gate so callers can parse it."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Validate: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor validator.
+
+See the `config-resolution` rule for the full configuration schema and skill-mapping table.
+
+## Workflow
+
+1. **Resolve tracker config** (same logic as `lisa:tracker-write` Step 1):
+
+   ```bash
+   local_tracker=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+   global_tracker=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+   tracker="${local_tracker:-${global_tracker:-jira}}"
+   ```
+
+2. **Dispatch**
+
+   - `jira` → invoke `lisa:jira-validate-ticket` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa:github-validate-issue` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa:linear-validate-issue` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+3. **Pass through the validator's structured report unchanged.** Callers (e.g. `lisa:jira-write-ticket` Phase 5.5) parse the gate lines; do not paraphrase.
+
+## Rules
+
+- Read-only — never write to any tracker.
+- Never re-implement gate logic here. The gate definitions are the vendor validator's responsibility.
+- Never silently transform the input — pass `$ARGUMENTS` through verbatim.

package/plugins/lisa-cursor/skills/tracker-verify/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: tracker-verify
+description: "Vendor-neutral wrapper for the post-write verification gate. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-verify, lisa:github-verify, or lisa:linear-verify. Fetches the live ticket/issue and runs the validator gates against the stored state — catches anything dropped or reformatted on write. Read-only."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Verify: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor post-write verifier.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa:tracker-write`).
+2. Dispatch:
+   - `jira` → invoke `lisa:jira-verify` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa:github-verify` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa:linear-verify` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Pass through the verifier's structured report unchanged.
+
+## Rules
+
+- Read-only.
+- The same gates run pre-write and post-write — this shim simply chooses the vendor implementation.
+- If the vendor verify reports `FAIL`, callers must NOT auto-fix from this layer. Surface the failures to the caller and let the higher-level skill decide.

package/plugins/lisa-cursor/skills/tracker-write/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: tracker-write
+description: "Vendor-neutral wrapper for ticket creation and updates. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-write-ticket, lisa:github-write-issue, or lisa:linear-write-issue. Callers in vendor-neutral skills (notion-to-tracker, linear-to-tracker, confluence-to-tracker, github-to-tracker, implement, verify) MUST invoke this skill instead of the vendor-specific ones — that is what makes the tracker switchable per project. The Phase-5.5 validate-pre-write gate, post-write verify, and Phase-8 announce-comment behavior live in the vendor skills; this shim is dispatch only."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Write: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor
+write skill.
+
+When the incoming description/body already contains the canonical `## Lisa Usage` ledger, the vendor
+writer must preserve that managed section on update and use the `usage-accounting` contract for any
+body-vs-comment fallback. This shim only routes — it never edits tracker artifacts itself.
+
+See the `config-resolution` rule for the full configuration schema and skill-mapping table.
+
+## Workflow
+
+1. **Resolve tracker config**
+
+   Read `.lisa.config.local.json` first (if present), then `.lisa.config.json`. Local overrides global on a per-key basis. Use `jq` — never hand-parse JSON.
+
+   ```bash
+   local_tracker=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+   global_tracker=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+   tracker="${local_tracker:-${global_tracker:-jira}}"
+   ```
+
+2. **Validate the value**
+
+   - `jira` → confirm `atlassian.cloudId` and `jira.project` are present. If either is missing, stop and report: `"tracker=jira but atlassian.cloudId and jira.project are not set in .lisa.config.json."` Continue to Step 3a.
+   - `github` → confirm `github.org` and `github.repo` are present. If either is missing, stop and report: `"tracker=github but github.org and github.repo are not set in .lisa.config.json."` Continue to Step 3b.
+   - `linear` → confirm `linear.workspace` and `linear.teamKey` are present. If either is missing, stop and report: `"tracker=linear but linear.workspace and linear.teamKey are not set in .lisa.config.json."` Continue to Step 3c.
+   - Any other value → stop and report: `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+3. **Dispatch**
+
+   - **3a (jira):** Invoke `lisa:jira-write-ticket` via the Skill tool, passing `$ARGUMENTS` verbatim.
+   - **3b (github):** Invoke `lisa:github-write-issue` via the Skill tool, passing `$ARGUMENTS` verbatim.
+   - **3c (linear):** Invoke `lisa:linear-write-issue` via the Skill tool, passing `$ARGUMENTS` verbatim.
+
+4. **Surface the vendor skill's output unchanged.** Do not paraphrase; downstream callers parse the structured response.
+
+## Rules
+
+- Never bypass dispatch — calling the vendor skill directly from a vendor-neutral caller defeats the per-project switch.
+- Never drop, duplicate, or hand-rewrite an existing managed `## Lisa Usage` section in this shim.
+  Writer-specific preservation logic belongs in the vendor writers and follows the
+  `usage-accounting` contract.
+- Never accept a tracker value outside `{jira, github, linear}`.
+- Never mutate `$ARGUMENTS` between layers. The vendor skills define their own input contract.
+- Never inline gate logic here. All validation rules live in the vendor skills (`lisa:jira-validate-ticket` / `lisa:github-validate-issue` / `lisa:linear-validate-issue`); this skill only routes.

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

@@ -0,0 +1,170 @@
+---
+name: 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.
+
+## 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
+
+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 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. 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 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 overwrite unrelated artifact body content. Rewrite only the managed usage section/comment.