@codyswann/lisa 4.54.5 → 4.54.6

package/package.json

@@ -181,7 +181,7 @@
     "zod-validation-error": "^4.0.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.54.5",
+  "version": "4.54.6",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -329,7 +329,7 @@
     "test": "tests"
   },
   "types": "./dist/index.d.ts",
-  "lisaReleaseCommit": "4a1f31779616e3485d28843387ee06e3bccd8888",
-  "gitHead": "4a1f31779616e3485d28843387ee06e3bccd8888",
-  "lisaReleaseTag": "v4.54.5"
+  "lisaReleaseCommit": "1d372a92f2f3ff23f6ecce9d09f14548b89ba609",
+  "gitHead": "1d372a92f2f3ff23f6ecce9d09f14548b89ba609",
+  "lisaReleaseTag": "v4.54.6"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.54.5",
+  "version": "4.54.6",
   "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": "4.54.5",
+  "version": "4.54.6",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-github-validate-issue/SKILL.md

@@ -71,6 +71,25 @@ prd_source: "https://notion.so/..."    # set when the issue was generated from a
 
 If the caller passes only an issue ref, fetch via `gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,state,milestone,assignees`, parse the body sections, derive the spec fields — including `runtime_behavior_change`, derived from the `## Target Backend Environment` declaration per `derived-branch-plan` and authoritative over any caller assertion — then run gates. The parser lives in `lisa-github-read-issue` (composition).
 
+## Standalone use, against an item that already exists
+
+This is a supported entry point, not only an internal step of a caller flow.
+Point it at a live issue and it fetches and validates the stored state:
+
+```text
+Skill(lisa-github-validate-issue) with owner/repo#1234
+```
+
+Use it whenever the issue reached the tracker by some path other than
+`lisa-github-write-issue` — a team's own script, a workflow step, a cron, anything holding the
+credentials but no skill runtime. Those paths get neither the pre-write nor the
+post-write gate, and their own read-back substitutes for neither: a read-back
+proves the tracker stored what was sent, never that what was sent was any good.
+
+The gate definitions live here on purpose, so every caller picks up a change
+automatically. Running this skill by hand is the same gate the write path runs,
+not an approximation of it.
+
 ## Gates
 
 Gates are grouped into **Specification** (spec-only checks, no GitHub lookups) and **Feasibility** (requires GitHub lookups). The dry-run path may opt to run Specification gates only via `--spec-only`; the write path runs both.

package/plugins/lisa/.codex-plugin/skills/lisa-github-verify/SKILL.md

@@ -27,3 +27,20 @@ Pass through `lisa-github-validate-issue`'s structured output unchanged. Do not
 - This skill is read-only. It never edits the issue, posts comments, or changes labels.
 - If a gate fails, the recommendation is part of the validator's report; surface it as-is.
 - The Validation Journey check (S11) parses the `## Validation Journey` markdown section — same parser logic as `lisa-github-add-journey` and `lisa-github-journey`.
+
+## Comparison is semantic, never byte-exact
+
+Re-run the validator against the live issue. Do NOT compare the stored body
+against what was sent byte for byte.
+
+The reason is measured rather than theoretical. Trackers normalize markdown on
+write: `-` bullets become `*`, a bare URL is wrapped as `[url](<url>)`, bold
+emphasis is re-segmented around inline code spans. All lossless, all
+rendering-identical, and all of it makes a byte comparator report failure on a
+write that was completely fine. A comparator that cannot tell vendor
+normalization from corruption fails on healthy writes and trains its reader to
+ignore it, which costs more than the check was ever worth.
+
+Compare meaning: run `lisa-github-validate-issue` against the stored item and let the gates
+decide. Where a single field must be compared directly, normalize both sides
+first.

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

@@ -12,6 +12,41 @@ This skill is the GitHub counterpart of `lisa-jira-write-ticket`. The two skills
 
 Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
 
