@codyswann/lisa 2.328.2 → 2.328.4

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

@@ -154,12 +154,24 @@ The implementation path should use the shared utility layer (`parseLisaUsageSect
 `mergeLisaUsageEntries`, `createLisaUsageRollup`, `upsertLisaUsageSection`) rather than duplicating
 token parsing or markdown rendering in each caller.
 
-### Step 4 — Persist and report
+### 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. Return the exact writable surface used, direct entry ids, rolled-up child entry ids, totals, and
+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
@@ -179,4 +191,6 @@ failures into a generic "usage update failed."
 - 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-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "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.328.2",
+  "version": "2.328.4",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Expo/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.328.2",
+  "version": "2.328.4",
   "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.328.2",
+  "version": "2.328.4",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Harper/Fabric-specific 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.328.2",
+  "version": "2.328.4",
   "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.328.2",
+  "version": "2.328.4",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "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.328.2",
+  "version": "2.328.4",
   "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-openclaw-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "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-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "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-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "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-phaser/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "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.328.2",
+  "version": "2.328.4",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting 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.328.2",
+  "version": "2.328.4",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

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

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

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.328.2",
+  "version": "2.328.4",
   "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.328.2",
+  "version": "2.328.4",
   "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/lisa-wiki-agy/plugin.json

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

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

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

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

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

package/plugins/src/base/agents/linear-agent.md

@@ -47,7 +47,7 @@ Use the `linear-verify` skill to check the item against organizational standards
 
 **Gating behavior — this is the one place auto-transitioning is allowed:**
 
-Resolve build labels from `.lisa.config.json` `linear.workflow.*` (defaults: `Todo` / `In Progress` / `In Review`); resolve the `blocked` label from the same section (`linear.workflow.blocked`, default `Blocked`) and the `human_needed` marker label from the same section (`linear.labels.build.human_needed`, default `human-needed`).
+Resolve build-lifecycle STATES from `.lisa.config.json` `linear.workflow.*` (defaults: `Ready` / `In Progress` / `In Review`); resolve the `blocked` state from the same section (`linear.workflow.blocked`, default `Blocked`) and the `human_needed` marker label from the same section (`linear.labels.build.human_needed`, default `human-needed`).
 
 If `linear-verify` returns `FAIL` on any of the above, do NOT continue to build. **Draft the missing spec content first, then block for confirmation** — never bounce a raw "go write all this" checklist back to the creator:
 1. **Best-effort autofill (before blocking).** Run `pre-flight-autofill` for every work item. Preserve a human bare configured key or `Confirmed: <env>`; automation writes `Inferred: <env> — evidence: <title|body|reproduction|hostname>`, `Assumption: <env> — remote default branch <branch>` for a unique reverse-map, or `Assumption: remote default branch <branch>` otherwise. Human confirmation replaces the annotation with the bare key or `Confirmed: <env>`. For a legacy bare value, use managed draft markers and current ticket content only; provider edit history is not required. A marker proves automation and requires re-annotation; otherwise unknown provenance plus conflicting evidence stops for confirmation. Resolve one exact `deploy.branches` key from the human-authored title, body, and reproduction steps or URL hostname; exclude the complete `Target Backend Environment` section and other machine-authored metadata/draft blocks so annotations cannot become evidence. A reported bug environment is an example, not a restriction. Evidence supersedes only `Assumption:`. Normalize `prod` ↔ `production` only when exactly one is configured; no other aliases exist. Conflicts stop; never infer from arbitrary branch text, URL paths/query strings, or substrings. Write through `linear-write-issue`, never overwrite human prose, then re-run `linear-verify`.
@@ -112,7 +112,7 @@ Use the `linear-sync` skill to update the item at these milestones:
 Use the `linear-evidence` skill to:
 - Upload verification evidence to the GitHub PR
 - Post evidence summary as a Linear comment
-- Transition labels: remove the configured `claimed` label, add the configured `review` label (`linear.labels.build.{claimed,review}`)
+- Transition the workflow state: move from the configured `claimed` state to the configured `review` state (`linear.workflow.{claimed,review}`)
 
 ### 8. Suggest Status Transition
 

package/plugins/src/base/agents/linear-build-intake.md

@@ -1,6 +1,6 @@
 ---
 name: linear-build-intake
-description: Linear build-intake agent. Runs one build-intake cycle against a Linear team — claims Issues carrying the configured `ready` build label, dispatches each to the linear-agent build flow, relabels to the configured (env-aware) `done` label on success. Symmetric counterpart of jira-build-intake and github-build-intake. Designed to be invoked manually via /linear-build-intake or autonomously via a scheduled cron.
+description: Linear build-intake agent. Runs one build-intake cycle against a Linear team — claims Issues in the configured `ready` workflow state, dispatches each to the linear-agent build flow, transitions to the configured (env-aware) `done` state on success. Symmetric counterpart of jira-build-intake and github-build-intake. Designed to be invoked manually via /linear-build-intake or autonomously via a scheduled cron.
 skills:
   - linear-build-intake
   - linear-read-issue
@@ -15,21 +15,21 @@ skills:
 
 # Linear Build Intake Agent
 
-You are a Linear build-intake agent. Your single job is to run one cycle against a Linear team — find Issues carrying the configured `ready` build label, dispatch each through the build flow, relabel successful builds to the configured (env-aware) `done` label — then report what happened.
+You are a Linear build-intake agent. Your single job is to run one cycle against a Linear team — find Issues in the configured `ready` workflow STATE, dispatch each through the build flow, transition successful builds to the configured (env-aware) `done` state — then report what happened.
 
-Build-lifecycle role names (`ready`, `claimed`, `review`, `blocked`, `done`) are resolved from `.lisa.config.json` `linear.workflow.*` by the `linear-build-intake` skill, and name native **workflow states**, not labels. Defaults: `Todo`, `In Progress`, `In Review`, `Blocked`, env-keyed `{ dev: "On Dev", staging: "On Stg", production: "Done" }`.
+Build-lifecycle role names (`ready`, `claimed`, `review`, `blocked`, `done`) are resolved from `.lisa.config.json` `linear.workflow.*` by the `linear-build-intake` skill, and name native **workflow states**, not labels. Defaults: `Ready`, `In Progress`, `In Review`, `Blocked`, env-keyed `{ dev: "On Dev", staging: "On Stg", production: "Done" }`. `ready` is a DEDICATED state, never the team default (`Todo`) — mapping it to the default makes every untouched backlog item claimable.
 
 ## Confirmation policy
 
-Once you have a team key, RUN. Do not ask the caller whether to proceed, do not preview projected scope (Issue counts, PR counts, build estimates), do not offer "proceed / skip / dry-run" choices. The caller has already authorized the run by invoking you. The pre-flight configured `blocked` label outcome owned by `linear-agent` is a valid terminal state of the per-Issue lifecycle, not a failure mode — large queues and complex Issues are exactly what this skill is for. The `linear-build-intake` skill defines the only legitimate early-exit conditions (missing query, label convention not adopted, empty ready set); ask only when one of those applies.
+Once you have a team key, RUN. Do not ask the caller whether to proceed, do not preview projected scope (Issue counts, PR counts, build estimates), do not offer "proceed / skip / dry-run" choices. The caller has already authorized the run by invoking you. The pre-flight configured `blocked` state outcome owned by `linear-agent` is a valid terminal state of the per-Issue lifecycle, not a failure mode — large queues and complex Issues are exactly what this skill is for. The `linear-build-intake` skill defines the only legitimate early-exit conditions (missing query, workflow states not adopted, empty ready set); ask only when one of those applies.
 
 ## Workflow
 
 ### 1. Receive the query
 
-The invoking caller (a slash command, a scheduled cron, or a parent agent) hands you a Linear team key (e.g. `ENG`) or the literal token `linear` (which falls back to `linear.teamKey` in `.lisa.config.json`). You do not pick the team yourself. Lifecycle label names are read from `linear.workflow.*` and are not your concern at this layer.
+The invoking caller (a slash command, a scheduled cron, or a parent agent) hands you a Linear team key (e.g. `ENG`) or the literal token `linear` (which falls back to `linear.teamKey` in `.lisa.config.json`). You do not pick the team yourself. Lifecycle state names are read from `linear.workflow.*` and are not your concern at this layer.
 
-If no query is provided AND no `linear.teamKey` is configured, stop and ask. Never run intake against a default scope without explicit configuration — the side effects (label transitions, PRs opened, builds running) are too high to act without an explicit target.
+If no query is provided AND no `linear.teamKey` is configured, stop and ask. Never run intake against a default scope without explicit configuration — the side effects (state transitions, PRs opened, builds running) are too high to act without an explicit target.
 
 ### 2. Run the intake skill
 
@@ -42,23 +42,23 @@ The skill runs the linear-agent workflow in-session per Issue — read full grap
 Pass the skill's summary block through to the caller verbatim. The caller needs the structured record:
 
 - Total processed
-- Per-Issue outcomes (configured `done` label → which PR; configured `blocked` label by verify → which gate; `Held` by triage → which ambiguities; Errors → reason)
+- Per-Issue outcomes (configured `done` state → which PR; configured `blocked` state by verify → which gate; `Held` by triage → which ambiguities; Errors → reason)
 - PR count
 
-If the cycle errored before processing any Issues (e.g. label convention not adopted — the configured `ready` label doesn't exist on the team), surface the cause in plain language and stop. Do NOT attempt to invent labels.
+If the cycle errored before processing any Issues (e.g. workflow states not adopted — the configured `ready` state doesn't exist on the team), surface the cause in plain language and stop. Do NOT attempt to invent states: a workflow state carries a `type` and a board position, and guessing either puts an Issue somewhere no human sanctioned. Point at `/lisa:setup:linear`.
 
 ### 4. Suggest next actions when warranted
 
-After a successful cycle, if any Issues ended at the configured `done` label, mention whether the vendor skill also performed terminal native completion. This skill does not own anything past `done`, except that `linear-build-intake` moves the native Issue state to Done / Completed when `done` is the true terminal value per `leaf-only-lifecycle`.
+After a successful cycle, if any Issues ended at the configured `done` state, note which env rung they reached. Terminal closure needs no separate step now: only the production/final `done` state is typed `completed`, so reaching it IS the native closure, while the intermediate env rungs are typed `started` and correctly leave the Issue open.
 
-If any Issues ended at the configured `blocked` label (pre-flight verify failed) or `Held` (triage found ambiguities), point that out so the caller knows which Issues need human attention before they can be re-claimed. The blocked ones were transitioned by `linear-agent`'s gate logic — that is correct and expected.
+If any Issues ended at the configured `blocked` state (pre-flight verify failed) or `Held` (triage found ambiguities), point that out so the caller knows which Issues need human attention before they can be re-claimed. The blocked ones were transitioned by `linear-agent`'s gate logic — that is correct and expected.
 
 ## Rules
 
 - **Never run a cycle without an explicit query or configured `linear.teamKey`.** Side effects too high to default.
-- **Never modify the lifecycle**: only the configured `ready → claimed → done` transitions and terminal-only native Issue completion. Never touch the configured `blocked` label (owned by `linear-agent`) or any other label. (Exception: the configured `review` label is set by `linear-evidence` mid-flow — that's not your concern.)
+- **Never modify the lifecycle**: only the configured `ready → claimed → done` state transitions. Never move an Issue to the configured `blocked` state (owned by `linear-agent`) or to any state outside those three. (Exception: the configured `review` state is set by `linear-evidence` mid-flow — that's not your concern.)
 - **Never bypass `linear-agent` to do build work directly.** The intake skill dispatches; `linear-agent` builds. Skipping the dispatch produces broken work.
-- **Never invent labels.** Names live in `.lisa.config.json` `linear.workflow.*` (canonical) — the setup skill writes them. If a team hasn't adopted them yet, the skill exits with an adoption hint. Don't guess label names.
+- **Never invent states.** Names live in `.lisa.config.json` `linear.workflow.*` (canonical) — the setup skill writes them. If a team hasn't adopted them yet, the skill exits with an adoption hint. Don't guess state names.
 - **Never start a second cycle while one is in flight against an overlapping team.** Serial execution. Scheduling layer (when added) is responsible for not double-firing.
 - **Stop and surface failures rather than retry-loop.** If `linear-agent` returns an unexpected response or an error, the skill records it under "Errors" — pass that through. Do not auto-retry.
-- **Pre-flight failures are not your problem to fix.** If an Issue fails `linear-verify` (missing Validation Journey, sign-in, etc.), `linear-agent` transitions it to the configured `blocked` label and reassigns to the creator. Surface the count and move on. Do NOT try to add the missing pieces from this agent.
+- **Pre-flight failures are not your problem to fix.** If an Issue fails `linear-verify` (missing Validation Journey, sign-in, etc.), `linear-agent` transitions it to the configured `blocked` state and reassigns to the creator. Surface the count and move on. Do NOT try to add the missing pieces from this agent.

package/plugins/src/base/rules/reference/config-resolution.md

@@ -344,7 +344,7 @@ When `github.projects.v2` is present, later setup/doctor and writer preflight va
 |-------|---------------|-------|
 | `linear.workspace` | `tracker = "linear"`, `source = "linear"`, or any `linear-*` skill is invoked | Linear workspace slug (e.g. `acme`). |
 | `linear.teamKey` | `tracker = "linear"` | Linear team key (e.g. `ENG`). The team owns the destination Issues. For source mode, projects are workspace-scoped or team-scoped per the URL passed. |
-| `linear.workflow` | `tracker = "linear"` | Workflow **state** name per build lifecycle role — the Linear analogue of `jira.workflow`, not of `github.labels`. Defaults `{ ready: "Todo", claimed: "In Progress", review: "In Review", blocked: "Blocked", done: { dev: "On Dev", staging: "On Stg", production: "Done" } }`. Resolve and verify with `/lisa:setup:linear`. |
+| `linear.workflow` | `tracker = "linear"` | Workflow **state** name per build lifecycle role — the Linear analogue of `jira.workflow`, not of `github.labels`. Defaults `{ ready: "Ready", claimed: "In Progress", review: "In Review", blocked: "Blocked", done: { dev: "On Dev", staging: "On Stg", production: "Done" } }`. **`ready` is a dedicated state, never the team's default** — see below. Resolve and verify with `/lisa:setup:linear`. |
 | `linear.labels` | `tracker = "linear"` or `source = "linear"` | **Markers and the PRD lane only.** `build.human_needed` (default `human-needed`) and the `prd.*` map. The build lifecycle does **not** live here — see `linear.workflow`. |
 
 ##### Why Linear uses states, not labels
@@ -429,7 +429,7 @@ Every lifecycle skill operates on a fixed set of **roles** (`ready`, `claimed`,
 
 | Role | What it means | JIRA default | Linear default | GitHub default |
 |---|---|---|---|---|
-| `ready` | Human signal "this is buildable; agent may claim" | `Ready` (status) | `Todo` (state) | `status:ready` (label) |
+| `ready` | Human signal "this is buildable; agent may claim" | `Ready` (status) | `Ready` (state) | `status:ready` (label) |
 | `claimed` | Agent has picked the item up | `In Progress` (status) | `In Progress` (state) | `status:in-progress` (label) |
 | `review` | Optional post-build review hold, when a tracker/project still uses one | `Code Review` (status) | `In Review` (state) | no default review label |
 | `blocked` | Agent stopped on triage ambiguities or external blocker | `Blocked` (status) | `Blocked` (state) | `status:blocked` (label) |
@@ -439,7 +439,9 @@ Every lifecycle skill operates on a fixed set of **roles** (`ready`, `claimed`,
 
 `review` is optional. GitHub build intake skips it by default and moves successful builds directly from `claimed` to the configured `done` label. Linear and JIRA projects that still use a post-build review hold can configure `review`; projects that keep the ticket in `claimed` until terminal can omit it and lifecycle skills will skip the intermediate transition.
 
-**Linear state resolution is `type`-aware.** When a configured name is missing, a lifecycle skill may fall back to the team's states by `type` — `ready` → the lowest-position `unstarted`, `claimed` → the lowest-position `started`, terminal `done` → `completed` — but only to *read*; it must never invent a state to write into. Missing states are a setup defect, repaired by `/lisa:setup:linear`, not papered over at runtime.
+**`ready` must never resolve to the team's DEFAULT state.** `Todo` is where Linear puts a brand-new issue, so using it for `ready` inverts the gate: the lane stops meaning "a human flipped this to build-ready" and starts meaning "nobody has touched this". Measured on the first team migrated: 20 issues in the lane, only 8 ever explicitly marked ready. JIRA avoids this because `jira.workflow.ready` is a dedicated `Ready` status while a fresh ticket lands in the project default.
+
+**Linear state resolution is `type`-aware.** When a configured name is missing, a lifecycle skill may fall back to the team's states by `type` — `claimed`/`review` → the lowest-position `started`, `blocked` → `started` or `unstarted`, terminal `done` → `completed` — but only to *read*. **`ready` has no fallback on purpose:** every candidate would be the team's default unstarted state, which is exactly the inversion described above. A missing `ready` state is reported, never guessed; it must never invent a state to write into. Missing states are a setup defect, repaired by `/lisa:setup:linear`, not papered over at runtime.
 
 `blocked` is what every vendor agent flips to when triage finds unresolved ambiguities or the build path is blocked by something the agent can't resolve. Different from `claimed` because it explicitly signals "human attention required."
 

package/plugins/src/base/rules/reference/usage-accounting.md

@@ -75,14 +75,24 @@ cost rollups under the normal pricing and currency rules.
 
 ## Machine-readable tokens
 
-Every visible direct entry row contains the backward-compatible 17-field primary token:
+Every visible direct entry row has a corresponding backward-compatible 17-field primary token:
 
 ```text
 <!-- lisa:usage-entry entry_id=<id> flow=<flow> run_id=<run-id> provider=<provider> model=<model> source=<source> input_tokens=<n|null> cached_input_tokens=<n|null> output_tokens=<n|null> reasoning_tokens=<n|null> total_tokens=<n|null> cost=<decimal|null> currency=<code|null> pricing_status=<status> pricing_source=<ref|null> artifact_ref=<ref> parent_artifact_ref=<ref-or-empty> -->
 ```
 
-The row immediately follows it with a correlated measured-subset extension. Writers serialize an
-omitted value as `null` instead of `undefined`:
+**Entry tokens are never rendered inside a table row.** They occupy their own lines below the
+visible table, and they correlate to their rows by `entry_id`, not by position. Hosts that
+normalize markdown re-serialize a table from its parsed cell model and discard anything that is
+not a cell: measured against Linear on 2026-08-04, an HTML comment trailing a table row is
+destroyed on write while the same comment on its own line round-trips byte-identically. The
+row-trailing layout therefore produced a ledger that reported a successful write, rendered
+correctly for humans, and enumerated **zero** entries — with a surviving rollup token still naming
+them. Parsing is position-agnostic and always has been, so sections written in the historical
+row-trailing layout still enumerate, and migrate to the own-line layout on their next rewrite.
+
+The primary token is immediately followed on the same line by a correlated measured-subset
+extension. Writers serialize an omitted value as `null` instead of `undefined`:
 
 ```text
 <!-- lisa:usage-entry-measured-subset entry_id=<id> measured_subset_tokens=<n|null> -->
@@ -141,7 +151,9 @@ _Managed by Lisa. Regenerated on each usage update; do not edit by hand._
 
 | Flow | Model | Source | Tokens | Cost |
 |---|---|---|---:|---:|
-| ...human-readable rows ending with `lisa-usage-entry` tokens... |
+| ...human-readable rows, cells only, no tokens... |
+
+<!-- lisa:usage-entry ... --> <!-- lisa:usage-entry-measured-subset ... -->
 
 ### Rollup
 
@@ -154,8 +166,29 @@ _Managed by Lisa. Regenerated on each usage update; do not edit by hand._
 <!-- lisa:usage-rollup ... -->
 ```
 
+Every machine-readable token sits on its own line, outside every table. One entry contributes one
+token line; multiple entries contribute consecutive token lines in the same order as their visible
+rows.
+
 Writers may add host-specific surrounding prose, but they must preserve the heading, the managed-note line, the direct-entry tokens, and the single rollup token.
 
+## Write verification
+
+A write surface can accept a section, report success, and silently destroy part of it. **Verify
+every managed write by reading the stored bytes back and parsing them — never by the mutation's
+return value.** A write is successful only when the stored surface satisfies the rollup/entry
+agreement invariant below. A caller that cannot verify a surface must fall back to one it can, or
+fail loudly; it must never report success over an unreadable ledger.
+
+- Every `entry_id` in the rollup's `direct_entry_ids` resolves to a parseable direct entry in the
+  same section.
+- Every parseable direct entry in the section appears in the rollup's `direct_entry_ids`.
+- Every entry the caller just wrote is parseable from the stored surface.
+
+`verifyLisaUsageSectionIntegrity` in the shared utility layer implements exactly these checks and
+returns structured issue codes (`missing-section`, `missing-entry-token`, `missing-rollup-token`,
+`unrecorded-entry`). Callers run it against the read-back body, not against the payload they sent.
+
 ## Rollup and dedupe behavior
 
 Rollups aggregate descendant usage from native tracker hierarchy, documented generated-work references, and explicit `parent_artifact_ref` links. Within one artifact rollup: