@codyswann/lisa 4.34.2 → 4.34.4

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

@@ -199,6 +199,41 @@ classifyPreWorkCandidate({ laneType, labels, body, humanNeededLabel, statedBlock
 
 ### Phase 3 — Process the first eligible ready Issue
 
+#### 3.0 Human-hold gate (absolute, and it runs before every other gate)
+
+A person parks an item by putting `[lisa-human-gate]` in its description. That marker used to be
+read only for candidates **outside** `$READY` (Phase 2's blocker re-probe), so an item already in
+the ready lane was claimed with the hold never consulted — one was dispatched and fully implemented
+before a human vetoed the merge. The check was correct; it was unreachable from the path that
+matters.
+
+Run this **first**, ahead of the repo-scope gate (3a.0) and the leaf-only gate (3a), for every ready
+candidate. Ordering is load-bearing for the same reason it is inside `classifyPreWorkCandidate`: no
+other gate's verdict — however conclusive — may promote an item a person parked.
+
+1. **Classify with `classifyReadyCandidate(...)`** from `scripts/intake-blocker-reprobe.mjs`. It
+   shares the gate test with the pre-work classifier deliberately — two copies of a substring test
+   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.
+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
+   are **not** in the ready role and excludes gated ones outright, so a ready-and-gated item falls
+   outside its filter twice over. Call
+   `planHumanGateReconciliation({ labels, body, humanNeededLabel, readyLabel, alreadyNotified })`
+   and apply exactly the actions it returns: remove `$READY`, add the configured human-needed
+   marker, and post `formatHumanGateNote()` once. The planner is idempotent by state, so an item
+   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
+   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.
+5. **Continue to the next candidate.** A held item does not end the cycle.
+
+
 #### 3a.0 Repo-scope gate (claim only current-repo Issues)
 
 A Linear team can oversee multiple repos (`frontend` / `backend` / `infrastructure`). This skill claims only Issues for the repo it is running in. Run this gate **before** the leaf-only gate (3a) and the claim (3b), per the `repo-scope-split` rule's "Claim-time repo scoping" section (cite it by slug; do not restate its decision table).

package/scripts/two-channel-couplings.json

@@ -5,7 +5,7 @@
   },
   "inspected": {
     "workflows": 22,
-    "steps": 678,
+    "steps": 708,
     "couplings": 33,
     "inventory": 69
   },

package/typescript/copy-overwrite/.claude/hooks/worktree-create.sh

@@ -10,17 +10,28 @@
 # so every git command redirects its output off stdout, and progress goes to
 # stderr (NOT /dev/tty, which is "not configured" in headless `-p`/CI sessions).
 #
-# It mirrors Claude's default layout — <cwd>/.claude/worktrees/<name> on a fresh
-# `worktree-<name>` branch — so behavior is unchanged; the value is clean,
-# pre-TUI output and an explicit, durable creation path. The plugin bootstrap
-# itself is done by the `post-checkout` hook that `git worktree add` fires, so
-# `claude -w` and standalone `cd && claude` sessions converge on the same state.
+# It mirrors Claude's default layout — <cwd>/.claude/worktrees/<name> — but the
+# new branch is cut from the repository's INTEGRATION branch, not from whatever
+# the invoking checkout happened to be standing on. See "Choosing the base".
+# The plugin bootstrap itself is done by the `post-checkout` hook that
+# `git worktree add` fires, so `claude -w` and standalone `cd && claude`
+# sessions converge on the same state.
 #
 # Payload (observed, Claude Code stdin):
 #   { "name": "<worktree>", "cwd": "<project root>", "hook_event_name": ... }
+#
+# Agent parity: `WorktreeCreate` is a Claude Code hook event and has no
+# counterpart on Codex, Cursor, OpenCode, Copilot or Antigravity — none of them
+# delegate worktree creation to the host project. There is deliberately no
+# projection of this file for those agents; on them, worktrees are created by
+# whatever invokes git directly, and the base-selection rules below do not
+# apply. This is a genuine surface gap, not a parity omission.
 
 _log() { echo "$*" >&2; }
 
+# The remote whose default branch defines "the integration branch" here.
+_remote="origin"
+
 _payload="$(cat)"
 
 if command -v jq >/dev/null 2>&1; then
@@ -43,7 +54,21 @@ case "$_name" in
     ;;
 esac
 
-_root="${_cwd:-$(pwd)}"
+# Which REPOSITORY this hook operates on is decided entirely by the payload's
+# `cwd`. This hook cannot validate that choice — it is handed `{ name, cwd }`
+# and nothing that names the intended repository, so it has no way to tell a
+# correct `cwd` from one that drifted. What it can do is refuse to be silent
+# about falling back to ambient process state, which is the one part of the
+# repository choice that happens HERE rather than upstream.
+if [ -n "${_cwd:-}" ]; then
+  _root="$_cwd"
+else
+  _root="$(pwd)"
+  _log "WorktreeCreate: WARNING — payload carried no 'cwd'; falling back to the"
+  _log "  process working directory: $_root"
+  _log "  If that is not the repository you meant, this worktree is in the wrong one."
+fi
+
 _base="$_root/.claude/worktrees"
 _path="$_base/$_name"
 _wt_branch="worktree-$_name"
@@ -55,23 +80,160 @@ if [ -d "$_path" ]; then
   exit 0
 fi
 
+# ---------------------------------------------------------------------------
+# Choosing the base
+#
+# This used to be a literal `HEAD`, which made the base of every new worktree a
+# property of ambient session state rather than of the work being handed over: a
+# checkout parked on an unmerged feature branch silently handed each new
+# worktree that other work item's commits, and a PR opened from it presented
+# them as its own. Nothing errored, and no identity check catches it — the
+# directory, the branch name and the binding are all exactly what was asked for.
+# Only the base was wrong, and nothing inspects a base.
+#
+# Resolution is OFFLINE ONLY. This hook runs before a session starts and must
+# never stall on the network, so it reads the LOCAL ref store and nothing else.
+# Precedence, most explicit first:
+#
+#   1. $LISA_WORKTREE_BASE       — operator override; wrong here is fatal
+#   2. refs/remotes/<remote>/HEAD — the remote's own declared default branch
+#   3. .lisa.config.json          — deploy.branches.production, as a hint
+#   4. HEAD                       — fallback, and never a silent one
+#
+# origin/HEAD outranks the config hint deliberately. `deploy.branches.production`
+# names a DEPLOY target, which in a dev/staging/prod repository is not the branch
+# work integrates onto; origin/HEAD is that repository's own statement of its
+# default branch, which is.
+
+# Fully qualified remote default-branch ref, or nothing when it cannot be
+# resolved offline. Mirrors `remoteDefaultRef` in lisa-work-item.mjs: the symref
+# must point INSIDE refs/remotes/<remote>/ and the ref it names must exist, so a
+# crafted symref cannot redirect the base somewhere arbitrary.
+_resolve_remote_head() {
+  _sym="$(git -C "$_root" symbolic-ref --quiet "refs/remotes/$_remote/HEAD" 2>/dev/null)" || return 1
+  [ -n "$_sym" ] || return 1
+  case "$_sym" in
+    "refs/remotes/$_remote/"*) ;;
+    *) return 1 ;;
+  esac
+  git -C "$_root" rev-parse -q --verify "$_sym" >/dev/null 2>&1 || return 1
+  printf '%s' "$_sym"
+}
+
+# Lisa's configured production branch, resolved to a real ref — remote-tracking
+# first, then local. A configured NAME that resolves to no ref is not usable.
+_resolve_config_base() {
+  _cfg="$_root/.lisa.config.json"
+  [ -f "$_cfg" ] || return 1
+  _cfg_branch="$(jq -r '.deploy.branches.production // empty' <"$_cfg" 2>/dev/null)" || return 1
+  [ -n "$_cfg_branch" ] || return 1
+  for _cand in "refs/remotes/$_remote/$_cfg_branch" "refs/heads/$_cfg_branch"; do
+    if git -C "$_root" rev-parse -q --verify "$_cand" >/dev/null 2>&1; then
+      printf '%s' "$_cand"
+      return 0
+    fi
+  done
+  return 1
+}
+
+_base_ref=""
+_base_source=""
+
+if [ -n "${LISA_WORKTREE_BASE:-}" ]; then
+  # An explicit override that does not resolve is a configuration error the
+  # operator can see and fix. Quietly ignoring it would reintroduce this very
+  # bug — a base silently different from the one that was asked for.
+  if git -C "$_root" rev-parse -q --verify "$LISA_WORKTREE_BASE" >/dev/null 2>&1; then
+    _base_ref="$LISA_WORKTREE_BASE"
+    _base_source="LISA_WORKTREE_BASE"
+  else
+    _log "WorktreeCreate: LISA_WORKTREE_BASE='$LISA_WORKTREE_BASE' does not resolve"
+    _log "  to a ref in $_root; refusing rather than silently using a different base."
+    exit 1
+  fi
+fi
+
+if [ -z "$_base_ref" ]; then
+  _base_ref="$(_resolve_remote_head)" && _base_source="$_remote/HEAD"
+fi
+
+if [ -z "$_base_ref" ] && command -v jq >/dev/null 2>&1; then
+  _base_ref="$(_resolve_config_base)" && _base_source="deploy.branches.production"
+fi
+
+if [ -z "$_base_ref" ]; then
+  _base_ref="HEAD"
+  _base_source="fallback"
+fi
+
 mkdir -p "$_base" 2>/dev/null || true