+## Writing by another path? The gates still apply
+
+A team that talks to its tracker through its own script is doing a normal
+thing — the script usually owns the credential plumbing, and Lisa neither
+controls nor wants to control it. What that script does NOT get is either half
+of this skill's quality gate, and nothing about the write says so.
+
+**A read-back is not the missing check.** A bespoke path almost always re-reads
+the issue after writing and confirms the tracker stored what was sent. That is
+worth doing and it is not this. It proves TRANSPORT: the API accepted the
+payload and the field values round-tripped. It cannot fail for the reason these
+gates exist, because it never looks at whether what was sent was any good — a
+issue with no acceptance criteria, no parent, and a human decision left sitting
+in the middle of it round-trips perfectly. That is the dangerous half of the
+shape: a failing control gets investigated, a misread one gets trusted.
+
+So a write by any other path still owes both phases, and both run standalone
+against an item that already exists:
+
+| Phase | Skill | What it costs you |
+|---|---|---|
+| Pre-write validate | `lisa-github-validate-issue` | Run it on the draft before you send it |
+| Post-write verify | `lisa-github-verify` | Run it on the live issue after you send it |
+
+```text
+Skill(lisa-github-validate-issue) with the draft issue, or with a reference to a live one
+Skill(lisa-github-verify) with owner/repo#1234
+```
+
+**These are plugin-resident skills invoked through the Skill tool.** They are
+not shell scripts and will not appear in any repository's `scripts/` directory,
+including yours. An agent that searches the repo it is standing in, finds
+nothing, and concludes the capability is absent has made the one mistake that
+turns a local script from the convenient option into the only one.
+
 ## Prerequisites
 
 - `gh` CLI installed and authenticated (`gh auth status` must succeed). The skill never falls back to a different transport — if `gh` is unauthenticated, stop and surface the auth error.

package/plugins/lisa/.codex-plugin/skills/lisa-jira-validate-ticket/SKILL.md

@@ -68,6 +68,25 @@ prd_source: "https://notion.so/..."    # set when the ticket was generated from
 
 If the caller passes only a ticket key, fetch the ticket via `lisa-atlassian-access` `operation: read-ticket key: <KEY>`, derive the same fields from the fetched data — including `runtime_behavior_change` (derived from the `Target Backend Environment` declaration per `derived-branch-plan`, and authoritative over any caller assertion), `build_ready` (label set contains the resolved `READY_ROLE` — merged `jira.workflow.ready`, default `status:ready` — never a hard-coded label) and `child_refs` (sub-tasks plus `is blocked by` parentage, resolved as in `lisa-jira-read-ticket`) so S15 can classify the ticket — then run gates.
 
+## Standalone use, against an item that already exists
+
+This is a supported entry point, not only an internal step of a caller flow.
+Point it at a live ticket and it fetches and validates the stored state:
+
+```text
+Skill(lisa-jira-validate-ticket) with PROJ-1234
+```
+
+Use it whenever the ticket reached the tracker by some path other than
+`lisa-jira-write-ticket` — a team's own script, a workflow step, a cron, anything holding the
+credentials but no skill runtime. Those paths get neither the pre-write nor the
+post-write gate, and their own read-back substitutes for neither: a read-back
+proves the tracker stored what was sent, never that what was sent was any good.
+
+The gate definitions live here on purpose, so every caller picks up a change
+automatically. Running this skill by hand is the same gate the write path runs,
+not an approximation of it.
+
 ## Gates
 
 Gates are grouped into **Specification** (spec-only checks, no JIRA lookups) and **Feasibility** (requires JIRA lookups). The dry-run path may opt to run Specification gates only; the write path runs both.

package/plugins/lisa/.codex-plugin/skills/lisa-jira-verify/SKILL.md

@@ -28,3 +28,20 @@ Pass through `lisa-jira-validate-ticket`'s structured output unchanged. Do not s
 - This skill is read-only. It never edits the ticket, posts comments, or changes status.
 - If a gate fails, the recommendation is part of the validator's report; surface it as-is.
 - Validation Journey checks (S11) historically required a parser script (`parse-plan.py`); the parser logic now lives inside `lisa-jira-validate-ticket` so this skill no longer shells out to it.
