@codyswann/lisa 4.55.2 → 4.55.3

package/plugins/lisa-agy/hooks/guard-dedupe.bash

@@ -1,3 +1,6 @@
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+
 # shellcheck shell=bash
 # Evaluate a dual-channel guard once per tool call, without de-registering it.
 #
@@ -51,12 +54,9 @@
 #      refusal reaching the agent without the message that explains it. On a
 #      refusal every channel evaluates and speaks exactly as it does today.
 #
-# COST ON THE PATH THAT GETS NO BENEFIT. A host with one channel must not pay
-# for a mechanism it cannot use. The channel check is builtins only — one small
-# file read, no subshell, no fork — and returns before the digest is computed
-# unless a second channel has actually been seen. The digest, and the one `stat`
-# that feeds it the per-call discriminator, are reached only where a second
-# channel is live, which is exactly where they are repaid.
+# State ownership, modes and ancestry are verified before channel discovery.
+# After that validation the channel check uses only builtins, and returns
+# before digesting code or sizing the transcript unless another channel is live.
 
 # Key this guard would memoise under, once computed. Empty means "record
 # nothing on exit".
@@ -74,14 +74,25 @@ lisa_guard_memo_ready=0
 # Digest tool for the memo key, resolved once. Empty disables the memo.
 lisa_guard_memo_digest_tool=""
 
