@codyswann/lisa 2.71.0 → 2.73.0

package/package.json

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/skills/confluence-write-prd/SKILL.md

@@ -65,7 +65,10 @@ else → **create**.
 format** (XHTML): `#`/`##`/`###` → `<h1>/<h2>/<h3>`, paragraphs → `<p>`, lists → `<ul>/<ol><li>`,
 fenced code → `<ac:structured-macro ac:name="code">`. Embed the marker as a storage comment
 (`<!-- $MARKER -->`) or a small `<p>` so future CQL dedupe finds it. The body must always contain
-**exactly one** marker; never write a markerless page (CREATE or UPDATE).
+**exactly one** marker; never write a markerless page (CREATE or UPDATE). If the live page body
+already contains the canonical managed `## Lisa Usage` section, preserve it verbatim unless the
+caller intentionally supplied an updated canonical section; use the shared `usage-accounting`
+serializer/merge path rather than hand-editing ledger rows in storage XHTML.
 
 **CREATE:** `lisa:atlassian-access` `operation: write-page` (create form) with a payload that sets:
 - `title`: `$TITLE`
@@ -77,7 +80,8 @@ fenced code → `<ac:structured-macro ac:name="code">`. Embed the marker as a st
 1. **GET-then-PUT** (load-bearing, as `confluence-prd-intake` documents): first `operation: read-page
    id: <page-id>` to read the current `version.number`, then `operation: write-page` (edit form) with
    the marker-normalized storage body and `version.number` bumped to current+1. A PUT without the
-   current version is rejected; never drop the marker on the edit.
+   current version is rejected; never drop the marker or an existing managed `## Lisa Usage` section
+   on the edit.
 2. Re-parent to the target lifecycle parent if the role changed — **unless** the page's current
    parent is in the resolved `${PROGRESSED_PARENTS[@]}` set (already past `ready`). If so, leave it
    and report `reused (already past ready)`. Reverse-lookup the current parent in
@@ -99,5 +103,7 @@ outcome: created | reused
 - State is the parent page, not a label — never attempt Confluence label writes (they 401 on scoped
   tokens; see `config-resolution`).
 - Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never re-parent a PRD already past `ready` down to draft/ready.
 - Resolve parents from config (`confluence.parents.{draft,ready}`) — never hardcode page ids.

package/plugins/lisa/skills/github-write-issue/SKILL.md

@@ -276,7 +276,7 @@ If the validator reports `FAIL`, do NOT proceed to Phase 6. Fix the spec and re-
 
 ### UPDATE
 
-1. Re-read the current body via `gh issue view <number> --repo <org>/<repo> --json body --jq '.body'`. Edit only the sections being changed; preserve everything else verbatim.
+1. Re-read the current body via `gh issue view <number> --repo <org>/<repo> --json body --jq '.body'`. Edit only the sections being changed; preserve everything else verbatim, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
 2. Apply the edit:
    ```bash
    gh issue edit <number> --repo <org>/<repo> --body-file /tmp/updated-body.md
@@ -331,6 +331,8 @@ The mapping below is the single source of truth for how JIRA concepts translate
 - Never create a Bug, Task, or Sub-task whose AC references work in a different repo. GitHub Issues already live in one repo; reject AC bullets that span others — split into per-repo issues under a shared Epic.
 - Never include a runtime-behavior issue without a target backend environment, and never include an authenticated-surface issue without sign-in credentials.
 - Never overwrite an issue body without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - All writes go through this skill (or the `tracker-write` shim). Other vendor-neutral skills must NEVER call `gh issue create` directly.
 - The gate logic lives in `lisa:github-validate-issue`, NOT here. This skill calls the validator at Phase 5.5 and Phase 7. When a gate needs to change, change it in `lisa:github-validate-issue`.
 - Never bypass the sub-issue mutation by encoding the parent only in the body. The native sub-issue link is what `lisa:github-read-issue` and the GitHub UI use to render the hierarchy.

package/plugins/lisa/skills/github-write-prd/SKILL.md

@@ -55,10 +55,13 @@ EXISTING=$(gh issue list --repo "$ORG/$REPO" --state open --search "\"$MARKER\"
 
 ## Phase 3 — Create or update
 
-**Marker normalization (both paths).** Before writing any body, ensure it contains **exactly one**
-marker line — inject `<!-- $MARKER -->` if the caller's synthesized body doesn't already carry it.
-**Never write a markerless body** (including on UPDATE or when `source_ref` is passed): a body without
-the marker breaks future dedupe. If the body already has the marker, leave the single instance.
+**Marker + usage-ledger preservation (both paths).** Before writing any body, ensure it contains
+**exactly one** marker line — inject `<!-- $MARKER -->` if the caller's synthesized body doesn't
+already carry it. **Never write a markerless body** (including on UPDATE or when `source_ref` is
+passed): a body without the marker breaks future dedupe. If the body already has the marker, leave
+the single instance. If the live issue body already contains the canonical managed `## Lisa Usage`
+section, preserve it verbatim unless the caller intentionally supplied an updated canonical section;
+use the shared `usage-accounting` serializer/merge path rather than hand-editing ledger rows.
 
 **CREATE** (no existing issue):
 
@@ -77,7 +80,7 @@ the marker breaks future dedupe. If the body already has the marker, leave the s
 **UPDATE** (existing issue or `source_ref`):
 
 1. `gh issue edit <n> --repo "$ORG/$REPO" --body-file /tmp/prd-body.md` with the **marker-normalized**
-   body (regenerate in place; never drop the marker).
+   body (regenerate in place; never drop the marker or an existing managed `## Lisa Usage` section).
 2. Reconcile the lifecycle label to **exactly one**: add `$ROLE_LABEL`, remove every other label in
    the resolved `${ALL_PRD_LABELS[@]}` set (the config-resolved names — not a hard-coded list) via
    `gh issue edit <n> --add-label / --remove-label`. Never leave a PRD carrying two lifecycle labels.
@@ -104,6 +107,8 @@ outcome: created | reused
 
 - Exactly one PRD lifecycle label at all times (leaf-only does not apply — PRDs are not build leaves).
 - Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never down-rank a PRD already past `ready`.
 - A *closed* prior PRD does not suppress a new one — a recurrence after closure is a genuine new PRD.
 - This is a source-side writer (`prd-*` labels). It never touches build labels (`status:*`) — that is

package/plugins/lisa/skills/jira-write-ticket/SKILL.md

@@ -235,7 +235,7 @@ If the validator reports `PASS`, continue to Phase 6.
 
 1. Invoke `lisa:atlassian-access` with `operation: write-ticket payload: {key: <K>, ...fields-being-changed}`. Do NOT resend fields that weren't in the change set — it blows away history.
 2. Add new relationships via `lisa:atlassian-access` `operation: link from: <K1> to: <K2> type: "<link-type>"`. Existing links are not touched unless explicitly removed.
-3. If description changes, preserve sections you are not editing. Re-read via `/jira-read-ticket` first.
+3. If description changes, preserve sections you are not editing. Re-read via `/jira-read-ticket` first, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
 
 ## Phase 7 — Verify
 
@@ -259,5 +259,7 @@ Skip this step only on UPDATE when no material change was made.
 - Never include a runtime-behavior ticket without a target backend environment, and never include an authenticated-surface ticket without sign-in credentials in the description.
 - Never invent custom field values. If the project requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:jira-create`) should delegate here rather than invoking `lisa:atlassian-access` write operations directly.
 - The gate logic (what makes a valid ticket) lives in `lisa:jira-validate-ticket`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:jira-verify` post-write). When a gate needs to change, change it in `lisa:jira-validate-ticket` — every caller (write path, dry-run path, post-write verify) picks it up automatically.

package/plugins/lisa/skills/linear-write-issue/SKILL.md

