@codyswann/lisa 4.54.13 → 4.55.0

package/plugins/lisa-agy/skills/lisa-github-build-intake/SKILL.md

@@ -317,7 +317,12 @@ other gate's verdict — however conclusive — may promote an item a person par
    drift, and a drifted gate fails *silently*, by quietly ceasing to match. Do **not** re-implement
    the test here, and do **not** key it on `reason=`: markers in the wild carry no `reason=` key at
    all and sit anywhere in the body, so a structured parse would miss them while appearing to work
-   on every item that happens to have one.
+   on every item that happens to have one. **Pass the item's `comments` alongside its labels and
+   body.** A hold is ended by a release recorded in a comment, so a reader handed no comments cannot
+   see the discharge — it goes on holding an item whose question was answered weeks ago, which is
+   the defect this gate carried from the day it was written (CodySwannGT/lisa#3852). Omitting them
+   fails closed, and that is exactly why it is easy to miss: nothing breaks, the item simply never
+   comes back.
 2. **On `claimable: false` with reason `human-gate`, do not claim and do not dispatch.**
 3. **Reconcile the lane; do not merely skip.** Skipping alone leaves the item in `$READY`, re-judged
    and re-rejected every cycle forever and seen by nothing — `lisa-repair-intake` sweeps items that
@@ -329,14 +334,32 @@ other gate's verdict — however conclusive — may promote an item a person par
    already out of the lane and already marked yields no second mutation and no second comment. This
    is the same repair the leaf-only gate already performs for a ready item that must not be
    dispatched.
-4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
+4. **On `claimable: true` for an item that still carries a hold, RELEASE it — do not just proceed.**
+   The hold left durable state behind: the item is out of the queue and flagged as needing a person,
+   and answering the question does not undo either. Call
+   `planHumanGateRelease({ labels, body, comments, humanNeededLabel, readyLabel, lifecycleLabels, alreadyNotified })`
+   and apply exactly the actions it returns: remove the configured human-needed marker, add the
+   configured ready role back, and post `formatHumanGateReleaseNote()` once. It is the exact inverse
+   of step 3's planner and it refuses in both directions — an item still held plans nothing, and an
+   item never held plans nothing, so it can only ever un-do a hold and can never promote something on
+   its own. It is idempotent by state, so a second cycle over a released item yields no second
+   mutation and no second comment.
+
+   **Never edit the description to clear a hold.** The only body write available is a whole-body
+   replacement, so deleting one line means rewriting the whole record and hoping nothing was
+   dropped — the reason holds accumulated instead of being lifted. The hold note stays in the
+   description as history; the release is a comment beside it.
+5. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
    Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
    — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
    A rule that quietly declines to honour half the occurrences it sees reads exactly like a
-   rule that saw none, so the count is printed even when it is zero.
-5. **Continue to the next candidate.** A held item does not end the cycle.
+   rule that saw none, so the count is printed even when it is zero. Report what was RELEASED
+   beside it via `summarizeHumanGateReleases([...])`, printed even when it is zero: a release path
+   that has stopped working and a cycle with nothing to release read identically otherwise, which
+   is how a missing inverse stays missing.
+6. **Continue to the next candidate.** A held item does not end the cycle.
 
 
 #### 3a.0 Repo-scope gate (claim only current-repo issues)

package/plugins/lisa-agy/skills/lisa-github-prd-intake/SKILL.md

@@ -29,7 +29,7 @@ SHIPPED=$(node "$ROLE_RESOLVER" --role prd.shipped --vendor github --intent writ
 
 In prose below, the role names refer to the resolved labels: e.g. "the `ready` label" means whatever `github.labels.prd.ready` resolves to (default: `prd-ready`).
 
-This skill is the GitHub counterpart of `lisa-notion-prd-intake`, `lisa-confluence-prd-intake`, and `lisa-linear-prd-intake`. Phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **issue labels** (mirroring Linear's project labels and Confluence's page labels), (2) the fetch / update tools are the `gh` CLI, and (3) clarifying-question comments land directly on the source PRD issue (because GitHub Issues *do* have native comments — no sentinel issue required, unlike Linear). Keep all four skills behaviorally aligned: when changing intake logic, change them together.
+This skill is the GitHub counterpart of `lisa-notion-prd-intake`, `lisa-confluence-prd-intake`, and `lisa-linear-prd-intake`. Phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **issue labels** (mirroring Linear's project labels and Confluence's page labels), (2) the fetch / update tools are the `gh` CLI, and (3) clarifying-question comments land directly on the source PRD issue. Keep all four skills behaviorally aligned: when changing intake logic, change them together.
 
 The **PRD shipped rollup phase (3f)** transitions a `$TICKETED` PRD to `$SHIPPED` once all its generated top-level work is terminal, per the `prd-lifecycle-rollup` rule. This phase is GitHub-only here because its vendor surface (issue close + labels via `gh`) is GitHub-specific; the Linear / Confluence / Notion intake skills carry the **same** vendor-neutral rollup with their own surfaces (sibling sub-task #584, now landed). All four intake skills are behaviorally aligned across the rollup phase too — keep them in sync when changing rollup logic.
 

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

@@ -15,6 +15,28 @@ Run all organizational quality gates against an issue spec OR an existing issue.
 1. **An existing issue ref** (`org/repo#<number>` or `https://github.com/<org>/<repo>/issues/<number>`): fetch it and validate the live state. Use this for post-write checks.
 2. **A proposed issue spec** (YAML block, see schema below): validate as-is without touching GitHub. Use this for pre-write and dry-run checks.
 
+### Standalone entry point — validating an item written by another path
+
+Input form 1 is a **supported entry point in its own right**, not only an internal step of a
+caller flow. Point this skill at any existing item — however it was written, including by a
+bespoke script, a direct API or GraphQL call, or the vendor's own web UI — and it fetches the
+live state and runs the full gate set against it.
+
+Copy-pasteable, via the Skill tool:
+
+```text
+Skill(skill: "lisa-github-validate-issue", args: "CodySwannGT/lisa#3663")
+```
+
+where the argument is an issue ref such as `CodySwannGT/lisa#3663`, or the full issue URL. The report it returns is the same structured PASS/FAIL
+report the write path consumes, so a bespoke write path can discharge both the pre-write
+validate and the post-write verify obligation with it (see the bespoke-path section of
+`lisa-github-write-issue`).
+
+This skill is plugin-resident. It is invoked through the Skill tool and is **not** expected to
+appear in any repository's `scripts/` directory; not finding a shell script by this name is
+not evidence that the capability is absent.
+
 ### Spec schema
 
 Specs are passed as a fenced YAML block. Required keys depend on `issue_type`.

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

@@ -22,6 +22,20 @@ This indirection exists so the gate definitions live in exactly one place (`lisa
 
 Pass through `lisa-github-validate-issue`'s structured output unchanged. Do not summarize or paraphrase — downstream callers (e.g. `lisa-github-agent`'s pre-flight gate) parse the gate lines.
 
+## Comparison semantics — semantic, never byte-exact
+
+Verification here re-runs `lisa-github-validate-issue` against the live issue. It does **not** compare the
+stored body against the sent body byte for byte, and it must never drift to doing so.
+
+GitHub normalizes markdown on write. Observed normalizations include rewriting `-` bullets
+as `*`, wrapping a bare URL as an explicit link, and re-segmenting bold emphasis around
+inline code spans — all lossless, all rendering-identical. **A byte-exact comparator cannot
+distinguish vendor markdown normalization from corruption**, so it reports failure on
+perfectly healthy writes and trains its reader to ignore it (CodySwannGT/lisa#3663).
+
+Any comparison of tracker-normalized rich text is therefore semantic, or
+normalize-then-compare. Byte-exact comparison of such text is forbidden.
+
 ## Notes
 
 - This skill is read-only. It never edits the issue, posts comments, or changes labels.

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

@@ -322,6 +322,17 @@ person scanning a board and to any path that has not yet been routed through the
 If the label does not exist in the tracker, create it, or record that it could not be applied and
 proceed — the marker still holds. Never file the label *instead of* the marker.
 
+**Write a `reason=` the release can name.** The hold's reason is not decoration: a hold ends when a
+`[lisa-human-gate-release]` comment repeating that same `reason=` is recorded on the item, and the
+next intake sweep then takes the marker label off and puts the item back in the build-ready role on
+its own. Matching is per-reason so that a hold declared *after* an earlier release is not born
+discharged. A keyless hold is legal and is discharged by a keyless release; a hold whose reason is a
+paragraph is legal and nobody will reproduce it. Prefer a short slug the person answering it can
+retype. Do **not** instruct anyone to delete the marker from the description to lift the hold — the
+only body write available is a whole-body replacement, so that asks them to rewrite the whole record
+to clear one line, which is why answered holds accumulated instead of being lifted
+(CodySwannGT/lisa#3852). The marker stays as history; the release is recorded beside it.
+
 If a leaf arrives with `build_ready` omitted or `false` **and** no `human_gate`, do not create it: report the incomplete handoff and name both ways to resolve it (`build_ready: true`, or a `human_gate` reason). Containers are exempt — their state rolls up from children, so they need neither.
 
 **The container exemption is executable, not prose.** It used to live only in the sentence above,
@@ -445,6 +456,46 @@ The mapping below is the single source of truth for how JIRA concepts translate
 | Worklog | Comments (no native time tracking) |
 | Triage marker | Label `claude-triaged-<repo>` |
 
+## Writing by a bespoke path (your own script, direct API or GraphQL)
+
+Nothing here stops a consumer from writing to GitHub through `gh issue create` directly, the GitHub REST or GraphQL API, or your own script, and nothing should
+try to — a script that owns the credential plumbing is often the only practical transport.
+**The transport is not the gate.** A bespoke write path still owes both halves of the quality
+gate this skill runs, and owes them explicitly, because no phase of this flow will ever run
+for it.
+
+A bespoke script's own read-back does not discharge either obligation. Re-reading the issue
+and confirming GitHub stored what was sent **proves transport, not quality**: it shows the
+fields round-tripped and says nothing about whether what was sent clears a single gate. An
+agent that reads `VERIFIED` out of such a script has been told the issue was checked when it
+was not. Measured once, on one issue, on 2026-09-03 (CodySwannGT/lisa#3663): a local
+script's read-back was clean on every field, and the issue then failed gates S5, S9 and S18
+when the validator was run against it by hand.
+
+What a bespoke write path still owes — the same two checks, invoked by hand:
+
+1. **Pre-write validate**, the obligation Phase 5.5 discharges here. Invoke `lisa-github-validate-issue` via
+   the Skill tool with the proposed spec as a YAML block **before** writing. Never write on a
+   `FAIL` verdict.
+2. **Post-write verify**, the obligation Phase 7 discharges here. Invoke `lisa-github-verify` via the
+   Skill tool with the identifier of the issue you just wrote — or `lisa-github-validate-issue` directly in
+   identifier mode, which fetches and validates the live state. Never report success on a
+   `FAIL` verdict.
+
+Both run standalone against an existing live issue; `lisa-github-validate-issue` documents the copy-pasteable
+invocation under its standalone entry point.
+
+**Three outcomes, never two.** `PASS`, `FAIL` and *could not validate* are distinct results.
+If the validator did not run to a verdict — the skill was unavailable, a credential was
+missing, the issue could not be fetched — that is **not** a pass. Report it as unvalidated and
+say why. Collapsing "could not validate" into "validated" is the same misreading as trusting
+a read-back.
+
+**These are skills, not scripts.** `lisa-github-validate-issue` and `lisa-github-verify` are plugin-resident and invoked
+through the Skill tool. They are **not** expected to appear in any repository's `scripts/`
+directory, and their absence from one is not evidence that the capability is missing —
+searching the repository you happen to be standing in is the wrong search.
+
 ## Rules
 
 - Never create a non-bug issue without a parent Epic / Story (sub-issue link).

package/plugins/lisa-agy/skills/lisa-intake/SKILL.md

@@ -107,7 +107,7 @@ The single-item skills (`lisa-plan`, `lisa-implement`) and the per-vendor batch
 4. **Process the first eligible Ready item only** (claim-first ordering for idempotency):
    - Notion PRDs → `lisa-notion-prd-intake` handles per-item: claim (Status=In Review), dry-run validate, branch to Blocked or Ticketed, coverage audit
    - Confluence PRDs → `lisa-confluence-prd-intake` handles per-item: claim (relabel to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed`, coverage audit
-   - Linear PRDs → `lisa-linear-prd-intake` handles per-item: claim (relabel project to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed` (with a sentinel feedback issue under each project hosting clarifying-question comments), coverage audit
+   - Linear PRDs → `lisa-linear-prd-intake` handles per-item: claim (relabel project to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed` (clarifying-question comments posted on the project itself), coverage audit
    - GitHub PRDs → `lisa-github-prd-intake` handles per-item: claim (relabel issue to `prd-in-review`), dry-run validate, branch to `prd-blocked` or `prd-ticketed` (with clarifying-question comments posted directly on the PRD issue), coverage audit
    - JIRA tickets → `lisa-jira-build-intake` handles per-item: claim, dispatch to `lisa-jira-agent`, transition to On Dev on success
    - GitHub build issues (when `tracker = github`) → `lisa-tracker-build-intake` → `lisa-github-build-intake` handles per-item: optional ready-queue assignee filtering, claim (relabel to `status:in-progress`), dispatch to `lisa-github-agent`, relabel to `status:on-dev` on success

package/plugins/lisa-agy/skills/lisa-jira-build-intake/SKILL.md

@@ -222,7 +222,12 @@ other gate's verdict — however conclusive — may promote an item a person par
    drift, and a drifted gate fails *silently*, by quietly ceasing to match. Do **not** re-implement
    the test here, and do **not** key it on `reason=`: markers in the wild carry no `reason=` key at
    all and sit anywhere in the body, so a structured parse would miss them while appearing to work
-   on every item that happens to have one.
+   on every item that happens to have one. **Pass the item's `comments` alongside its labels and
+   body.** A hold is ended by a release recorded in a comment, so a reader handed no comments cannot
+   see the discharge — it goes on holding an item whose question was answered weeks ago, which is
+   the defect this gate carried from the day it was written (CodySwannGT/lisa#3852). Omitting them
+   fails closed, and that is exactly why it is easy to miss: nothing breaks, the item simply never
+   comes back.
 2. **On `claimable: false` with reason `human-gate`, do not claim and do not dispatch.**
 3. **Reconcile the lane; do not merely skip.** Skipping alone leaves the item in `$READY`, re-judged
    and re-rejected every cycle forever and seen by nothing — `lisa-repair-intake` sweeps items that
@@ -234,14 +239,32 @@ other gate's verdict — however conclusive — may promote an item a person par
    already out of the lane and already marked yields no second mutation and no second comment. This
    is the same repair the leaf-only gate already performs for a ready item that must not be
    dispatched.
-4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
+4. **On `claimable: true` for an item that still carries a hold, RELEASE it — do not just proceed.**
+   The hold left durable state behind: the item is out of the queue and flagged as needing a person,
+   and answering the question does not undo either. Call
+   `planHumanGateRelease({ labels, body, comments, humanNeededLabel, readyLabel, lifecycleLabels, alreadyNotified })`
+   and apply exactly the actions it returns: remove the configured human-needed marker, add the
+   configured ready role back, and post `formatHumanGateReleaseNote()` once. It is the exact inverse
+   of step 3's planner and it refuses in both directions — an item still held plans nothing, and an
+   item never held plans nothing, so it can only ever un-do a hold and can never promote something on
+   its own. It is idempotent by state, so a second cycle over a released item yields no second
+   mutation and no second comment.
+
+   **Never edit the description to clear a hold.** The only body write available is a whole-body
+   replacement, so deleting one line means rewriting the whole record and hoping nothing was
+   dropped — the reason holds accumulated instead of being lifted. The hold note stays in the
+   description as history; the release is a comment beside it.
+5. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
    Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
    — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
    A rule that quietly declines to honour half the occurrences it sees reads exactly like a
-   rule that saw none, so the count is printed even when it is zero.
-5. **Continue to the next candidate.** A held item does not end the cycle.
+   rule that saw none, so the count is printed even when it is zero. Report what was RELEASED
+   beside it via `summarizeHumanGateReleases([...])`, printed even when it is zero: a release path
+   that has stopped working and a cycle with nothing to release read identically otherwise, which
+   is how a missing inverse stays missing.
+6. **Continue to the next candidate.** A held item does not end the cycle.
 
 
 #### 3a.0 Repo-scope gate (claim only current-repo tickets)

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

@@ -17,6 +17,28 @@ Run all organizational quality gates against a ticket spec OR an existing ticket
 1. **An existing ticket key** (e.g. `PROJ-1234`): fetch it and validate the live state. Use this for post-write checks.
 2. **A proposed ticket spec** (YAML block, see schema below): validate as-is without touching JIRA. Use this for pre-write and dry-run checks.
 
+### Standalone entry point — validating an item written by another path
+
+Input form 1 is a **supported entry point in its own right**, not only an internal step of a
+caller flow. Point this skill at any existing item — however it was written, including by a
+bespoke script, a direct API or GraphQL call, or the vendor's own web UI — and it fetches the
+live state and runs the full gate set against it.
+
+Copy-pasteable, via the Skill tool:
+
+```text
+Skill(skill: "lisa-jira-validate-ticket", args: "PROJ-1234")
+```
+
+where the argument is a ticket key such as `PROJ-1234`. The report it returns is the same structured PASS/FAIL
+report the write path consumes, so a bespoke write path can discharge both the pre-write
+validate and the post-write verify obligation with it (see the bespoke-path section of
+`lisa-jira-write-ticket`).
+
+This skill is plugin-resident. It is invoked through the Skill tool and is **not** expected to
+appear in any repository's `scripts/` directory; not finding a shell script by this name is
+not evidence that the capability is absent.
+
 ### Spec schema
 
 Specs are passed as a fenced YAML block. Required keys depend on `issue_type`.

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

@@ -23,6 +23,20 @@ This indirection exists so the gate definitions live in exactly one place (`lisa
 
 Pass through `lisa-jira-validate-ticket`'s structured output unchanged. Do not summarize or paraphrase — downstream callers (e.g. `lisa-jira-agent`'s pre-flight gate) parse the gate lines.
 
+## Comparison semantics — semantic, never byte-exact
+
+Verification here re-runs `lisa-jira-validate-ticket` against the live ticket. It does **not** compare the
+stored body against the sent body byte for byte, and it must never drift to doing so.
+
+JIRA normalizes markdown on write. Observed normalizations include rewriting `-` bullets
+as `*`, wrapping a bare URL as an explicit link, and re-segmenting bold emphasis around
+inline code spans — all lossless, all rendering-identical. **A byte-exact comparator cannot
+distinguish vendor markdown normalization from corruption**, so it reports failure on
+perfectly healthy writes and trains its reader to ignore it (CodySwannGT/lisa#3663).
+
+Any comparison of tracker-normalized rich text is therefore semantic, or
+normalize-then-compare. Byte-exact comparison of such text is forbidden.
+
 ## Notes
 
 - This skill is read-only. It never edits the ticket, posts comments, or changes status.

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

@@ -307,6 +307,17 @@ person scanning a board and to any path that has not yet been routed through the
 If the label does not exist in the tracker, create it, or record that it could not be applied and
 proceed — the marker still holds. Never file the label *instead of* the marker.
 
+**Write a `reason=` the release can name.** The hold's reason is not decoration: a hold ends when a
+`[lisa-human-gate-release]` comment repeating that same `reason=` is recorded on the item, and the
+next intake sweep then takes the marker label off and puts the item back in the build-ready role on
+its own. Matching is per-reason so that a hold declared *after* an earlier release is not born
+discharged. A keyless hold is legal and is discharged by a keyless release; a hold whose reason is a
+paragraph is legal and nobody will reproduce it. Prefer a short slug the person answering it can
+retype. Do **not** instruct anyone to delete the marker from the description to lift the hold — the
+only body write available is a whole-body replacement, so that asks them to rewrite the whole record
+to clear one line, which is why answered holds accumulated instead of being lifted
+(CodySwannGT/lisa#3852). The marker stays as history; the release is recorded beside it.
+
 If a leaf arrives with `build_ready` omitted or `false` **and** no `human_gate`, do not create it: report the incomplete handoff and name both ways to resolve it (`build_ready: true`, or a `human_gate` reason). Containers are exempt — their status rolls up from children, so they need neither.
 
 ## Phase 5.5 — Validate (Pre-write Gate)
@@ -355,6 +366,46 @@ Post a creation comment via `lisa-atlassian-access` `operation: comment key: <K>
 
 Skip this step only on UPDATE when no material change was made.
 
+## Writing by a bespoke path (your own script, direct API or GraphQL)
+
+Nothing here stops a consumer from writing to JIRA through the JIRA REST API directly, `acli`, or your own script, and nothing should
+try to — a script that owns the credential plumbing is often the only practical transport.
+**The transport is not the gate.** A bespoke write path still owes both halves of the quality
+gate this skill runs, and owes them explicitly, because no phase of this flow will ever run
+for it.
+
+A bespoke script's own read-back does not discharge either obligation. Re-reading the ticket
+and confirming JIRA stored what was sent **proves transport, not quality**: it shows the
+fields round-tripped and says nothing about whether what was sent clears a single gate. An
+agent that reads `VERIFIED` out of such a script has been told the ticket was checked when it
+was not. Measured once, on one ticket, on 2026-09-03 (CodySwannGT/lisa#3663): a local
+script's read-back was clean on every field, and the ticket then failed gates S5, S9 and S18
+when the validator was run against it by hand.
+
+What a bespoke write path still owes — the same two checks, invoked by hand:
+
+1. **Pre-write validate**, the obligation Phase 5.5 discharges here. Invoke `lisa-jira-validate-ticket` via
+   the Skill tool with the proposed spec as a YAML block **before** writing. Never write on a
+   `FAIL` verdict.
+2. **Post-write verify**, the obligation Phase 7 discharges here. Invoke `lisa-jira-verify` via the
+   Skill tool with the identifier of the ticket you just wrote — or `lisa-jira-validate-ticket` directly in
+   identifier mode, which fetches and validates the live state. Never report success on a
+   `FAIL` verdict.
+
+Both run standalone against an existing live ticket; `lisa-jira-validate-ticket` documents the copy-pasteable
+invocation under its standalone entry point.
+
+**Three outcomes, never two.** `PASS`, `FAIL` and *could not validate* are distinct results.
+If the validator did not run to a verdict — the skill was unavailable, a credential was
+missing, the ticket could not be fetched — that is **not** a pass. Report it as unvalidated and
+say why. Collapsing "could not validate" into "validated" is the same misreading as trusting
+a read-back.
+
+**These are skills, not scripts.** `lisa-jira-validate-ticket` and `lisa-jira-verify` are plugin-resident and invoked
+through the Skill tool. They are **not** expected to appear in any repository's `scripts/`
+directory, and their absence from one is not evidence that the capability is missing —
+searching the repository you happen to be standing in is the wrong search.
+
 ## Rules
 
 - Never create a non-bug ticket without an epic parent.

package/plugins/lisa-agy/skills/lisa-linear-access/SKILL.md

@@ -23,8 +23,8 @@ operation: get-issue id:<ID>
 operation: save-issue payload:{...} [lifecycle_role:<ROLE>] [env:<KEY>]
 operation: list-workflow-states team:<ID>
 operation: create-workflow-state payload:{...}
-operation: list-comments issue_id:<ID>
-operation: save-comment issue_id:<ID> body:"..."
+operation: list-comments (issue_id:<ID> | project_id:<ID>)
+operation: save-comment (issue_id:<ID> | project_id:<ID>) body:"..."
 operation: history id:<ID>
 operation: list-issue-labels [team:<ID>]
 operation: create-issue-label payload:{...}
@@ -294,6 +294,55 @@ Set `isTeamDefault` per node by comparing `node.id` against
 the team's default, resolve the default through the team record and join on `id`
 the same way.
 
+## `save-comment` / `list-comments` — an Issue **or** a Project
+
+Both comment operations take **either** `issue_id:` or `project_id:`. Exactly one
+is required; passing both, or neither, is refused naming the operation.
+
+Linear treats a comment's target as one field on the same input type, so the
+project form is not a second mechanism — it is the same mutation with a
+different anchor. Direct introspection of `https://api.linear.app/graphql`:
+`CommentCreateInput` accepts `issueId`, `projectId`, `projectUpdateId`,
+`documentContentId`, and `parentId`, and the `Project` type exposes
+`Project.comments`. Neither is beta and neither needs a special scope.
+
+```graphql
+# save-comment — the anchor field is chosen by which id the caller passed.
+mutation($input:CommentCreateInput!){
+  commentCreate(input:$input){ success comment{ id url createdAt } }
+}
+```
+
+Build `$input` as `{ issueId: <id>, body: <body> }` for the Issue form and
+`{ projectId: <id>, body: <body> }` for the Project form. Nothing else differs —
+same mutation, same result shape, same error handling.
+
+```graphql
+# list-comments project_id:<ID> — page via pageInfo so a long-lived PRD's
+# feedback history never silently truncates.
+query($id:String!){
+  project(id:$id){
+    comments(first:100){
+      pageInfo{ hasNextPage endCursor }
+      nodes{ id body createdAt url user{ name } }
+    }
+  }
+}
+```
+
+The Issue form reads through `issue(id:$id){ comments{...} }` with the identical
+node shape, so a caller consumes one result format for either anchor.
+
+**Substrate.** The Linear MCP exposes comments on Issues only, so the
+`project_id` form resolves solely through the tier-1 `LINEAR_API_KEY` + GraphQL
+substrate — the same restriction `history` carries, and for the same reason.
+That is not a gap in Linear: the precedence contract already puts GraphQL ahead
+of the MCP, so the preferred substrate has always been able to do this. Only
+this wrapper could not, which is what made callers fabricate an Issue to hold a
+Project's comments. If tier 1 is unavailable, fail with the layer's standard
+`Error:` result naming `save-comment project_id` — do **not** silently degrade
+into creating an Issue to comment on.
+
 ## `history` — transition history (read-only)
 
 `history id:<ID>` returns an Issue's ordered past state changes — the raw
@@ -371,6 +420,10 @@ query($id:String!){
 - Missing token plus missing MCP is a hard failure naming `LINEAR_API_KEY`.
 - Mutations send only the fields being changed, matching existing Linear skill
   guidance that `save_*` style updates should not clobber unrelated fields.
+- A comment anchors to exactly one target. `save-comment` and `list-comments`
+  take `issue_id` **or** `project_id`, never both and never neither. A caller
+  that wants to comment on a Project passes `project_id` — it never creates an
+  Issue to hold the comment, and this layer never creates one on its behalf.
 - Every workflow-state write is resolved by
   `scripts/linear-state-write-target.mjs` from a declared `lifecycle_role`,
   before either transport. The ID dispatched is the ID that script returned —

package/plugins/lisa-agy/skills/lisa-linear-build-intake/SKILL.md

@@ -216,7 +216,12 @@ other gate's verdict — however conclusive — may promote an item a person par
    drift, and a drifted gate fails *silently*, by quietly ceasing to match. Do **not** re-implement
    the test here, and do **not** key it on `reason=`: markers in the wild carry no `reason=` key at
    all and sit anywhere in the body, so a structured parse would miss them while appearing to work
-   on every item that happens to have one.
+   on every item that happens to have one. **Pass the item's `comments` alongside its labels and
+   body.** A hold is ended by a release recorded in a comment, so a reader handed no comments cannot
+   see the discharge — it goes on holding an item whose question was answered weeks ago, which is
+   the defect this gate carried from the day it was written (CodySwannGT/lisa#3852). Omitting them
+   fails closed, and that is exactly why it is easy to miss: nothing breaks, the item simply never
+   comes back.
 2. **On `claimable: false` with reason `human-gate`, do not claim and do not dispatch.**
 3. **Reconcile the lane; do not merely skip.** Skipping alone leaves the item in `$READY`, re-judged
    and re-rejected every cycle forever and seen by nothing — `lisa-repair-intake` sweeps items that
@@ -228,14 +233,32 @@ other gate's verdict — however conclusive — may promote an item a person par
    already out of the lane and already marked yields no second mutation and no second comment. This
    is the same repair the leaf-only gate already performs for a ready item that must not be
    dispatched.
-4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
+4. **On `claimable: true` for an item that still carries a hold, RELEASE it — do not just proceed.**
+   The hold left durable state behind: the item is out of the queue and flagged as needing a person,
+   and answering the question does not undo either. Call
+   `planHumanGateRelease({ labels, body, comments, humanNeededLabel, readyLabel, lifecycleLabels, alreadyNotified })`
+   and apply exactly the actions it returns: remove the configured human-needed marker, add the
+   configured ready role back, and post `formatHumanGateReleaseNote()` once. It is the exact inverse
+   of step 3's planner and it refuses in both directions — an item still held plans nothing, and an
+   item never held plans nothing, so it can only ever un-do a hold and can never promote something on
+   its own. It is idempotent by state, so a second cycle over a released item yields no second
+   mutation and no second comment.
+
+   **Never edit the description to clear a hold.** The only body write available is a whole-body
+   replacement, so deleting one line means rewriting the whole record and hoping nothing was
+   dropped — the reason holds accumulated instead of being lifted. The hold note stays in the
+   description as history; the release is a comment beside it.
+5. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
    Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
    — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
    A rule that quietly declines to honour half the occurrences it sees reads exactly like a
-   rule that saw none, so the count is printed even when it is zero.
-5. **Continue to the next candidate.** A held item does not end the cycle.
+   rule that saw none, so the count is printed even when it is zero. Report what was RELEASED
+   beside it via `summarizeHumanGateReleases([...])`, printed even when it is zero: a release path
+   that has stopped working and a cycle with nothing to release read identically otherwise, which
+   is how a missing inverse stays missing.
+6. **Continue to the next candidate.** A held item does not end the cycle.
 
 
 #### 3a.0 Repo-scope gate (claim only current-repo Issues)