+
+## Comparison is semantic, never byte-exact
+
+Re-run the validator against the live ticket. Do NOT compare the stored body
+against what was sent byte for byte.
+
+The reason is measured rather than theoretical. Trackers normalize markdown on
+write: `-` bullets become `*`, a bare URL is wrapped as `[url](<url>)`, bold
+emphasis is re-segmented around inline code spans. All lossless, all
+rendering-identical, and all of it makes a byte comparator report failure on a
+write that was completely fine. A comparator that cannot tell vendor
+normalization from corruption fails on healthy writes and trains its reader to
+ignore it, which costs more than the check was ever worth.
+
+Compare meaning: run `lisa-jira-validate-ticket` against the stored item and let the gates
+decide. Where a single field must be compared directly, normalize both sides
+first.

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

@@ -12,6 +12,41 @@ Create or update a JIRA ticket with all required relationships, metadata, and qu
 
 Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
 
+## Writing by another path? The gates still apply
+
+A team that talks to its tracker through its own script is doing a normal
+thing — the script usually owns the credential plumbing, and Lisa neither
+controls nor wants to control it. What that script does NOT get is either half
+of this skill's quality gate, and nothing about the write says so.
+
+**A read-back is not the missing check.** A bespoke path almost always re-reads
+the ticket after writing and confirms the tracker stored what was sent. That is
+worth doing and it is not this. It proves TRANSPORT: the API accepted the
+payload and the field values round-tripped. It cannot fail for the reason these
+gates exist, because it never looks at whether what was sent was any good — a
+ticket with no acceptance criteria, no parent, and a human decision left sitting
+in the middle of it round-trips perfectly. That is the dangerous half of the
+shape: a failing control gets investigated, a misread one gets trusted.
+
+So a write by any other path still owes both phases, and both run standalone
+against an item that already exists:
+
+| Phase | Skill | What it costs you |
+|---|---|---|
+| Pre-write validate | `lisa-jira-validate-ticket` | Run it on the draft before you send it |
+| Post-write verify | `lisa-jira-verify` | Run it on the live ticket after you send it |
+
+```text
+Skill(lisa-jira-validate-ticket) with the draft ticket, or with a reference to a live one
+Skill(lisa-jira-verify) with PROJ-1234
+```
+
+**These are plugin-resident skills invoked through the Skill tool.** They are
+not shell scripts and will not appear in any repository's `scripts/` directory,
+including yours. An agent that searches the repo it is standing in, finds
+nothing, and concludes the capability is absent has made the one mistake that
+turns a local script from the convenient option into the only one.
+
 ## Phase 1 — Resolve Intent
 
 Determine from $ARGUMENTS and context whether this is a CREATE or UPDATE:

package/plugins/lisa/.codex-plugin/skills/lisa-linear-validate-issue/SKILL.md