@@ -260,7 +260,7 @@ If the validator reports `PASS`, continue to Phase 6.
 ### UPDATE
 
 1. Call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` with **only the fields being changed**. Do NOT resend fields that weren't in the change set — Linear treats the call as a full overwrite of the listed fields.
-2. Preserve description sections you are not editing — re-read via `/linear-read-issue` first.
+2. Preserve description sections you are not editing — re-read via `/linear-read-issue` first, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
 
 ## Phase 7 — Verify
 
@@ -285,6 +285,8 @@ Skip this step only on UPDATE when no material change was made.
 - Never include a runtime-behavior item without a target backend environment, and never include an authenticated-surface item without sign-in credentials in the description.
 - Never invent custom field values. If the team requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - All Linear writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:linear-create`) should delegate here rather than calling the MCP write tools directly.
 - The gate logic (what makes a valid item) lives in `lisa:linear-validate-issue`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:linear-verify` post-write). When a gate needs to change, change it in `lisa:linear-validate-issue` — every caller picks it up automatically.
 - This skill is the destination of the `lisa:tracker-write` shim when `tracker = "linear"`. Vendor-neutral callers (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST go through `lisa:tracker-write`, not call this skill directly.

package/plugins/lisa/skills/linear-write-prd/SKILL.md

@@ -52,9 +52,12 @@ marker, **never** the project name:
 
 ## Phase 3 — Create or update
 
-**Marker normalization (both paths).** Before writing the `description`, ensure it contains
-**exactly one** marker line — inject the marker if the synthesized description lacks it. **Never write
-a markerless description** (including UPDATE / `source_ref`): that breaks future dedupe.
+**Marker + usage-ledger preservation (both paths).** Before writing the `description`, ensure it
+contains **exactly one** marker line — inject the marker if the synthesized description lacks it.
+**Never write a markerless description** (including UPDATE / `source_ref`): that breaks future
+dedupe. If the live Project description already contains the canonical managed `## Lisa Usage`
+section, preserve it verbatim unless the caller intentionally supplied an updated canonical section;
+use the shared `usage-accounting` serializer/merge path rather than hand-editing ledger rows.
 
 **CREATE:** `mcp__linear-server__save_project` with:
 - `name`: `$TITLE`
@@ -64,8 +67,9 @@ a markerless description** (including UPDATE / `source_ref`): that breaks future
 - `state`: Linear Project default (e.g. `backlog`)
 
 **UPDATE** (existing project or `source_ref`): `save_project` with the project id and **only** the
-changed fields — regenerate the marker-normalized `description`, and reconcile labels to **exactly
-one** PRD lifecycle label: add the role label, remove every other label in the resolved
+changed fields — regenerate the marker-normalized `description` without dropping the managed
+`## Lisa Usage` section, and reconcile labels to **exactly one** PRD lifecycle label: add the role
+label, remove every other label in the resolved
 `${ALL_PRD_LABELS[@]}` set (config-resolved names, not a hard-coded list). Do **not** down-rank a
 Project whose current label is in the resolved `${PROGRESSED[@]}` set (already past `ready`) — leave
 it and report `reused (already past ready)`.
@@ -84,6 +88,8 @@ outcome: created | reused
 
 - Exactly one PRD lifecycle project-label at all times.
 - Match dedupe by marker, never by project name.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never down-rank a Project already past `ready`.
 - Source-side writer (`prd-*` project labels) — never touches issue-level build labels (`status:*`),
   which are `lisa:linear-write-issue`'s lane (see `config-resolution` self-host separation).

package/plugins/lisa/skills/notion-write-prd/SKILL.md

@@ -60,8 +60,8 @@ exceeds 100 blocks, create the page with the first ≤100 blocks then add the re
 accept the markdown content directly (it performs this conversion) — prefer that; the explicit block
 conversion is the curl-substrate path.
 
-**Marker normalization (both paths).** The page must always carry **exactly one** marker. On CREATE
-the marker is the first body block; on UPDATE never remove it. Never write a markerless page.
+**Marker + usage-ledger preservation (both paths).** The page must always carry **exactly one**
+marker. On CREATE the marker is the first body block; on UPDATE never remove it. Never write a markerless body. Never write a markerless page. If the existing page content already contains the canonical managed `## Lisa Usage` section, preserve that section when regenerating the page body unless the caller intentionally supplied an updated canonical section; use the shared `usage-accounting` serializer/merge path rather than freehand block edits to ledger rows.
 
 **CREATE:**
 