-# Whether a directory is a real directory this user owns, and not a symlink —
-# builtins only, so this costs no process.
-#
-# `-O` is the load-bearing test: a memo planted by another user would suppress a
-# refusal, so a directory this user does not own is never used. The dispatcher
-# validates the whole parent chain before exporting `LISA_GUARD_MEMO_DIR`; this
-# re-checks the leaf rather than trusting the environment variable, because an
-# exported path is an input like any other.
+# Read ownership and all permission bits without accepting output from a
+# failed platform-specific stat invocation.
+# $1 - directory; sets lisa_guard_memo_owner and lisa_guard_memo_mode
+lisa_guard_memo_stat() {
+  local facts=""
+  facts="$(stat -c '%u %a' "$1" 2>/dev/null)" ||
+    facts="$(stat -f '%u %p' "$1" 2>/dev/null)" || return 1
+  lisa_guard_memo_owner="${facts%% *}"
+  lisa_guard_memo_mode="${facts#* }"
+  case "$lisa_guard_memo_owner:$lisa_guard_memo_mode" in
+    *[!0-9:]* | :* | *:) return 1 ;;
+  esac
+  case "$lisa_guard_memo_mode" in *[!0-7]*) return 1 ;; esac
+  lisa_guard_memo_mode=$((8#$lisa_guard_memo_mode & 8#7777))
+}
+
+# Memo leaves must be private even when a sticky shared temp ancestor is safe.
+# Ownership alone allows another local account to plant a session/allow file
+# in an owned but group- or world-writable directory.
 #
 # $1 - candidate directory
 lisa_guard_memo_dir_usable() {
@@ -89,23 +100,42 @@ lisa_guard_memo_dir_usable() {
   [ -d "$1" ] || return 1
   [ ! -L "$1" ] || return 1
   [ -O "$1" ] || return 1
+  lisa_guard_memo_stat "$1" || return 1
+  [ $((lisa_guard_memo_mode & 8#0022)) -eq 0 ]
+}
+
+# Resolve parents physically and verify every ancestor. Plugin hooks do not
+# inherit the dispatcher's trust walk, and exported paths are still inputs.
+# $1 - candidate memo base; sets lisa_guard_memo_base only on success
+lisa_guard_memo_trust_base() {
+  lisa_guard_memo_dir_usable "$1" || return 1
+  local physical=""
+  physical="$(cd "$1" 2>/dev/null && pwd -P)" || return 1
+  local current="$physical"
+  while :; do
+    lisa_guard_memo_stat "$current" || return 1
+    [ "$lisa_guard_memo_owner" = 0 ] || [ -O "$current" ] || return 1
+    if [ $((lisa_guard_memo_mode & 8#0022)) -ne 0 ] &&
+      [ $((lisa_guard_memo_mode & 8#1000)) -eq 0 ]; then
+      return 1
+    fi
+    [ "$current" != / ] || break
+    current="${current%/*}"
+    [ -n "$current" ] || current=/
+  done
+  lisa_guard_memo_base="$physical"
 }
 
 # Establish the memo base directory.
 #
-# Preferred source is `LISA_GUARD_MEMO_DIR`, exported by the dispatcher, which
-# has already resolved `TMPDIR` physically and walked every parent for ownership
-# and mode. Guards it spawns therefore pay nothing for that walk. A guard
-# reached by the plugin channel has no such parent, so it creates the directory
-# itself under `TMPDIR` — private by umask, and used only when this user owns
-# it. If neither works the memo is unavailable and every guard evaluates, which
-# is today's behaviour.
+# Preferred source is `LISA_GUARD_MEMO_DIR`, exported by the dispatcher. Both
+# this input and the plugin channel's TMPDIR fallback receive the same trust
+# checks. Missing state is created privately; untrusted state disables memo use.
 lisa_guard_memo_resolve_base() {
   [ -z "$lisa_guard_memo_base" ] || return 0
 
   local candidate="${LISA_GUARD_MEMO_DIR:-}"
-  if lisa_guard_memo_dir_usable "$candidate"; then
-    lisa_guard_memo_base="$candidate"
+  if lisa_guard_memo_trust_base "$candidate"; then
     return 0
   fi
 
@@ -118,8 +148,7 @@ lisa_guard_memo_resolve_base() {
   if [ ! -e "$candidate" ] && [ ! -L "$candidate" ]; then
     (umask 077 && mkdir -p "$candidate") 2>/dev/null || true
   fi
-  if lisa_guard_memo_dir_usable "$candidate"; then
-    lisa_guard_memo_base="$candidate"
+  if lisa_guard_memo_trust_base "$candidate"; then
     return 0
   fi
   return 1
@@ -165,6 +194,7 @@ lisa_guard_memo_sweep() {
 #
 # $1 - guard name, used only to name the memo file
 # $2 - the raw tool payload this guard was handed on stdin
+# Remaining arguments - files containing delegated verdict code
 lisa_guard_dedupe() {
   local guard_name="${1:-}"
   local payload="${2:-}"
@@ -194,8 +224,7 @@ lisa_guard_dedupe() {
       fresh_session=1
     fi
   fi
-  [ -d "$session_dir" ] || return 0
-  [ ! -L "$session_dir" ] || return 0
+  lisa_guard_memo_dir_usable "$session_dir" || return 0
 
   # Swept once, by the process that created the session directory, so a
   # long-lived machine does not accumulate memo state. Off the hot path by
@@ -278,11 +307,18 @@ lisa_guard_dedupe() {
   case "$transcript_size" in "" | *[!0-9]*) return 0 ;; esac
 
   # One command substitution, covering everything the verdict depends on: the
-  # guard's own bytes, this library's bytes, the payload, and which call it is.
+  # guard's own bytes, this library, delegated code, payload, and call identity.
+  # Keep literal bytes (including trailing newlines), and propagate every read
+  # failure. A successful digest of a partial stream is not proof of identity.
   local key=""
   key="$(
+    set -o pipefail
     {
-      cat "$self_script" "${BASH_SOURCE[0]}" 2>/dev/null
+      local source_file=""
+      for source_file in "$self_script" "${BASH_SOURCE[0]}" "${@:3}"; do
+        cat "$source_file" 2>/dev/null || exit 1
+        printf '\0'
+      done
       printf '\n%s\n' "$payload"
       printf '%s\n' "$transcript_size"
     } | if [ "$lisa_guard_memo_digest_tool" = "shasum" ]; then
@@ -293,6 +329,7 @@ lisa_guard_dedupe() {
   )" || key=""
   key="${key%% *}"
   case "$key" in "" | *[!0-9a-f]*) return 0 ;; esac
+  [ "${#key}" -eq 64 ] || return 0
 
   # One memo file per guard per session, rewritten as the call moves on, so the
   # state directory stays a fixed size however long a session runs. A saturated

package/plugins/lisa-agy/hooks/parity-safety-net-heredoc.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python3
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+
 """Classify the only heredoc forms whose payload is non-executable text.
 
 SCOPE — read this before hardening anything here (issue #1993).

package/plugins/lisa-agy/hooks/parity-safety-net.sh

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+
 # PreToolUse hook for Bash: a safety net that blocks destructive shell commands
 # before they run. Lisa-native reimplementation of the upstream
 # `safety-net@cc-marketplace` plugin's PreToolUse Bash-guard (parity work,
@@ -136,7 +139,8 @@ if [ -r "$lisa_guard_dedupe_lib" ]; then
   # shellcheck source=guard-dedupe.bash
   . "$lisa_guard_dedupe_lib"
   trap 'lisa_guard_dedupe_record $?' EXIT
-  lisa_guard_dedupe parity-safety-net "$input"
+  lisa_guard_dedupe parity-safety-net "$input" \
+    "$lisa_guard_hook_dir/parity-safety-net-heredoc.py"
 fi
 
 tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"

package/plugins/lisa-agy/plugin.json

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

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

@@ -215,9 +215,15 @@ nothing survives, exit on the denominator-stated summary from `summarizeDryLane`
 A blocker is a **claim with a timestamp, not a fact** — it goes stale the moment its condition comes
 true, and nothing re-read one before this phase. For each `$BLOCKED` candidate:
 
-1. **Human gate first, and it is absolute.** An issue carrying the configured human-needed label
-   (`github.labels.build.human_needed`, default `human-needed`) or a `[lisa-human-gate]` marker in
-   its body is **never** auto-selected, whatever any probe says.
+1. **Read release comments before applying the human gate.** Pass all item comments, labels,
+   body and configured `humanNeededLabel` to `classifyReadyCandidate(...)`. For a discharged hold,
+   call `planHumanGateRelease({ labels, body, comments, humanNeededLabel, readyLabel, lifecycleLabels, alreadyNotified })`
+   and retain its plan. Apply human-marker cleanup only as planned; defer any ready-role restoration
+   until steps 2–5 have cleared the remaining blockers (map the role to the vendor's state or label).
+   A still-active hold is never auto-selected, whatever any probe says. An absent or unreadable
+   comment history cannot discharge a hold. A release removes only the human hold: continue the
+   remaining blocker checks below before selecting the item.
+
 2. **Extract the stated discharge condition**, then **probe it**. Machine-testable conditions — a
    version on trunk, a published package, a CI run history, an advisory's patched status — rot
    fastest and are cheapest to check. A human decision is not machine-testable; leave it.
@@ -335,8 +341,9 @@ other gate's verdict — however conclusive — may promote an item a person par
    is the same repair the leaf-only gate already performs for a ready item that must not be
    dispatched.
 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
+   This ready-lane candidate can retain a historical body marker and a human-needed label.
+   This step reconciles only candidates still in the ready lane; released holds outside it are
+   recovered by `lisa-repair-intake` step 2b (or Phase 2.5 when included in this cycle). 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
@@ -369,11 +376,12 @@ GitHub Issues live in one repo by definition, so the scanned repo's issues are u
 1. **Resolve the current repo** per `config-resolution` "Repo scoping" (`.repo` → `.github.repo` → `git remote get-url origin` basename). If unresolvable, stop and report.
 2. **Cheap path first.** Prefer candidates already carrying the `repo:<current>` label. Keep the Phase 2 scan broad so unlabeled issues are still seen, determined, and stamped.
 3. **Per candidate, apply the repo-scope decision (`repo-scope-split`):**
-   - Carries `repo:<other>` → **skip** (leave it `ready` for that repo's own intake); next candidate.
-   - **Unlabeled** → determine the target repo(s) from the issue + code surfaces, then **stamp** `repo:<name>` via `gh issue edit <n> --add-label "repo:<name>"` (create the label lazily) so later cycles filter cheaply; re-apply with the now-known repo. (An issue whose work is entirely in the scanned repo is simply labeled `repo:<current>`.)
-   - **Container visibility is allowed.** A multi-repo Epic / Story / Spike may legitimately carry multiple `repo:<name>` labels for operator visibility. Do not split or claim it here; leave the repo markers intact and fall through to the leaf-only gate, which repairs the stale build-ready label instead of dispatching the container.
-   - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
-   - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
+   - **Count distinct repository markers first**: collect all `repo:<name>` labels and, on JIRA, recognized repository components; deduplicate by repository. A container may carry multiple `repo:<name>` labels. Do not split or claim it here; send it to the leaf-only gate.
+   - **Multi-repo leaf → split, never claim.** More than one repository takes the work-time split before any wrong-repository skip. Each sibling is **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
+   - **Exactly one other repository** (`repo:<other>`) → **skip**, leaving the item ready for that repo's intake.
+   - **No repository marker** → determine target repo(s) from the ticket and code, stamp `repo:<name>` through the vendor access layer, and re-apply from the count.
+   - **Single-repo leaf for the current repo** → fall through to 3a and 3b.
+
 4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the candidate set is exhausted — exit cleanly on the denominator-stated summary, naming the current repo alongside the swept lanes.
 
 #### 3a. Leaf-only claim gate (repair containers)

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

@@ -189,9 +189,15 @@ swept (see `automation-runbook-contract`).
 A blocker is a **claim with a timestamp, not a fact** — it goes stale the moment its condition comes
 true, and nothing re-read one before this phase. For each pre-work candidate outside `$READY`:
 
-1. **Human gate first, and it is absolute.** A ticket carrying the configured human-needed label
-   (`jira.labels.human_needed`, default `Human Needed`) or a `[lisa-human-gate]` marker in its
-   description is **never** auto-selected, whatever any probe says.
+1. **Read release comments before applying the human gate.** Pass all item comments, labels,
+   body and configured `humanNeededLabel` to `classifyReadyCandidate(...)`. For a discharged hold,
+   call `planHumanGateRelease({ labels, body, comments, humanNeededLabel, readyLabel, lifecycleLabels, alreadyNotified })`
+   and retain its plan. Apply human-marker cleanup only as planned; defer any ready-role restoration
+   until steps 2–5 have cleared the remaining blockers (map the role to the vendor's state or label).
+   A still-active hold is never auto-selected, whatever any probe says. An absent or unreadable
+   comment history cannot discharge a hold. A release removes only the human hold: continue the
+   remaining blocker checks below before selecting the item.
+
 2. **Extract the stated discharge condition**, then **probe it**. Machine-testable conditions — a
    version on trunk, a published package, a CI run history, an advisory's patched status — rot
    fastest and are cheapest to check. A human decision is not machine-testable; leave it.
@@ -240,8 +246,9 @@ other gate's verdict — however conclusive — may promote an item a person par
    is the same repair the leaf-only gate already performs for a ready item that must not be
    dispatched.
 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
+   This ready-lane candidate can retain a historical body marker and a human-needed label.
+   This step reconciles only candidates still in the ready lane; released holds outside it are
+   recovered by `lisa-repair-intake` step 2b (or Phase 2.5 when included in this cycle). 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
@@ -274,10 +281,12 @@ A JIRA project can oversee multiple repos (`frontend` / `backend` / `infrastruct
 1. **Resolve the current repo** per `config-resolution` "Repo scoping" (`.repo` → `.github.repo` → `git remote get-url origin` basename). If unresolvable, stop and report — do not claim tickets you cannot scope.
 2. **Cheap path first.** Phase 1's query-time pre-filter has already dropped tickets explicitly stamped for a sibling repo, so the Phase 2 result set is current-repo-labeled + unlabeled tickets. Prefer candidates already carrying `repo:<current>` — a JIRA **label**, or a **component** equal to the repo name (accepted as an alias); the pre-filter is label-only, so a ticket scoped solely by a sibling-repo **component** can still appear and is skipped here. The result set still includes unlabeled tickets so they can be determined and stamped; this gate orders/filters what remains.
 3. **Per candidate, apply the repo-scope decision (`repo-scope-split`):**
-   - Carries `repo:<other>` (label or component) → **skip** (leave it `ready` for that repo's own intake); next candidate.
-   - **Unlabeled** → determine the target repo(s) from the ticket (description, AC, technical approach) confirmed against the code surfaces, then **stamp** `repo:<name>` via `lisa-atlassian-access` `operation: write-ticket` (add the label / set the component) so later cycles filter cheaply; re-apply with the now-known repo.
-   - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure to break it into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
-   - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
+   - **Count distinct repository markers first**: collect all `repo:<name>` labels and, on JIRA, recognized repository components; deduplicate by repository. A container may carry multiple `repo:<name>` labels. Do not split or claim it here; send it to the leaf-only gate.
+   - **Multi-repo leaf → split, never claim.** More than one repository takes the work-time split before any wrong-repository skip. Each sibling is **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
+   - **Exactly one other repository** (`repo:<other>`) → **skip**, leaving the item ready for that repo's intake.
+   - **No repository marker** → determine target repo(s) from the ticket and code, stamp `repo:<name>` through the vendor access layer, and re-apply from the count.
+   - **Single-repo leaf for the current repo** → fall through to 3a and 3b.
+
 4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the candidate set is exhausted — exit cleanly on the denominator-stated summary, naming the current repo alongside the swept lanes.
 
 #### 3a. Leaf-only claim gate (skip / safe-block containers)

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

@@ -188,7 +188,7 @@ Consumers pass business-shaped arguments only; they do not embed GraphQL.
 
 **This layer does not accept a state to write. It resolves one.** A `save-issue`
 that changes the workflow state declares `lifecycle_role:<ROLE>` — the semantic
-role it is applying (`ready`, `claimed`, `blocked`, `review`, `done`) — plus `env:<KEY>` when the role is the env-indexed
+role it is applying (for example, `ready`, `claimed`, `blocked`, `review`, `done`; the configured role contract is authoritative) — plus `env:<KEY>` when the role is the env-indexed
 `done`. This layer then resolves that role against config and the team's own
 catalog, and sends the ID **it** resolved.
 
@@ -319,9 +319,9 @@ 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!){
+query($id:String!,$after:String){
   project(id:$id){
-    comments(first:100){
+    comments(first:100,after:$after){
       pageInfo{ hasNextPage endCursor }
       nodes{ id body createdAt url user{ name } }
     }
@@ -329,8 +329,47 @@ query($id:String!){
 }
 ```
 
-The Issue form reads through `issue(id:$id){ comments{...} }` with the identical
-node shape, so a caller consumes one result format for either anchor.
+The Issue form uses `issue(id:$id)` with the same `first:100,after:$after`
+arguments and node shape. For **both** anchors, use this access-layer adapter with
+`linear_graphql` above; it accumulates every page and prints no partial history.
+A read succeeds only after `hasNextPage` is false. Errors, malformed pages, and
+missing or repeated continuation cursors fail the whole read.
+
+```bash
+linear_list_comment_pages() {  # issue|project id -> complete JSON node array
+  local anchor="$1" id="$2" after=null nodes='[]' seen='[]'
+  local query variables response connection cursor
+  case "$anchor" in issue|project) ;; *) echo "Error: invalid comment anchor" >&2; return 1 ;; esac
+  query='query($id:String!,$after:String){'"$anchor"'(id:$id){comments(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id body createdAt url user{name}}}}}'
+  while :; do
+    variables=$(jq -cn --arg id "$id" --argjson after "$after" '{id:$id,after:$after}') || return 1
+    response=$(linear_graphql "$query" "$variables") || return 1
+    connection=$(printf '%s' "$response" | jq -ce --arg anchor "$anchor" '
+      if (.errors != null and .errors != []) then error("GraphQL comments read failed")
+      else .data[$anchor].comments end |
+      if (.nodes | type) != "array" or (.pageInfo.hasNextPage | type) != "boolean"
+      then error("Incomplete comments page") else . end') || return 1
+    nodes=$(jq -cn --argjson prior "$nodes" --argjson page "$connection" '$prior + $page.nodes') || return 1
+    if [ "$(printf '%s' "$connection" | jq -r '.pageInfo.hasNextPage')" = false ]; then
+      printf '%s\n' "$nodes"
+      return 0
+    fi
+    cursor=$(printf '%s' "$connection" | jq -ce '.pageInfo.endCursor | select(type == "string" and length > 0)') || {
+      echo "Error: incomplete comments history; missing cursor" >&2; return 1;
+    }
+    if jq -en --argjson seen "$seen" --argjson cursor "$cursor" '$seen | index($cursor) != null' >/dev/null; then
+      echo "Error: incomplete comments history; repeated cursor" >&2
+      return 1
+    fi
+    seen=$(jq -cn --argjson seen "$seen" --argjson cursor "$cursor" '$seen + [$cursor]') || return 1
+    after="$cursor"
+  done
+}
+```
+
+Call `linear_list_comment_pages project "$PROJECT_ID"` for `project_id`, or
+`linear_list_comment_pages issue "$ISSUE_ID"` for `issue_id`. The caller receives
+one complete node array; it must not interpret a failed command as zero comments.
 
 **Substrate.** The Linear MCP exposes comments on Issues only, so the
 `project_id` form resolves solely through the tier-1 `LINEAR_API_KEY` + GraphQL
@@ -339,7 +378,7 @@ 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
+`Error:` result naming the requested `save-comment project_id` or `list-comments project_id` operation — do **not** silently degrade
 into creating an Issue to comment on.
 
 ## `history` — transition history (read-only)

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

@@ -182,7 +182,15 @@ A blocker is a **claim with a timestamp, not a fact**. It is written once and go
 
 For each pre-work candidate that is **not** in `$READY`:
 
-1. **Human gate first, and it is absolute.** An Issue carrying the configured human-needed label (`linear.labels.build.human_needed`, default `human-needed`) or a `[lisa-human-gate]` marker in its description is **never** auto-selected, whatever any probe says. Skip it and move on.
+1. **Read release comments before applying the human gate.** Pass all item comments, labels,
+   body and configured `humanNeededLabel` to `classifyReadyCandidate(...)`. For a discharged hold,
+   call `planHumanGateRelease({ labels, body, comments, humanNeededLabel, readyLabel, lifecycleLabels, alreadyNotified })`
+   and retain its plan. Apply human-marker cleanup only as planned; defer any ready-role restoration
+   until steps 2–5 have cleared the remaining blockers (map the role to the vendor's state or label).
+   A still-active hold is never auto-selected, whatever any probe says. An absent or unreadable
+   comment history cannot discharge a hold. A release removes only the human hold: continue the
+   remaining blocker checks below before selecting the item.
+
 2. **Extract the stated discharge condition** from the description or the most recent blocking comment — the sentence naming what has to become true.
 3. **Probe it.** Machine-testable conditions are the ones that rot fastest and are cheapest to check: a version on trunk (`git show origin/<trunk>:<manifest>`), a published package, a run history (`gh run list`), an advisory's patched status. A condition that is a human decision is not machine-testable — leave it and move on.
 4. **Classify with the shared helper** so the ordering and the evidence requirement cannot drift per vendor:
@@ -234,8 +242,9 @@ other gate's verdict — however conclusive — may promote an item a person par
    is the same repair the leaf-only gate already performs for a ready item that must not be
    dispatched.
 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
+   This ready-lane candidate can retain a historical body marker and a human-needed label.
+   This step reconciles only candidates still in the ready lane; released holds outside it are
+   recovered by `lisa-repair-intake` step 2b (or Phase 2.5 when included in this cycle). 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
@@ -268,10 +277,12 @@ A Linear team can oversee multiple repos (`frontend` / `backend` / `infrastructu
 1. **Resolve the current repo** per `config-resolution` "Repo scoping" (`.repo` → `.github.repo` → `git remote get-url origin` basename). If unresolvable, stop and report.
 2. **Cheap path first.** Prefer candidates already carrying the `repo:<current>` label. Keep the Phase 2 scan broad so unlabeled Issues are still seen, determined, and stamped.
 3. **Per candidate, apply the repo-scope decision (`repo-scope-split`):**
-   - Carries `repo:<other>` → **skip** (leave it `ready` for that repo's own intake); next candidate.
-   - **Unlabeled** → determine the target repo(s) from the Issue + code surfaces, then **stamp** `repo:<name>` via `lisa-linear-access operation: save-issue` (resolve/create the label via `list_issue_labels`/`create_issue_label`) so later cycles filter cheaply; re-apply with the now-known repo.
-   - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
-   - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
+   - **Count distinct repository markers first**: collect all `repo:<name>` labels and, on JIRA, recognized repository components; deduplicate by repository. A container may carry multiple `repo:<name>` labels. Do not split or claim it here; send it to the leaf-only gate.
+   - **Multi-repo leaf → split, never claim.** More than one repository takes the work-time split before any wrong-repository skip. Each sibling is **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
+   - **Exactly one other repository** (`repo:<other>`) → **skip**, leaving the item ready for that repo's intake.
+   - **No repository marker** → determine target repo(s) from the ticket and code, stamp `repo:<name>` through the vendor access layer, and re-apply from the count.
+   - **Single-repo leaf for the current repo** → fall through to 3a and 3b.
+
 4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the candidate set is exhausted — exit cleanly on the denominator-stated summary, naming the current repo alongside the swept lanes.
 
 #### 3a. Leaf-only claim gate (skip / safe-block containers)

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

@@ -130,6 +130,16 @@ Select the first ready project returned by Phase 2 and process only that project
 
 #### 3a. Claim
 
+**Preflight project comments before any claim or destination-ticket creation.** Through
+`lisa-linear-access`, resolve an identity-matched tier-1 GraphQL credential and the
+`save-comment project_id` adapter, then read the candidate's complete project comment
+history with `list-comments project_id:<id>`. The issue-only MCP is insufficient for
+this flow. If the required credential, adapter or read is unavailable, return the
+layer's `Error:` naming the project-comment operation and leave the project ready;
+create no tickets and no substitute comment-holder Issue. This is a read-only
+capability preflight, not a test comment. It establishes the available transport;
+later permission changes or write failures still follow the normal error handler.
+
 Transition labels via `lisa-linear-access operation: save-project({id, labels})`: pass the full new label set with `$READY` removed and `$IN_REVIEW` added. This is the idempotency lock — a re-entrant cycle running concurrently won't see this project because its query filters on `label: "$READY"`.
 
 If the update fails (permission error, race condition), log it and skip this project. Do not proceed to validation on a project you didn't successfully claim.
@@ -152,7 +162,7 @@ This call also indirectly invokes `lisa-tracker-source-artifacts` (artifact extr
 
 1. Re-invoke `lisa-linear-to-tracker` with `dry_run: false` to actually write the tickets. This re-runs Phases 1-5 and runs the preservation gate (Phase 5.5).
 2. Capture the created ticket keys from the skill's output.
-3. Post a comment on the project via `lisa-linear-access operation: save-comment project_id:<id>` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Add the $SHIPPED label to the Linear project after the work is delivered."`
+3. Post a comment on the project via `lisa-linear-access operation: save-comment project_id:<id>` listing the created tickets (epic, stories, sub-tasks) with the URLs returned by the configured destination tracker. Lead with: `"Ticketed by Claude. Created N tickets — see below. Add the $SHIPPED label to the Linear project after the work is delivered."`
 4. Transition labels: remove `$IN_REVIEW`, add `$TICKETED` via `save_project`.
 5. **Run Phase 3e (coverage audit)** before considering this PRD done.
 
@@ -396,6 +406,6 @@ Before this skill can run against a Linear workspace or team, the team must adop
 1. Apply the `ready` label (default: `prd-ready`) to projects that are ready for ticketing (replaces the Notion `Status = Ready` flip and the Confluence `prd-ready` page label).
 2. Reserve `in_review`, `blocked`, `ticketed` (defaults: `prd-in-review`, `prd-blocked`, `prd-ticketed`) for this skill — humans should not set them manually except to recover from an error.
 3. (Optional but recommended) Add the `draft` and `shipped` labels (defaults: `prd-draft`, `prd-shipped`) for in-progress PRDs and delivered work respectively, so the full lifecycle is visible at a glance.
-4. The labels must exist as **project labels** in Linear (`list_project_labels` should return them). Issue-level labels with the same names won't work; Linear keeps the two label kinds separate.
+4. The labels must exist as **project labels** in Linear (`list-project-labels` should return them). Issue-level labels with the same names won't work; Linear keeps the two label kinds separate.
 
 If the workspace hasn't adopted these labels, the first run exits with a label-convention error (not the idle empty-set message) — this distinguishes a setup issue from a genuinely empty queue so operators know to apply the convention rather than assuming there is no work. See Phase 2 for how the skill detects this case.

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

@@ -91,24 +91,7 @@ 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.
+For existing items written through another path, use the [standalone entry point](#standalone-entry-point--validating-an-item-written-by-another-path). A transport read-back does not prove the stored specification passes the gates.
 
 ## Gates
 

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

@@ -63,20 +63,3 @@ normalize-then-compare. Byte-exact comparison of such text is forbidden.
 - 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-agy/skills/lisa-linear-write-issue/SKILL.md

@@ -33,40 +33,7 @@ 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.
+For direct API or bespoke script writes, the [bespoke-path contract](#writing-by-a-bespoke-path-your-own-script-direct-api-or-graphql) still requires pre-write validation and post-write verification.
 
 ## Phase 1 — Resolve Intent
 
@@ -334,6 +301,8 @@ 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.
 
+**Every marker reader must consult comments.** Use `classifyReadyCandidate` with labels, body, comments and the configured human-needed label, then `planHumanGateRelease` for any release actions. A historical body marker alone is not an active hold after its matching release; unreadable comments leave a hold in place.
+
 **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

package/plugins/lisa-agy/skills/lisa-prd-ticket-coverage/SKILL.md

@@ -15,7 +15,7 @@ The PRD URL can be a **Notion page URL**, a **Confluence page URL**, a **Linear
 
 - `notion.so` / `notion.site` → Notion. Fetch with `mcp__claude_ai_Notion__notion-fetch` (`include_discussions: true`) and `mcp__claude_ai_Notion__notion-get-comments`.
 - Atlassian Confluence host (e.g. `*.atlassian.net/wiki/...`) → Confluence. Through `lisa-atlassian-access`, fetch the page, its descendants (for child epic pages), and its footer + inline comments including nested replies. State the operation, not a vendor tool name — the access skill owns substrate selection (`integration-access-layer`).
-- `linear.app` host → Linear. Fetch with `lisa-linear-access operation: get-project` (capture description, labels, state, attached resources), `lisa-linear-access operation: list-documents({projectId})` + `lisa-linear-access operation: get-document` per attached document, `lisa-linear-access operation: list-issues({project})` for sub-issues that act as child epics / user stories, and `lisa-linear-access operation: list-comments({issueId})` per sub-issue for decisions and engineering notes. Comments do not exist on the project itself in the MCP surface — sub-issue comments are the substitute.
+- `linear.app` host → Linear. Fetch with `lisa-linear-access operation: get-project` (capture description, labels, state, attached resources), `lisa-linear-access operation: list-documents({projectId})` + `lisa-linear-access operation: get-document` per attached document, `lisa-linear-access operation: list-issues({project})` for sub-issues that act as child epics / user stories, and `lisa-linear-access operation: list-comments({issueId})` per sub-issue for decisions and engineering notes. Also fetch all project comments with `lisa-linear-access operation: list-comments project_id:<ID>`; the access layer pages through GraphQL even when the MCP lacks project comments. An incomplete comment read is an access failure, not an empty history.
 - `github.com` host → GitHub Issues. Fetch with the `gh` CLI (no GitHub MCP — Lisa uses the CLI exclusively for GitHub):
   - `gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,milestone,assignees,author,createdAt,comments,url` for the PRD body and comments.
   - `gh api graphql` with the `subIssues` field for native sub-issue children (these stand in for child epic pages — see `lisa-github-read-issue` Phase 3 for the exact query).
@@ -41,7 +41,7 @@ Per-ticket gates (`lisa-jira-validate-ticket`) prove each created ticket is well
 2. Fetch the PRD using the vendor-appropriate tool surface:
    - **Notion**: `notion-fetch` with `include_discussions: true`. Capture: title, body, child Epic pages, all comment threads.
    - **Confluence**: `getConfluencePage` (capture title, body, labels), `getConfluencePageFooterComments` + `getConfluencePageInlineComments` (capture all comments; walk replies via `getConfluenceCommentChildren` for any thread with children).
-   - **Linear**: `get_project` (capture name, description, labels, state, attached resources). Capture sub-issues via `list_issues({project})` and per-issue comments via `list_comments({issueId})`.
+   - **Linear**: `get_project` (capture name, description, labels, state, attached resources). Capture all project comments via `lisa-linear-access operation: list-comments project_id:<ID>`, plus sub-issues via `list_issues({project})` and per-issue comments via `list_comments({issueId})`. Include both comment sources in destination URL discovery; refuse to report `NO_TICKETS_FOUND` from an incomplete read.
    - **GitHub**: `gh issue view --json` for the source PRD issue (title, body, labels, comments). Capture sub-issues via the GraphQL `subIssues` traversal.
 3. If the PRD has child Epic sub-pages / sub-issues (a multi-epic PRD), fetch each in parallel:
    - **Notion**: `notion-fetch` per child page with `include_discussions: true`.