-_log "Creating worktree $_path (branch: $_wt_branch)…"
 
-# Reuse the worktree branch if it already exists, else create it from HEAD.
-# All git output is kept off stdout (its "Preparing worktree…" line would
-# corrupt the path contract and hang Claude).
+# Announce what was resolved, so a wrong repository or a wrong base is visible
+# AT CREATION instead of being reconstructed hours later from a confused agent.
+# The origin URL can embed a credential (https://user:token@host/...), so strip
+# any userinfo before it reaches a log.
+_origin_url="$(git -C "$_root" remote get-url "$_remote" 2>/dev/null | sed -e 's#://[^/@]*@#://#')"
+_base_sha="$(git -C "$_root" rev-parse --short "$_base_ref" 2>/dev/null)"
+
+_log "Creating worktree $_path"
+_log "  repository : $_root"
+_log "  origin     : ${_origin_url:-<none>}"
+_log "  branch     : $_wt_branch"
+_log "  base       : $_base_ref @ ${_base_sha:-<unknown>} ($_base_source)"
+
+if [ "$_base_source" = "fallback" ]; then
+  _log "WorktreeCreate: WARNING — no integration branch could be resolved for this"
+  _log "  repository, so this worktree is based on whatever branch that checkout was"
+  _log "  standing on. It may carry another work item's unmerged commits. Check with:"
+  _log "    git -C $_path log --oneline -5"
+fi
+
+# Reuse the worktree branch if it already exists, else create it from the
+# resolved base. All git output is kept off stdout (its "Preparing worktree…"
+# line would corrupt the path contract and hang Claude); stderr is captured so a
+# failure can say WHY instead of just that it happened.
+#
+# --no-track matters: without it, branching from refs/remotes/<remote>/<default>
+# sets the integration branch as this branch's upstream, and a later bare
+# `git push` from the worktree would target it.
 if git -C "$_root" show-ref --verify --quiet "refs/heads/$_wt_branch" 2>/dev/null; then