@@ -86,7 +86,7 @@ the marker is the first body block; on UPDATE never remove it. Never write a mar
    (`operation: archive-page` is page-level, so for blocks delete via the blocks API through
    `notion-access` or, where block deletion isn't available, replace their text in place) and
    `operation: append-blocks` the regenerated blocks. Do not duplicate the whole spec as a dated
-   note, and never drop the marker.
+   note, and never drop the marker or an existing managed `## Lisa Usage` section.
 
 ## Phase 4 — Return
 
@@ -102,6 +102,8 @@ outcome: created | reused
 
 - All access via `lisa:notion-access`; never touch the Notion API/MCP directly.
 - Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never down-rank a PRD whose Status is already past `ready`.
 - Resolve the Status vocabulary from config (`notion.statusProperty`, `notion.values.*`) — never
   hardcode value names.

package/plugins/lisa/skills/prd-source-write/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: ["Skill", "Bash", "Read"]
 
 Thin dispatcher. Resolves the configured PRD `source` and delegates to the matching vendor PRD
 writer, which owns the concrete create/update, the lifecycle-role application, and the marker-based
-dedupe. This skill only routes — it never talks to a source API itself.
+dedupe. When the supplied PRD body already contains the canonical `## Lisa Usage` ledger, the
+vendor writer must preserve that managed section on update instead of dropping it or reformatting it
+ad hoc. This skill only routes — it never talks to a source API itself.
 
 See the `config-resolution` rule for the full configuration schema and the PRD lifecycle roles.
 
@@ -74,6 +76,8 @@ prior PRD-source-write behavior to preserve, so omitted means `draft`.
 
 - Never bypass dispatch — a vendor-neutral caller calling a `*-write-prd` skill directly defeats the
   per-project source switch (exactly the `tracker-write` discipline, mirrored).
+- Never drop or duplicate an existing managed `## Lisa Usage` section. Writer-specific preservation
+  and fallback behavior belongs in the vendor writers and follows the `usage-accounting` contract.
 - Never accept a source outside `{notion, confluence, github, linear}`. `jira` and `file` fail loudly.
 - Never mutate the spec between layers. The vendor writers define their own create/dedupe contract.
 - Never invent a PRD lifecycle role string — resolve every role from `config-resolution` per vendor.

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

@@ -6,7 +6,12 @@ allowed-tools: ["Skill", "Bash", "Read"]
 
 # Tracker Write: $ARGUMENTS
 
-Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor write skill.
+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.
 
@@ -40,6 +45,9 @@ See the `config-resolution` rule for the full configuration schema and skill-map
 ## 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/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.

package/plugins/lisa/skills/usage-accounting/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Usage Accounting"
+short_description: "Shared usage-ledger utility for Lisa lifecycle flows and artifact writers"
+default_prompt:
+  - "Use $usage-accounting: Shared usage-ledger utility for Lisa lifecycle flows and artifact writers."

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.71.0",
+  "version": "2.73.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/skills/confluence-write-prd/SKILL.md

@@ -65,7 +65,10 @@ else → **create**.
 format** (XHTML): `#`/`##`/`###` → `<h1>/<h2>/<h3>`, paragraphs → `<p>`, lists → `<ul>/<ol><li>`,
 fenced code → `<ac:structured-macro ac:name="code">`. Embed the marker as a storage comment
 (`<!-- $MARKER -->`) or a small `<p>` so future CQL dedupe finds it. The body must always contain
-**exactly one** marker; never write a markerless page (CREATE or UPDATE).
+**exactly one** marker; never write a markerless page (CREATE or UPDATE). If the live page body
+already contains the canonical managed `## Lisa Usage` section, preserve it verbatim unless the
+caller intentionally supplied an updated canonical section; use the shared `usage-accounting`
+serializer/merge path rather than hand-editing ledger rows in storage XHTML.
 
 **CREATE:** `lisa:atlassian-access` `operation: write-page` (create form) with a payload that sets:
 - `title`: `$TITLE`
@@ -77,7 +80,8 @@ fenced code → `<ac:structured-macro ac:name="code">`. Embed the marker as a st
 1. **GET-then-PUT** (load-bearing, as `confluence-prd-intake` documents): first `operation: read-page
    id: <page-id>` to read the current `version.number`, then `operation: write-page` (edit form) with
    the marker-normalized storage body and `version.number` bumped to current+1. A PUT without the
-   current version is rejected; never drop the marker on the edit.
+   current version is rejected; never drop the marker or an existing managed `## Lisa Usage` section
+   on the edit.
 2. Re-parent to the target lifecycle parent if the role changed — **unless** the page's current
    parent is in the resolved `${PROGRESSED_PARENTS[@]}` set (already past `ready`). If so, leave it
    and report `reused (already past ready)`. Reverse-lookup the current parent in
@@ -99,5 +103,7 @@ outcome: created | reused
 - State is the parent page, not a label — never attempt Confluence label writes (they 401 on scoped
   tokens; see `config-resolution`).
 - Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never re-parent a PRD already past `ready` down to draft/ready.
 - Resolve parents from config (`confluence.parents.{draft,ready}`) — never hardcode page ids.

package/plugins/src/base/skills/github-write-issue/SKILL.md

@@ -276,7 +276,7 @@ If the validator reports `FAIL`, do NOT proceed to Phase 6. Fix the spec and re-
 
 ### UPDATE
 
-1. Re-read the current body via `gh issue view <number> --repo <org>/<repo> --json body --jq '.body'`. Edit only the sections being changed; preserve everything else verbatim.
+1. Re-read the current body via `gh issue view <number> --repo <org>/<repo> --json body --jq '.body'`. Edit only the sections being changed; preserve everything else verbatim, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
 2. Apply the edit:
    ```bash
    gh issue edit <number> --repo <org>/<repo> --body-file /tmp/updated-body.md
@@ -331,6 +331,8 @@ The mapping below is the single source of truth for how JIRA concepts translate
 - Never create a Bug, Task, or Sub-task whose AC references work in a different repo. GitHub Issues already live in one repo; reject AC bullets that span others — split into per-repo issues under a shared Epic.
 - Never include a runtime-behavior issue without a target backend environment, and never include an authenticated-surface issue without sign-in credentials.
 - Never overwrite an issue body without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - All writes go through this skill (or the `tracker-write` shim). Other vendor-neutral skills must NEVER call `gh issue create` directly.
 - The gate logic lives in `lisa:github-validate-issue`, NOT here. This skill calls the validator at Phase 5.5 and Phase 7. When a gate needs to change, change it in `lisa:github-validate-issue`.
 - Never bypass the sub-issue mutation by encoding the parent only in the body. The native sub-issue link is what `lisa:github-read-issue` and the GitHub UI use to render the hierarchy.

package/plugins/src/base/skills/github-write-prd/SKILL.md

@@ -55,10 +55,13 @@ EXISTING=$(gh issue list --repo "$ORG/$REPO" --state open --search "\"$MARKER\"
 
 ## Phase 3 — Create or update
 
-**Marker normalization (both paths).** Before writing any body, ensure it contains **exactly one**
-marker line — inject `<!-- $MARKER -->` if the caller's synthesized body doesn't already carry it.
-**Never write a markerless body** (including on UPDATE or when `source_ref` is passed): a body without
-the marker breaks future dedupe. If the body already has the marker, leave the single instance.
+**Marker + usage-ledger preservation (both paths).** Before writing any body, ensure it contains
+**exactly one** marker line — inject `<!-- $MARKER -->` if the caller's synthesized body doesn't
+already carry it. **Never write a markerless body** (including on UPDATE or when `source_ref` is
+passed): a body without the marker breaks future dedupe. If the body already has the marker, leave
+the single instance. If the live issue body already contains the canonical managed `## Lisa Usage`
+section, preserve it verbatim unless the caller intentionally supplied an updated canonical section;
+use the shared `usage-accounting` serializer/merge path rather than hand-editing ledger rows.
 
 **CREATE** (no existing issue):
 
@@ -77,7 +80,7 @@ the marker breaks future dedupe. If the body already has the marker, leave the s
 **UPDATE** (existing issue or `source_ref`):
 
 1. `gh issue edit <n> --repo "$ORG/$REPO" --body-file /tmp/prd-body.md` with the **marker-normalized**
-   body (regenerate in place; never drop the marker).
+   body (regenerate in place; never drop the marker or an existing managed `## Lisa Usage` section).
 2. Reconcile the lifecycle label to **exactly one**: add `$ROLE_LABEL`, remove every other label in
    the resolved `${ALL_PRD_LABELS[@]}` set (the config-resolved names — not a hard-coded list) via
    `gh issue edit <n> --add-label / --remove-label`. Never leave a PRD carrying two lifecycle labels.
@@ -104,6 +107,8 @@ outcome: created | reused
 
 - Exactly one PRD lifecycle label at all times (leaf-only does not apply — PRDs are not build leaves).
 - Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never down-rank a PRD already past `ready`.
 - A *closed* prior PRD does not suppress a new one — a recurrence after closure is a genuine new PRD.
 - This is a source-side writer (`prd-*` labels). It never touches build labels (`status:*`) — that is

package/plugins/src/base/skills/jira-write-ticket/SKILL.md

@@ -235,7 +235,7 @@ If the validator reports `PASS`, continue to Phase 6.
 
 1. Invoke `lisa:atlassian-access` with `operation: write-ticket payload: {key: <K>, ...fields-being-changed}`. Do NOT resend fields that weren't in the change set — it blows away history.
 2. Add new relationships via `lisa:atlassian-access` `operation: link from: <K1> to: <K2> type: "<link-type>"`. Existing links are not touched unless explicitly removed.
-3. If description changes, preserve sections you are not editing. Re-read via `/jira-read-ticket` first.
+3. If description changes, preserve sections you are not editing. Re-read via `/jira-read-ticket` first, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
 
 ## Phase 7 — Verify
 
@@ -259,5 +259,7 @@ Skip this step only on UPDATE when no material change was made.
 - Never include a runtime-behavior ticket without a target backend environment, and never include an authenticated-surface ticket without sign-in credentials in the description.
 - Never invent custom field values. If the project requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - All writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:jira-create`) should delegate here rather than invoking `lisa:atlassian-access` write operations directly.
 - The gate logic (what makes a valid ticket) lives in `lisa:jira-validate-ticket`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:jira-verify` post-write). When a gate needs to change, change it in `lisa:jira-validate-ticket` — every caller (write path, dry-run path, post-write verify) picks it up automatically.