@@ -69,6 +69,25 @@ prd_source: "https://notion.so/..."    # set when the Issue was generated from a
 
 If the caller passes only an identifier, fetch the item via `lisa-linear-access operation: get-issue` (Issue) or `lisa-linear-access operation: get-project` (Project), derive the same fields from the fetched data — including `runtime_behavior_change` (derived from the `## Target Backend Environment` declaration per `derived-branch-plan`, and authoritative over any caller assertion), `build_ready` (the Issue's state is the configured `ready` state) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa-linear-read-issue`) so S15 can classify the item — then run gates.
 
+## Standalone use, against an item that already exists
+
+This is a supported entry point, not only an internal step of a caller flow.
+Point it at a live issue and it fetches and validates the stored state:
+
+```text
+Skill(lisa-linear-validate-issue) with ENG-1234
+```
+
+Use it whenever the issue reached the tracker by some path other than
+`lisa-linear-write-issue` — a team's own script, a workflow step, a cron, anything holding the
+credentials but no skill runtime. Those paths get neither the pre-write nor the
+post-write gate, and their own read-back substitutes for neither: a read-back
+proves the tracker stored what was sent, never that what was sent was any good.
+
+The gate definitions live here on purpose, so every caller picks up a change
+automatically. Running this skill by hand is the same gate the write path runs,
+not an approximation of it.
+
 ## Gates
 
 Gates are grouped into **Specification** (spec-only checks, no Linear lookups) and **Feasibility** (requires Linear lookups). The dry-run path may opt to run Specification gates only; the write path runs both.

package/plugins/lisa/.codex-plugin/skills/lisa-linear-verify/SKILL.md

@@ -49,3 +49,20 @@ If the verdict is `FAIL`, the caller should fix the item and re-run verify. Neve
 - Never write to Linear. Read-only.
 - Never short-circuit the validator. Always run the full gate set.
 - If `get_issue` / `get_project` returns an access error, surface it and exit — don't pretend the item is fine.
+
+## Comparison is semantic, never byte-exact
+
+Re-run the validator against the live issue. Do NOT compare the stored body
+against what was sent byte for byte.
+
+The reason is measured rather than theoretical. Trackers normalize markdown on
+write: `-` bullets become `*`, a bare URL is wrapped as `[url](<url>)`, bold
+emphasis is re-segmented around inline code spans. All lossless, all
+rendering-identical, and all of it makes a byte comparator report failure on a
+write that was completely fine. A comparator that cannot tell vendor
+normalization from corruption fails on healthy writes and trains its reader to
+ignore it, which costs more than the check was ever worth.
+
+Compare meaning: run `lisa-linear-validate-issue` against the stored item and let the gates
+decide. Where a single field must be compared directly, normalize both sides
+first.

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

@@ -33,6 +33,41 @@ Linear's data model maps Epic / Story / Sub-task to **different entity types**.
 
 The build lifecycle uses native **workflow states** (`Ready`, `In Progress`, `Blocked`, `On Dev`, `On Stg`, `Done`, plus an optional review state a project may bind), resolved per role from `linear.workflow` — see "Why Linear uses states, not labels" in `config-resolution`. A new **leaf** work unit is created in the configured `ready` state only on explicit `build_ready: true`; omitted or `false` leaves it in the team's default backlog state, and a container is never put in `ready` at all (see the Build-ready control input below).
 
+## Writing by another path? The gates still apply
+
+A team that talks to its tracker through its own script is doing a normal
+thing — the script usually owns the credential plumbing, and Lisa neither
+controls nor wants to control it. What that script does NOT get is either half
+of this skill's quality gate, and nothing about the write says so.
+
+**A read-back is not the missing check.** A bespoke path almost always re-reads
+the issue after writing and confirms the tracker stored what was sent. That is
+worth doing and it is not this. It proves TRANSPORT: the API accepted the
+payload and the field values round-tripped. It cannot fail for the reason these
+gates exist, because it never looks at whether what was sent was any good — a
+issue with no acceptance criteria, no parent, and a human decision left sitting
+in the middle of it round-trips perfectly. That is the dangerous half of the
+shape: a failing control gets investigated, a misread one gets trusted.
+
+So a write by any other path still owes both phases, and both run standalone
+against an item that already exists:
+
+| Phase | Skill | What it costs you |
+|---|---|---|
+| Pre-write validate | `lisa-linear-validate-issue` | Run it on the draft before you send it |
+| Post-write verify | `lisa-linear-verify` | Run it on the live issue after you send it |
+
+```text
+Skill(lisa-linear-validate-issue) with the draft issue, or with a reference to a live one
+Skill(lisa-linear-verify) with ENG-1234
+```
+
+**These are plugin-resident skills invoked through the Skill tool.** They are
+not shell scripts and will not appear in any repository's `scripts/` directory,
+including yours. An agent that searches the repo it is standing in, finds
+nothing, and concludes the capability is absent has made the one mistake that
+turns a local script from the convenient option into the only one.
+
 ## Phase 1 — Resolve Intent
 
 Determine from `$ARGUMENTS` and context whether this is a CREATE or UPDATE:

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

@@ -71,6 +71,25 @@ prd_source: "https://notion.so/..."    # set when the issue was generated from a
 
 If the caller passes only an issue ref, fetch via `gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,state,milestone,assignees`, parse the body sections, derive the spec fields — including `runtime_behavior_change`, derived from the `## Target Backend Environment` declaration per `derived-branch-plan` and authoritative over any caller assertion — then run gates. The parser lives in `lisa-github-read-issue` (composition).
 
+## Standalone use, against an item that already exists
+
+This is a supported entry point, not only an internal step of a caller flow.
+Point it at a live issue and it fetches and validates the stored state:
+
+```text
+Skill(lisa-github-validate-issue) with owner/repo#1234
+```
+
+Use it whenever the issue reached the tracker by some path other than
+`lisa-github-write-issue` — a team's own script, a workflow step, a cron, anything holding the
+credentials but no skill runtime. Those paths get neither the pre-write nor the
+post-write gate, and their own read-back substitutes for neither: a read-back
+proves the tracker stored what was sent, never that what was sent was any good.
+
+The gate definitions live here on purpose, so every caller picks up a change
+automatically. Running this skill by hand is the same gate the write path runs,
+not an approximation of it.
+
 ## Gates
 
 Gates are grouped into **Specification** (spec-only checks, no GitHub lookups) and **Feasibility** (requires GitHub lookups). The dry-run path may opt to run Specification gates only via `--spec-only`; the write path runs both.

package/plugins/lisa/skills/lisa-github-verify/SKILL.md

@@ -27,3 +27,20 @@ Pass through `lisa-github-validate-issue`'s structured output unchanged. Do not
 - This skill is read-only. It never edits the issue, posts comments, or changes labels.
 - If a gate fails, the recommendation is part of the validator's report; surface it as-is.
 - The Validation Journey check (S11) parses the `## Validation Journey` markdown section — same parser logic as `lisa-github-add-journey` and `lisa-github-journey`.
+
+## Comparison is semantic, never byte-exact
+
+Re-run the validator against the live issue. Do NOT compare the stored body
+against what was sent byte for byte.
+
+The reason is measured rather than theoretical. Trackers normalize markdown on
+write: `-` bullets become `*`, a bare URL is wrapped as `[url](<url>)`, bold
+emphasis is re-segmented around inline code spans. All lossless, all
+rendering-identical, and all of it makes a byte comparator report failure on a
+write that was completely fine. A comparator that cannot tell vendor
+normalization from corruption fails on healthy writes and trains its reader to
+ignore it, which costs more than the check was ever worth.
+
+Compare meaning: run `lisa-github-validate-issue` against the stored item and let the gates
+decide. Where a single field must be compared directly, normalize both sides
+first.

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

@@ -12,6 +12,41 @@ This skill is the GitHub counterpart of `lisa-jira-write-ticket`. The two skills
 
 Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
 
+## Writing by another path? The gates still apply
+
+A team that talks to its tracker through its own script is doing a normal
+thing — the script usually owns the credential plumbing, and Lisa neither
+controls nor wants to control it. What that script does NOT get is either half
+of this skill's quality gate, and nothing about the write says so.
+
+**A read-back is not the missing check.** A bespoke path almost always re-reads
+the issue after writing and confirms the tracker stored what was sent. That is
+worth doing and it is not this. It proves TRANSPORT: the API accepted the
+payload and the field values round-tripped. It cannot fail for the reason these
+gates exist, because it never looks at whether what was sent was any good — a
+issue with no acceptance criteria, no parent, and a human decision left sitting
+in the middle of it round-trips perfectly. That is the dangerous half of the
+shape: a failing control gets investigated, a misread one gets trusted.
+
+So a write by any other path still owes both phases, and both run standalone
+against an item that already exists:
+
+| Phase | Skill | What it costs you |
+|---|---|---|
+| Pre-write validate | `lisa-github-validate-issue` | Run it on the draft before you send it |
+| Post-write verify | `lisa-github-verify` | Run it on the live issue after you send it |
+
+```text
+Skill(lisa-github-validate-issue) with the draft issue, or with a reference to a live one
+Skill(lisa-github-verify) with owner/repo#1234
+```
+
+**These are plugin-resident skills invoked through the Skill tool.** They are
+not shell scripts and will not appear in any repository's `scripts/` directory,
+including yours. An agent that searches the repo it is standing in, finds
+nothing, and concludes the capability is absent has made the one mistake that
+turns a local script from the convenient option into the only one.
+
 ## Prerequisites
 
 - `gh` CLI installed and authenticated (`gh auth status` must succeed). The skill never falls back to a different transport — if `gh` is unauthenticated, stop and surface the auth error.

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

@@ -68,6 +68,25 @@ prd_source: "https://notion.so/..."    # set when the ticket was generated from
 
 If the caller passes only a ticket key, fetch the ticket via `lisa-atlassian-access` `operation: read-ticket key: <KEY>`, derive the same fields from the fetched data — including `runtime_behavior_change` (derived from the `Target Backend Environment` declaration per `derived-branch-plan`, and authoritative over any caller assertion), `build_ready` (label set contains the resolved `READY_ROLE` — merged `jira.workflow.ready`, default `status:ready` — never a hard-coded label) and `child_refs` (sub-tasks plus `is blocked by` parentage, resolved as in `lisa-jira-read-ticket`) so S15 can classify the ticket — then run gates.
 
+## Standalone use, against an item that already exists
+
+This is a supported entry point, not only an internal step of a caller flow.
+Point it at a live ticket and it fetches and validates the stored state:
+
+```text
+Skill(lisa-jira-validate-ticket) with PROJ-1234
+```
+
+Use it whenever the ticket reached the tracker by some path other than
+`lisa-jira-write-ticket` — a team's own script, a workflow step, a cron, anything holding the
+credentials but no skill runtime. Those paths get neither the pre-write nor the
+post-write gate, and their own read-back substitutes for neither: a read-back
+proves the tracker stored what was sent, never that what was sent was any good.
+
+The gate definitions live here on purpose, so every caller picks up a change
+automatically. Running this skill by hand is the same gate the write path runs,
+not an approximation of it.
+
 ## Gates
 
 Gates are grouped into **Specification** (spec-only checks, no JIRA lookups) and **Feasibility** (requires JIRA lookups). The dry-run path may opt to run Specification gates only; the write path runs both.

package/plugins/lisa/skills/lisa-jira-verify/SKILL.md

@@ -28,3 +28,20 @@ Pass through `lisa-jira-validate-ticket`'s structured output unchanged. Do not s
 - This skill is read-only. It never edits the ticket, posts comments, or changes status.
 - If a gate fails, the recommendation is part of the validator's report; surface it as-is.
 - Validation Journey checks (S11) historically required a parser script (`parse-plan.py`); the parser logic now lives inside `lisa-jira-validate-ticket` so this skill no longer shells out to it.
+
+## Comparison is semantic, never byte-exact
+
+Re-run the validator against the live ticket. Do NOT compare the stored body
+against what was sent byte for byte.
+
+The reason is measured rather than theoretical. Trackers normalize markdown on
+write: `-` bullets become `*`, a bare URL is wrapped as `[url](<url>)`, bold
+emphasis is re-segmented around inline code spans. All lossless, all
+rendering-identical, and all of it makes a byte comparator report failure on a
+write that was completely fine. A comparator that cannot tell vendor
+normalization from corruption fails on healthy writes and trains its reader to
+ignore it, which costs more than the check was ever worth.
+
+Compare meaning: run `lisa-jira-validate-ticket` against the stored item and let the gates
+decide. Where a single field must be compared directly, normalize both sides
+first.

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

@@ -12,6 +12,41 @@ Create or update a JIRA ticket with all required relationships, metadata, and qu
 
 Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
 
+## Writing by another path? The gates still apply
+
+A team that talks to its tracker through its own script is doing a normal
+thing — the script usually owns the credential plumbing, and Lisa neither
+controls nor wants to control it. What that script does NOT get is either half
+of this skill's quality gate, and nothing about the write says so.
+
+**A read-back is not the missing check.** A bespoke path almost always re-reads
+the ticket after writing and confirms the tracker stored what was sent. That is
+worth doing and it is not this. It proves TRANSPORT: the API accepted the
+payload and the field values round-tripped. It cannot fail for the reason these
+gates exist, because it never looks at whether what was sent was any good — a
+ticket with no acceptance criteria, no parent, and a human decision left sitting
+in the middle of it round-trips perfectly. That is the dangerous half of the
+shape: a failing control gets investigated, a misread one gets trusted.
+
+So a write by any other path still owes both phases, and both run standalone
+against an item that already exists:
+
+| Phase | Skill | What it costs you |
+|---|---|---|
+| Pre-write validate | `lisa-jira-validate-ticket` | Run it on the draft before you send it |
+| Post-write verify | `lisa-jira-verify` | Run it on the live ticket after you send it |
+
+```text
+Skill(lisa-jira-validate-ticket) with the draft ticket, or with a reference to a live one
+Skill(lisa-jira-verify) with PROJ-1234
+```
+
+**These are plugin-resident skills invoked through the Skill tool.** They are
+not shell scripts and will not appear in any repository's `scripts/` directory,
+including yours. An agent that searches the repo it is standing in, finds
+nothing, and concludes the capability is absent has made the one mistake that
+turns a local script from the convenient option into the only one.
+
 ## Phase 1 — Resolve Intent
 
 Determine from $ARGUMENTS and context whether this is a CREATE or UPDATE:

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

@@ -69,6 +69,25 @@ prd_source: "https://notion.so/..."    # set when the Issue was generated from a
 
 If the caller passes only an identifier, fetch the item via `lisa-linear-access operation: get-issue` (Issue) or `lisa-linear-access operation: get-project` (Project), derive the same fields from the fetched data — including `runtime_behavior_change` (derived from the `## Target Backend Environment` declaration per `derived-branch-plan`, and authoritative over any caller assertion), `build_ready` (the Issue's state is the configured `ready` state) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa-linear-read-issue`) so S15 can classify the item — then run gates.
 
+## Standalone use, against an item that already exists
+
+This is a supported entry point, not only an internal step of a caller flow.
+Point it at a live issue and it fetches and validates the stored state:
+
+```text
+Skill(lisa-linear-validate-issue) with ENG-1234
+```
+
+Use it whenever the issue reached the tracker by some path other than
+`lisa-linear-write-issue` — a team's own script, a workflow step, a cron, anything holding the
+credentials but no skill runtime. Those paths get neither the pre-write nor the
+post-write gate, and their own read-back substitutes for neither: a read-back
+proves the tracker stored what was sent, never that what was sent was any good.
+
+The gate definitions live here on purpose, so every caller picks up a change
+automatically. Running this skill by hand is the same gate the write path runs,
+not an approximation of it.
+
 ## Gates
 
 Gates are grouped into **Specification** (spec-only checks, no Linear lookups) and **Feasibility** (requires Linear lookups). The dry-run path may opt to run Specification gates only; the write path runs both.

package/plugins/lisa/skills/lisa-linear-verify/SKILL.md

@@ -49,3 +49,20 @@ If the verdict is `FAIL`, the caller should fix the item and re-run verify. Neve
 - Never write to Linear. Read-only.
 - Never short-circuit the validator. Always run the full gate set.
 - If `get_issue` / `get_project` returns an access error, surface it and exit — don't pretend the item is fine.
+
+## Comparison is semantic, never byte-exact
+
+Re-run the validator against the live issue. Do NOT compare the stored body
+against what was sent byte for byte.
+
+The reason is measured rather than theoretical. Trackers normalize markdown on
+write: `-` bullets become `*`, a bare URL is wrapped as `[url](<url>)`, bold
+emphasis is re-segmented around inline code spans. All lossless, all
+rendering-identical, and all of it makes a byte comparator report failure on a
+write that was completely fine. A comparator that cannot tell vendor
+normalization from corruption fails on healthy writes and trains its reader to
+ignore it, which costs more than the check was ever worth.
+
+Compare meaning: run `lisa-linear-validate-issue` against the stored item and let the gates
+decide. Where a single field must be compared directly, normalize both sides
+first.

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

@@ -33,6 +33,41 @@ Linear's data model maps Epic / Story / Sub-task to **different entity types**.
 
 The build lifecycle uses native **workflow states** (`Ready`, `In Progress`, `Blocked`, `On Dev`, `On Stg`, `Done`, plus an optional review state a project may bind), resolved per role from `linear.workflow` — see "Why Linear uses states, not labels" in `config-resolution`. A new **leaf** work unit is created in the configured `ready` state only on explicit `build_ready: true`; omitted or `false` leaves it in the team's default backlog state, and a container is never put in `ready` at all (see the Build-ready control input below).
 
+## Writing by another path? The gates still apply
+
+A team that talks to its tracker through its own script is doing a normal
+thing — the script usually owns the credential plumbing, and Lisa neither
+controls nor wants to control it. What that script does NOT get is either half
+of this skill's quality gate, and nothing about the write says so.
+
+**A read-back is not the missing check.** A bespoke path almost always re-reads
+the issue after writing and confirms the tracker stored what was sent. That is
+worth doing and it is not this. It proves TRANSPORT: the API accepted the
+payload and the field values round-tripped. It cannot fail for the reason these
+gates exist, because it never looks at whether what was sent was any good — a
+issue with no acceptance criteria, no parent, and a human decision left sitting
+in the middle of it round-trips perfectly. That is the dangerous half of the
+shape: a failing control gets investigated, a misread one gets trusted.
+
+So a write by any other path still owes both phases, and both run standalone
+against an item that already exists:
+
+| Phase | Skill | What it costs you |
+|---|---|---|
+| Pre-write validate | `lisa-linear-validate-issue` | Run it on the draft before you send it |
+| Post-write verify | `lisa-linear-verify` | Run it on the live issue after you send it |
+
+```text
+Skill(lisa-linear-validate-issue) with the draft issue, or with a reference to a live one
+Skill(lisa-linear-verify) with ENG-1234
+```
+
+**These are plugin-resident skills invoked through the Skill tool.** They are
+not shell scripts and will not appear in any repository's `scripts/` directory,
+including yours. An agent that searches the repo it is standing in, finds
+nothing, and concludes the capability is absent has made the one mistake that
+turns a local script from the convenient option into the only one.
+
 ## Phase 1 — Resolve Intent
 
 Determine from `$ARGUMENTS` and context whether this is a CREATE or UPDATE:

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/skills/lisa-github-validate-issue/SKILL.md

@@ -71,6 +71,25 @@ prd_source: "https://notion.so/..."    # set when the issue was generated from a
 
 If the caller passes only an issue ref, fetch via `gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,state,milestone,assignees`, parse the body sections, derive the spec fields — including `runtime_behavior_change`, derived from the `## Target Backend Environment` declaration per `derived-branch-plan` and authoritative over any caller assertion — then run gates. The parser lives in `lisa-github-read-issue` (composition).
 
+## Standalone use, against an item that already exists
+
+This is a supported entry point, not only an internal step of a caller flow.
+Point it at a live issue and it fetches and validates the stored state:
+
+```text
+Skill(lisa-github-validate-issue) with owner/repo#1234
+```
+
+Use it whenever the issue reached the tracker by some path other than
+`lisa-github-write-issue` — a team's own script, a workflow step, a cron, anything holding the
+credentials but no skill runtime. Those paths get neither the pre-write nor the
+post-write gate, and their own read-back substitutes for neither: a read-back
+proves the tracker stored what was sent, never that what was sent was any good.
+
+The gate definitions live here on purpose, so every caller picks up a change
+automatically. Running this skill by hand is the same gate the write path runs,
+not an approximation of it.
+
 ## Gates
 
 Gates are grouped into **Specification** (spec-only checks, no GitHub lookups) and **Feasibility** (requires GitHub lookups). The dry-run path may opt to run Specification gates only via `--spec-only`; the write path runs both.