feat(dispatcher): support cross-repo deps in check_deps_resolved (closes #157) (#160)

## Summary

- Fix `check_deps_resolved` two-bug class (#157): cross-repo
`owner/repo#N` refs were collapsing to bare `N` queried in the wrong
repo, and prose/blockquote `#N` mentions were greedy-extracted — both
ending in the same silent-block-forever path.
- Restrict extraction to list-item lines only; recognize `owner/repo#N`
(cross-repo) and `#N` (same-repo) with left-boundary anchors so URL
fragments and inline punctuation don't misparse.
- On lookup failure (empty `$state` from `gh issue view`), fail-safe
block AND emit a stderr warning naming the failed ref — without that, a
typo would silently recreate the original bug class.

## Spec & docs

- **Design doc**:
`docs/superpowers/specs/2026-05-27-cross-repo-deps-design.md`
- **New invariant**:
[INV-39](https://github.com/zxkane/autonomous-dev-team/blob/feat/cross-repo-deps/docs/pipeline/invariants.md#inv-39-dependency-parsing-is-list-item-scoped-and-supports-cross-repo-refs)
— list-item scope, cross-repo support, lookup-failure semantics.
- **Updated invariant**: INV-11 cross-references INV-39 (`state ∉
{CLOSED, MERGED}` rule applies to both same-repo and cross-repo refs).
- **Flow doc**: `docs/pipeline/dispatcher-flow.md` Step 2 description
updated.
- **User-facing**: `skills/create-issue/SKILL.md` and
`references/issue-templates.md` document list-item scope +
`owner/repo#N` syntax.

## Test plan

- [x] All existing `#61`/`#73` regression cases continue to pass (no
behavior change for bare-`#N`-on-list-item).
- [x] Cross-repo `owner/repo#N`: CLOSED/MERGED → resolved; OPEN →
blocked.
- [x] Same number in two repos resolves independently (`#42` OPEN in
this repo + `other/other#42` CLOSED → resolved).
- [x] Mixed list items: same-repo CLOSED + cross-repo OPEN → blocked.
- [x] Prose-embedded `#N` between headings → ignored (was the
silent-block bug).
- [x] Blockquote `> ... owner/repo#N ...` → ignored.
- [x] URL fragment `https://github.com/.../issues/123` → ignored.
- [x] Numbered list (`1.` / `2.`) → extracted correctly.
- [x] Failed `gh issue view` (404 / unauthorized) → blocks AND emits
stderr warning naming the failed ref.

`bash tests/unit/test-check-deps-resolved.sh` — 20/20 PASS.
`bash tests/unit/test-create-issue-dependencies-guidance.sh` — 10/10
PASS.
`bash tests/unit/test-lib-dispatch.sh` — 21/21 PASS.

Closes #157.

Author: zxkane

docs/pipeline/dispatcher-flow.md

@@ -162,7 +162,7 @@ Find issues labeled `autonomous` with **no other active state label** (no `in-pr
 
 For each match, in order:
 
-1. **Dependency check.** Read the issue body for a `## Dependencies` section. Extract every `#N` reference. For each, call `gh issue view N --json state` and require state `CLOSED` or `MERGED` ([INV-11](invariants.md#inv-11-dependency-state-includes-merged) — PRs report `MERGED`, not `CLOSED`). If any dependency is still open, **skip silently** — no comment, no label change. The issue picks up next tick once dependencies clear.
+1. **Dependency check.** Read the issue body for a `## Dependencies` section. Extract refs from list-item lines only — `#N` and `owner/repo#N` are recognized; prose and blockquotes are ignored ([INV-39](invariants.md#inv-39-dependency-parsing-is-list-item-scoped-and-supports-cross-repo-refs)). For each ref, call `gh issue view N --repo <repo> --json state` and require state `CLOSED` or `MERGED` ([INV-11](invariants.md#inv-11-dependency-state-includes-merged) — PRs report `MERGED`, not `CLOSED`; the same rule applies to cross-repo refs). If any dependency is still open, **skip silently** — no comment, no label change. The issue picks up next tick once dependencies clear.
 2. **Add `in-progress` label.**
 3. **Post dispatch token** ([INV-18](invariants.md#inv-18-cold-start-grace-period-before-stale-detection)): write `<!-- dispatcher-token: <id> at <iso> mode=dev-new -->` followed by the human-readable "Dispatching autonomous development..." line. The HTML comment encodes the dispatch timestamp for Step 5's grace-period check.
 4. **Dispatch**: `bash $PROJECT_DIR/scripts/dispatch-local.sh dev-new <issue>`

docs/pipeline/invariants.md

@@ -175,14 +175,14 @@ The cutoff timestamp falls back to epoch (1970-01-01) for issues that have never
 
 ## INV-11: Dependency state includes `MERGED`
 
-**Rule**: Step 2's dependency check MUST treat both `CLOSED` and `MERGED` as resolved states. PRs return `MERGED` when merged, NOT `CLOSED`.
+**Rule**: Step 2's dependency check MUST treat both `CLOSED` and `MERGED` as resolved states. PRs return `MERGED` when merged, NOT `CLOSED`. The same `state ∉ {"CLOSED", "MERGED"}` rule applies to cross-repo refs resolved under [INV-39](#inv-39-dependency-parsing-is-list-item-scoped-and-supports-cross-repo-refs).
 
 **Why**: When a `## Dependencies` section references a PR that has been merged, `gh issue view N --json state` returns `state: "MERGED"`. A naive `state != "CLOSED"` check leaves the dependent issue blocked forever (#61).
 
 **Producer**: dispatcher Step 2 (`lib-dispatch.sh::check_deps_resolved`).
 **Consumer**: itself.
-**Status**: **ENFORCED** in PR-4 (closes #61). The check now reads `state ∉ {"CLOSED", "MERGED"}`.
-**Test**: `tests/unit/test-check-deps-resolved.sh` covers single-CLOSED, single-MERGED, single-OPEN, and multi-dep mixed-state scenarios.
+**Status**: **ENFORCED** in PR-4 (closes #61). The check reads `state ∉ {"CLOSED", "MERGED"}` for both same-repo and cross-repo refs.
+**Test**: `tests/unit/test-check-deps-resolved.sh` covers single-CLOSED, single-MERGED, single-OPEN, multi-dep mixed-state scenarios, and cross-repo MERGED/CLOSED/OPEN.
 
 ## INV-12: Resume only against unfinished sessions
 
@@ -1018,6 +1018,36 @@ Where `<short-token>` is one of `bot-timeout`, `ci-transport`, `no-pr-found`, `m
 - [INV-31](#inv-31-operator-tunable-per-cli-flags-live-in-conf-not-in-lib-agentsh) — operator-tunable flags live in `autonomous.conf`. The new vars follow that contract.
 - [INV-13](#inv-13-wall-clock-cap-on-agent-invocations) — wall-clock cap. Unaffected: each side's launcher still runs inside `_run_with_timeout` exactly as before.
 
+## INV-39: Dependency parsing is list-item scoped and supports cross-repo refs
+
+**Rule**: Step 2's dependency check parses ONLY list-item lines (lines that start with `-`, `*`, or `1.` after optional leading whitespace) inside the `## Dependencies` section. Prose, blockquotes (`> ...`), and headings between `## Dependencies` and the next `## ` heading are ignored — they MUST NOT cause an issue to be blocked. On each list item, two ref shapes are recognized:
+
+- `#N` — same-repo issue/PR, resolved against `$REPO`.
+- `owner/repo#N` — cross-repo issue/PR, resolved against the named repo.
+
+Both shapes require a left boundary (start-of-line, whitespace, or `(`) so URL fragments like `https://github.com/owner/repo/issues/123` and inline punctuation don't misparse, while parenthesized refs like `(owner/repo#42)` are still recognized. The longer `owner/repo#N` shape is always matched before bare `#N` so a single ref is never double-counted.
+
+**Why**: The pre-#157 implementation greedy-extracted every `#NNN` substring between `## Dependencies` and the next `## ` heading via `grep -oE '#[0-9]+'`, then looked each one up in `$REPO`. Two related failure modes followed:
+
+1. Cross-repo refs (`owner/repo#NNN`) yielded a bare `NNN` which got queried against the wrong repo. If no such issue existed there, `gh issue view` errored, the surrounding `|| true` swallowed the error, the empty `$state` failed the `!= "CLOSED"` check, and the issue was silently blocked forever.
+2. The same greedy extraction picked up `#NNN` tokens inside prose, blockquotes, and inline-prose `owner/repo#NNN` mentions, producing identical silent blocks.
+
+List-item-only scope eliminates the prose false positives. Explicit `owner/repo#N` syntax makes cross-repo dependencies a first-class case instead of a silent failure.
+
+**Producer**: dispatcher Step 2 (`lib-dispatch.sh::check_deps_resolved`).
+
+**Consumer**: itself.
+
+**Lookup-failure semantics**: when `gh issue view` returns a non-zero exit (404 / network error / private repo the dispatcher token can't see), the resulting empty `$state` MUST be treated as fail-safe block AND emit a stderr warning naming the failed `<repo>#N`. The original #157 bug was the silent-block half of this rule; without the warning half, a typo in `owner/repo#N` would silently recreate the same bug class.
+
+**Status**: **ENFORCED** in #157's fix. The function uses `grep -E '^[[:space:]]*([-*]|[0-9]+\.)[[:space:]]'` to filter the `## Dependencies` section to list items, then bash regex `(^|[[:space:]\(])([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)#([0-9]+)` followed by `(^|[[:space:]\(])#([0-9]+)` for stage-2 extraction with a match-and-strip loop. Empty-state lookups emit a `[check_deps_resolved] WARNING: lookup failed for ...` line on stderr and return 1.
+
+**Test**: `tests/unit/test-check-deps-resolved.sh` covers cross-repo CLOSED/MERGED/OPEN, same-repo + cross-repo mixed, prose-embedded refs (must not block), blockquote refs (must not block), URL-fragment refs (must not block), and lookup-failure warning (cross-repo ref to a non-existent repo blocks AND prints the warning). The mock `gh` keys state lookups on `<repo>:<num>` so the same number resolves to different states in different repos.
+
+**Cross-references**:
+- [INV-11](#inv-11-dependency-state-includes-merged) — `state ∉ {CLOSED, MERGED}` rule applies to both same-repo and cross-repo refs.
+- The `create-issue` skill's `## Dependencies` guidance documents the user-facing parsing rules (`skills/create-issue/SKILL.md`, `skills/create-issue/references/issue-templates.md`).
+
 ## Adding a new invariant
 
 When fixing a pipeline bug, after locating the bug on the state machine + flow docs:

docs/superpowers/specs/2026-05-27-cross-repo-deps-design.md

@@ -0,0 +1,108 @@
+# Cross-repo dependency support in `check_deps_resolved`
+
+**Issue**: #157
+**Author**: zxkane
+**Date**: 2026-05-27
+**Status**: approved
+
+## Problem
+
+`check_deps_resolved` (`skills/autonomous-dispatcher/scripts/lib-dispatch.sh:286`) parses the `## Dependencies` section of an issue body by greedy-extracting every `#NNN` substring between the `## Dependencies` heading and the next `## ` heading, then looking each one up in the **current repo** via `gh issue view N --repo "$REPO"`.
+
+Two failure modes follow from this:
+
+1. **Cross-repo refs are silently treated as unresolved.** `owner/repo#NNN` in the section yields a bare `NNN`, queried against `$REPO`. If no such issue exists locally, `gh issue view` returns non-zero, the surrounding `|| true` swallows the error, `$state` is empty, and `[ "$state" != "CLOSED" ]` is true → the issue is **blocked forever**, with no log line and no comment to surface the cause.
+2. **Prose/blockquote false positives.** The regex `grep -oE '#[0-9]+'` matches every `#NNN` substring inside the line range, including ones inside blockquotes (`> requires owner/repo#4470 ...`), inline code (`` `#42` ``), and free-form prose. These leak into the loop and trigger the same silent-block failure if the number doesn't exist in `$REPO`.
+
+The function preserves [INV-11](../../pipeline/invariants.md#inv-11-dependency-state-includes-merged) (MERGED counts as resolved) and the portable extraction fix from PR-4. Both must remain green after this change.
+
+## Goals
+
+- Support `owner/repo#NNN` as a first-class dependency specifier.
+- Eliminate prose/blockquote false positives (Option B from #157).
+- Preserve INV-11 and #73 portability fixes.
+- No behavior change for issues that contain only bare `#NNN` list items.
+
+## Non-goals
+
+- URL-form refs (`https://github.com/owner/repo/issues/N`) — not in #157's acceptance criteria.
+- GitLab / Bitbucket cross-host refs.
+- Inline-code stripping (` `#42` ` on a list-item line is still extracted) — acceptable per #157 acceptance criteria; can be added later if needed.
+- Migration of existing issue bodies — old prose-style refs simply stop being parsed, which is the desired outcome.
+
+## Design
+
+### Parser rewrite (`check_deps_resolved`)
+
+Replace the current pipeline with a two-stage parse:
+
+**Stage 1 — restrict scope to list items.** Use `grep -E '^[[:space:]]*([-*]|[0-9]+\.)[[:space:]]'` to filter the `## Dependencies` section down to lines beginning with a markdown list marker. This drops blockquotes (`> ...`), prose paragraphs, and headings.
+
+**Stage 2 — extract refs with priority.** Per list-item line, scan twice:
+
+1. First, match `owner/repo#NNN` — bash regex `(^|[[:space:]\(])([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)#([0-9]+)`. The leading anchor (start-of-line, whitespace, or `(`) prevents matching inside larger tokens like `https://github.com/owner/repo#NNN`. Each hit fires `gh issue view NNN --repo owner/repo`. Strip the matched substring from the line before continuing.
+2. Then, match bare `#NNN` — bash regex `(^|[[:space:]\(])#([0-9]+)`. Each hit fires `gh issue view NNN --repo "$REPO"` (existing same-repo behavior).
+
+State check is unchanged: `state ∉ {CLOSED, MERGED}` returns 1.
+
+Stripping the matched substring after each hit is what makes "match owner/repo#N first, then bare #N on the residue" work correctly — `owner/repo#42` no longer survives stage-1 to be re-extracted as `#42` in stage 2.
+
+### Tests (`tests/unit/test-check-deps-resolved.sh`)
+
+Mock-`gh` extension: state lookups currently key on issue number. They need to key on `repo:num` so the same number in two different repos resolves independently.
+
+```bash
+gh() {
+  local mode="" issue_num="" repo=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      view) issue_num="$2"; shift 2 ;;
+      --repo) repo="$2"; shift 2 ;;
+      --json) [[ "$2" == body ]] && mode=body; [[ "$2" == state ]] && mode=state; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  case "$mode" in
+    body)  printf '%s' "$_MOCK_BODY" ;;
+    state) printf '%s' "${_MOCK_STATES[${repo}:${issue_num}]:-OPEN}" ;;
+  esac
+}
+```
+
+Existing fixtures migrate to `_MOCK_STATES[zxkane/autonomous-dev-team:42]="CLOSED"` etc. — mechanical change.
+
+New cases (numbered to match the acceptance criteria in #157):
+
+1. **Cross-repo dep, list item, CLOSED in remote** → unblocked.
+2. **Cross-repo dep, list item, OPEN in remote** → blocked.
+3. **Same-repo `#NNN` embedded in prose between headings** → unblocked (was blocked, the regression #157 is about).
+4. **Blockquote `> requires owner/repo#4470 to be merged`** → unblocked.
+5. **Mixed list: same-repo `#42` (CLOSED) + cross-repo `owner/repo#7` (OPEN)** → blocked.
+6. **Inline-code on a list item: `- waiting on \`#99\` ` ** — extracted (documented limitation; not part of #157 acceptance, but worth a regression note).
+
+The five existing test cases (no-section / single-CLOSED / single-MERGED / single-OPEN / multi-mixed / portable-extract `#73`) continue to pass.
+
+### Pipeline doc updates
+
+Per the project's "Pipeline Documentation Authority" rule, this PR also updates:
+
+1. **`docs/pipeline/invariants.md`** — extend INV-11's status block to mention "extraction is restricted to list items; cross-repo `owner/repo#N` resolves against the named repo." A new invariant (INV-NN) is unnecessary; the parsing rule is a refinement of the same dependency-resolution invariant.
+2. **`docs/pipeline/dispatcher-flow.md:165`** — change "Extract every `#N` reference" to "Extract `#N` and `owner/repo#N` references from list items only (prose and blockquotes are ignored)."
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| Bash 3.2 (macOS default) regex semantics differ from 5.x | Patterns use only POSIX char classes, no backreferences. Verify on macOS as part of test run. |
+| Existing issue bodies relying on prose extraction | None known; quick `gh issue list --search 'in:body'` audit on `zxkane/autonomous-dev-team`, `zxkane/podcast-curation`, `zxkane/Panoptes`, `zxkane/VidSyllabus`, `zxkane/llm-wiki`, `zxkane/voicebiz-editorial` to confirm no live issue would change blocked-state. |
+| `gh issue view --repo owner/repo` for a private repo the dispatcher token can't see | Returns non-zero like the same-repo case today. The current `|| true`-based silent-block is preserved for unknown / unauthorized — this is no worse than today. Future hardening could surface a comment, but is out-of-scope. |
+
+## Acceptance criteria (verbatim from #157)
+
+- [x] A same-repo dep on a list item (`- #NNN`) is checked in `$REPO` as before.
+- [x] A cross-repo dep on a list item (`- owner/repo#NNN`) is checked in `owner/repo`.
+- [x] A `#NNN` reference embedded in prose, blockquotes, or inline code between `## Dependencies` and the next heading does not cause a false block.
+- [x] `None` (or empty section with no list items) returns 0.
+- [x] Unit tests cover same-repo CLOSED/OPEN, cross-repo, prose-embedded, empty.
+
+(Inline code in a *list item* is the one carve-out, called out in Non-goals.)

skills/autonomous-dispatcher/scripts/lib-dispatch.sh

@@ -280,28 +280,69 @@ run_hygiene_pass() {
 # Returns 1 (blocked) on the first unresolved dependency. Returns 0 if no
 # dependencies are listed.
 #
-# Closes #61 (MERGED PRs report `state: "MERGED"`, not `"CLOSED"`) and
-# #73 (replace GNU-only `grep -oP '#\K[0-9]+'` with portable extraction).
-# Both fixes are in the same function and ship together.
+# Parsing rules (see INV-11 in docs/pipeline/invariants.md):
+#   - Only list-item lines (`-`, `*`, or `1.` markers) inside the
+#     `## Dependencies` section are scanned. Prose, blockquotes, and
+#     headings are ignored — this is what stops false positives where a
+#     `#NNN` mentioned in passing got greedy-extracted (#157).
+#   - Two ref shapes are recognized, longest first per line:
+#       * `owner/repo#N` → resolved against the named repo
+#       * `#N`           → resolved against $REPO (same-repo)
+#   - Both shapes require a left boundary (start-of-line or whitespace) so
+#     URL fragments (`https://github.com/.../issues/123`) and inline
+#     punctuation aren't misparsed.
+#
+# Closes #61 (MERGED PRs report `state: "MERGED"`, not `"CLOSED"`),
+# #73 (replace GNU-only `grep -oP '#\K[0-9]+'` with portable extraction),
+# and #157 (cross-repo refs + list-only scope).
 check_deps_resolved() {
   local issue_num="$1"
-  local deps state
-  # Portable dep-number extraction: grep -oE matches `#NNN`, sed strips
-  # the leading `#`. Equivalent to the GNU-only `grep -oP '#\K[0-9]+'`
-  # but works on macOS / BSD grep too.
-  deps=$(gh issue view "$issue_num" --repo "$REPO" --json body -q '.body' \
-    | sed -n '/^## Dependencies/,/^## /p' \
-    | grep -oE '#[0-9]+' \
-    | sed 's/^#//' || true)
-
-  for dep in $deps; do
-    state=$(gh issue view "$dep" --repo "$REPO" --json state -q '.state')
-    # Both CLOSED (issues, closed PRs) and MERGED (merged PRs) count as
-    # resolved. `gh issue view` on a merged PR returns state "MERGED".
-    if [ "$state" != "CLOSED" ] && [ "$state" != "MERGED" ]; then
-      return 1
-    fi
-  done
+  local body section line state dep_repo dep_num matched
+  body=$(gh issue view "$issue_num" --repo "$REPO" --json body -q '.body')
+  section=$(printf '%s\n' "$body" | sed -n '/^## Dependencies/,/^## /p')
+
+  # Stage 1: restrict to list-item lines. `grep -E` exits non-zero when
+  # nothing matches; the trailing `|| true` keeps the pipeline alive so
+  # the while loop simply runs zero times and we fall through to rc=0.
+  while IFS= read -r line; do
+    # Stage 2a: cross-repo `owner/repo#N`. Matched longest-first so that
+    # `owner/repo#42` doesn't survive to be re-parsed as bare `#42`. The
+    # left boundary `(^|[[:space:]\(])` rules out URL fragments and inline
+    # punctuation while still allowing parenthesized refs like
+    # `- (owner/repo#42)`.
+    while [[ "$line" =~ (^|[[:space:]\(])([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)#([0-9]+) ]]; do
+      matched="${BASH_REMATCH[0]}"
+      dep_repo="${BASH_REMATCH[2]}"
+      dep_num="${BASH_REMATCH[3]}"
+      state=$(gh issue view "$dep_num" --repo "$dep_repo" --json state -q '.state' 2>/dev/null || true)
+      # Empty state means the lookup failed (404, network error, private
+      # repo). [INV-39]: fail-safe blocks dispatch, but the failure must
+      # be observable — otherwise we silently recreate the #157 bug class.
+      if [ -z "$state" ]; then
+        echo "[check_deps_resolved] WARNING: lookup failed for ${dep_repo}#${dep_num} (issue ${issue_num}); blocking" >&2
+        return 1
+      fi
+      if [ "$state" != "CLOSED" ] && [ "$state" != "MERGED" ]; then
+        return 1
+      fi
+      line="${line/"$matched"/ }"
+    done
+    # Stage 2b: bare `#N` on the residue. Same-repo lookup against $REPO.
+    while [[ "$line" =~ (^|[[:space:]\(])#([0-9]+) ]]; do
+      matched="${BASH_REMATCH[0]}"
+      dep_num="${BASH_REMATCH[2]}"
+      state=$(gh issue view "$dep_num" --repo "$REPO" --json state -q '.state' 2>/dev/null || true)
+      if [ -z "$state" ]; then
+        echo "[check_deps_resolved] WARNING: lookup failed for ${REPO}#${dep_num} (issue ${issue_num}); blocking" >&2
+        return 1
+      fi
+      if [ "$state" != "CLOSED" ] && [ "$state" != "MERGED" ]; then
+        return 1
+      fi
+      line="${line/"$matched"/ }"
+    done
+  done < <(printf '%s\n' "$section" | grep -E '^[[:space:]]*([-*]|[0-9]+\.)[[:space:]]' || true)
+
   return 0
 }