package/plugins/src/base/skills/linear-write-issue/SKILL.md

@@ -260,7 +260,7 @@ If the validator reports `PASS`, continue to Phase 6.
 ### UPDATE
 
 1. Call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` with **only the fields being changed**. Do NOT resend fields that weren't in the change set — Linear treats the call as a full overwrite of the listed fields.
-2. Preserve description sections you are not editing — re-read via `/linear-read-issue` first.
+2. Preserve description sections you are not editing — re-read via `/linear-read-issue` first, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
 
 ## Phase 7 — Verify
 
@@ -285,6 +285,8 @@ Skip this step only on UPDATE when no material change was made.
 - Never include a runtime-behavior item without a target backend environment, and never include an authenticated-surface item without sign-in credentials in the description.
 - Never invent custom field values. If the team requires a field you don't have, stop and ask.
 - Never overwrite a description without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - All Linear writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:linear-create`) should delegate here rather than calling the MCP write tools directly.
 - The gate logic (what makes a valid item) lives in `lisa:linear-validate-issue`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:linear-verify` post-write). When a gate needs to change, change it in `lisa:linear-validate-issue` — every caller picks it up automatically.
 - This skill is the destination of the `lisa:tracker-write` shim when `tracker = "linear"`. Vendor-neutral callers (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST go through `lisa:tracker-write`, not call this skill directly.

package/plugins/src/base/skills/linear-write-prd/SKILL.md

@@ -52,9 +52,12 @@ marker, **never** the project name:
 
 ## Phase 3 — Create or update
 
-**Marker normalization (both paths).** Before writing the `description`, ensure it contains
-**exactly one** marker line — inject the marker if the synthesized description lacks it. **Never write
-a markerless description** (including UPDATE / `source_ref`): that breaks future dedupe.
+**Marker + usage-ledger preservation (both paths).** Before writing the `description`, ensure it
+contains **exactly one** marker line — inject the marker if the synthesized description lacks it.
+**Never write a markerless description** (including UPDATE / `source_ref`): that breaks future
+dedupe. If the live Project description already contains the canonical managed `## Lisa Usage`
+section, preserve it verbatim unless the caller intentionally supplied an updated canonical section;
+use the shared `usage-accounting` serializer/merge path rather than hand-editing ledger rows.
 
 **CREATE:** `mcp__linear-server__save_project` with:
 - `name`: `$TITLE`