-  git -C "$_root" worktree add "$_path" "$_wt_branch" >/dev/null 2>&1
+  _reused=1
+  _add_err="$(git -C "$_root" worktree add "$_path" "$_wt_branch" 2>&1 >/dev/null)"
 else
-  git -C "$_root" worktree add -b "$_wt_branch" "$_path" HEAD >/dev/null 2>&1
+  _reused=0
+  _add_err="$(git -C "$_root" worktree add --no-track -b "$_wt_branch" "$_path" "$_base_ref" 2>&1 >/dev/null)"
 fi
 
 if [ ! -d "$_path" ]; then
   _log "WorktreeCreate: git worktree add failed for $_path."
+  [ -n "$_add_err" ] && _log "  git: $_add_err"
   exit 1
 fi
 
+if [ "$_reused" = "1" ]; then
+  # A reused branch legitimately carries its own prior work, so its commits
+  # ahead of the integration branch are expected. Report, do not refuse.
+  _log "  reused existing branch $_wt_branch"
+elif [ "$_base_source" != "fallback" ]; then
+  # Post-condition. A freshly cut branch is AT its base, so this is 0 by
+  # construction — which is exactly why it is worth asserting: if base selection
+  # ever regresses, this is what catches it, loudly, instead of handing back a
+  # plausible-looking tree with someone else's commits in it.
+  _ahead="$(git -C "$_path" rev-list --left-right --count "$_base_ref...HEAD" 2>/dev/null | awk '{print $2}')"
+  case "${_ahead:-0}" in
+    "" | 0) ;;
+    *[!0-9]*) ;;
+    *)
+      _log "WorktreeCreate: REFUSING — the new worktree carries $_ahead commit(s) that"
+      _log "  are not on $_base_ref. That means it inherited another work item's"
+      _log "  unmerged work. Removing it rather than handing back a wrong tree."
+      git -C "$_root" worktree remove --force "$_path" >/dev/null 2>&1
+      git -C "$_root" branch -D "$_wt_branch" >/dev/null 2>&1
+      exit 1
+      ;;
+  esac
+fi
+
 # THE ONLY thing on stdout: the absolute worktree path.
 printf '%s\n' "$_path"
 exit 0