@@ -64,8 +67,9 @@ a markerless description** (including UPDATE / `source_ref`): that breaks future
 - `state`: Linear Project default (e.g. `backlog`)
 
 **UPDATE** (existing project or `source_ref`): `save_project` with the project id and **only** the
-changed fields — regenerate the marker-normalized `description`, and reconcile labels to **exactly
-one** PRD lifecycle label: add the role label, remove every other label in the resolved
+changed fields — regenerate the marker-normalized `description` without dropping the managed
+`## Lisa Usage` section, and reconcile labels to **exactly one** PRD lifecycle label: add the role
+label, remove every other label in the resolved
 `${ALL_PRD_LABELS[@]}` set (config-resolved names, not a hard-coded list). Do **not** down-rank a
 Project whose current label is in the resolved `${PROGRESSED[@]}` set (already past `ready`) — leave
 it and report `reused (already past ready)`.
@@ -84,6 +88,8 @@ outcome: created | reused
 
 - Exactly one PRD lifecycle project-label at all times.
 - Match dedupe by marker, never by project name.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never down-rank a Project already past `ready`.
 - Source-side writer (`prd-*` project labels) — never touches issue-level build labels (`status:*`),
   which are `lisa:linear-write-issue`'s lane (see `config-resolution` self-host separation).

package/plugins/src/base/skills/notion-write-prd/SKILL.md

@@ -60,8 +60,8 @@ exceeds 100 blocks, create the page with the first ≤100 blocks then add the re
 accept the markdown content directly (it performs this conversion) — prefer that; the explicit block
 conversion is the curl-substrate path.
 
-**Marker normalization (both paths).** The page must always carry **exactly one** marker. On CREATE
-the marker is the first body block; on UPDATE never remove it. Never write a markerless page.
+**Marker + usage-ledger preservation (both paths).** The page must always carry **exactly one**
+marker. On CREATE the marker is the first body block; on UPDATE never remove it. Never write a markerless body. Never write a markerless page. If the existing page content already contains the canonical managed `## Lisa Usage` section, preserve that section when regenerating the page body unless the caller intentionally supplied an updated canonical section; use the shared `usage-accounting` serializer/merge path rather than freehand block edits to ledger rows.
 
 **CREATE:**
 
@@ -86,7 +86,7 @@ the marker is the first body block; on UPDATE never remove it. Never write a mar
    (`operation: archive-page` is page-level, so for blocks delete via the blocks API through
    `notion-access` or, where block deletion isn't available, replace their text in place) and
    `operation: append-blocks` the regenerated blocks. Do not duplicate the whole spec as a dated
-   note, and never drop the marker.
+   note, and never drop the marker or an existing managed `## Lisa Usage` section.
 
 ## Phase 4 — Return
 
@@ -102,6 +102,8 @@ outcome: created | reused
 
 - All access via `lisa:notion-access`; never touch the Notion API/MCP directly.
 - Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
 - Never down-rank a PRD whose Status is already past `ready`.
 - Resolve the Status vocabulary from config (`notion.statusProperty`, `notion.values.*`) — never
   hardcode value names.

package/plugins/src/base/skills/prd-source-write/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: ["Skill", "Bash", "Read"]
 
 Thin dispatcher. Resolves the configured PRD `source` and delegates to the matching vendor PRD
 writer, which owns the concrete create/update, the lifecycle-role application, and the marker-based
-dedupe. This skill only routes — it never talks to a source API itself.
+dedupe. When the supplied PRD body already contains the canonical `## Lisa Usage` ledger, the
+vendor writer must preserve that managed section on update instead of dropping it or reformatting it
+ad hoc. This skill only routes — it never talks to a source API itself.
 
 See the `config-resolution` rule for the full configuration schema and the PRD lifecycle roles.
 
@@ -74,6 +76,8 @@ prior PRD-source-write behavior to preserve, so omitted means `draft`.
 
 - Never bypass dispatch — a vendor-neutral caller calling a `*-write-prd` skill directly defeats the
   per-project source switch (exactly the `tracker-write` discipline, mirrored).
+- Never drop or duplicate an existing managed `## Lisa Usage` section. Writer-specific preservation
+  and fallback behavior belongs in the vendor writers and follows the `usage-accounting` contract.
 - Never accept a source outside `{notion, confluence, github, linear}`. `jira` and `file` fail loudly.
 - Never mutate the spec between layers. The vendor writers define their own create/dedupe contract.
 - Never invent a PRD lifecycle role string — resolve every role from `config-resolution` per vendor.

package/plugins/src/base/skills/tracker-write/SKILL.md

@@ -6,7 +6,12 @@ allowed-tools: ["Skill", "Bash", "Read"]
 
 # Tracker Write: $ARGUMENTS
 
-Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor write skill.
+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.
 
@@ -40,6 +45,9 @@ See the `config-resolution` rule for the full configuration schema and skill-map
 ## 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/src/base/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.