@glrs-dev/cli 0.0.1 → 0.1.1

package/dist/vendor/harness-opencode/dist/agents/prompts/research.md

@@ -0,0 +1,138 @@
+---
+name: research
+description: Research orchestrator — decomposes a research query into parallel workstreams, dispatches research skills (research / research-web / research-local / research-auto) as subagents, reviews findings for gaps, iterates, and synthesizes. Use when the user asks to investigate, explore, deep-dive, or understand a complex topic that needs multiple workstreams.
+mode: all
+model: anthropic/claude-opus-4-7
+temperature: 0.3
+---
+
+# @research — Research Orchestrator Agent
+
+You are a research orchestrator. Your job is NOT to research directly — it is to plan, dispatch, review, and synthesize via subagents.
+
+**Research Query:** $ARGUMENTS
+
+## Core Principle
+
+You are an **orchestrator only**. You do NOT:
+- Use Glob, Grep, Read, or any exploration tool directly
+- Synthesize findings yourself
+- Review for gaps yourself
+- Decide workstream classifications yourself
+
+Every cognitive task is a subagent. You launch subagents and pass their outputs to other subagents.
+
+## How to Invoke Skills
+
+The four research skills are bundled with the harness:
+
+1. **`research`** (this skill) — umbrella orchestrator for multi-workstream research
+2. **`research-local`** — deep codebase research using parallel Explore subagents
+3. **`research-web`** — multi-agent web research with skeleton-file pattern
+4. **`research-auto`** — autonomous experimentation with `.lab/` directory
+
+**To invoke a skill:** Use the Agent tool with a prompt instructing the subagent to read the skill via the Skill tool:
+
+```
+Agent tool:
+"You are a research agent.
+
+## Research Query
+{the full query or sub-question}
+
+## Task
+1. Read the bundled {skill-name} skill via the Skill tool and follow every instruction
+2. Focus specifically on: {sub-question}
+3. Report back with your complete findings"
+```
+
+## 7-Phase Flow
+
+### Phase 1: Plan — Subagent
+
+Launch a **general-purpose subagent** to decompose the query into workstreams:
+
+```
+PROMPT:
+"You are a research planner. Given a research query, decompose it into workstreams
+and classify each by research type.
+
+Research Query: [QUERY]
+
+For each workstream, provide:
+1. A specific sub-question to answer
+2. Classification: LOCAL, WEB, or AUTO
+3. Why this classification (one sentence)
+4. Dependencies: which other workstreams must complete first (if any)
+
+Classification rules:
+- LOCAL: codebase architecture, data flow, patterns, implementations
+- WEB: external knowledge, best practices, market research, comparisons
+- AUTO: experimentation with measurable outcomes (RARE)
+
+Output 3-6 workstreams. Mark dependencies explicitly."
+```
+
+### Phase 2: Execute Round 1 — Parallel Agent Dispatches
+
+Dispatch **one Agent per workstream**. Launch ALL independent workstreams in a SINGLE message.
+
+For LOCAL workstreams: invoke `research-local` skill.
+For WEB workstreams: invoke `research-web` skill.
+For AUTO workstreams: invoke `research-auto` skill.
+
+### Phase 3: Review Round 1 — Subagent
+
+Launch a **general-purpose subagent** to review all findings and identify gaps.
+
+### Phase 4: Execute Round 2 — Fill Gaps (If Needed)
+
+If gaps found, dispatch gap-filling agents — ALL in ONE message.
+
+### Phase 5: Review Round 2 — Subagent (If Phase 4 Ran)
+
+Launch another review subagent with Round 1 + Round 2 findings.
+
+### Phase 6: Synthesize — Subagent
+
+Launch a **general-purpose subagent** to produce the final synthesis report.
+
+### Phase 7: Final Quality Gate — Subagent
+
+Launch a **general-purpose subagent** to score the final report (1-5 on 5 dimensions).
+
+### Phase 8: Present
+
+Present to the user:
+1. Full synthesis report
+2. Quality score
+3. Research metadata (rounds, agents dispatched, modes used)
+4. Follow-up suggestions if quality < 4.0
+
+## Parallel Dispatch Rule
+
+**ALL independent workstreams in ONE message.** Never sequential. Never one at a time.
+
+## Workflow Mechanics Exception
+
+If you realize this work should be on its own branch, do NOT ask the user. Apply the workflow-mechanics heuristic and announce the result in one line.
+
+## How to Ask the User
+
+Use the `question` tool. One question per call. Never bundle questions.
+
+## PRIME-Delegation Brief Contract
+
+When PRIME passes a brief via task tool:
+- Trust the brief. Don't re-interview on points already resolved.
+- The brief IS the research query — proceed directly to Phase 1.
+- If the brief lacks critical context (e.g., no query provided), ask once then proceed.
+
+## Red Flags — STOP
+
+- About to use Skill() directly — USE AGENT TOOL with skill-read instruction
+- About to research/synthesize/review yourself — LAUNCH A SUBAGENT
+- About to skip planning/review phases — BOTH ARE MANDATORY
+- About to launch agents sequentially — ONE MESSAGE, ALL INDEPENDENT AGENTS
+- About to present raw outputs — SYNTHESIZE FIRST
+- About to run a 4th round — MAX 3 ROUNDS, THEN PRESENT

package/dist/vendor/harness-opencode/dist/agents/shared/index.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function readMd(name: string): string {
+  // In the bundled dist/index.js, import.meta.url resolves to dist/,
+  // but the file is at dist/agents/shared/. In dev (running from src/),
+  // import.meta.url resolves to src/agents/shared/.
+  const candidates = [
+    join(HERE, name),                                          // dev: src/agents/shared/
+    join(HERE, "agents", "shared", name),                      // dist: dist/ → dist/agents/shared/
+    join(HERE, "..", "..", "..", "src", "agents", "shared", name), // fallback dev
+  ];
+  for (const p of candidates) {
+    try {
+      return readFileSync(p, "utf8");
+    } catch {
+      // try next
+    }
+  }
+  throw new Error(`Could not find shared file: ${name}`);
+}
+
+export const WORKFLOW_MECHANICS_RULE: string = readMd("workflow-mechanics.md");

package/dist/vendor/harness-opencode/dist/agents/shared/workflow-mechanics.md

@@ -0,0 +1,32 @@
+# Workflow-mechanics decisions
+
+Users run this harness so they don't have to answer questions about *mechanics*. They want the agent to decide, announce, and move. If you catch yourself about to open a `question` tool prompt asking the user which branch to use, whether to open a fresh worktree, whether this work should stack on the current branch, etc. — **stop.** Apply the heuristic below, state what you did in one line of chat (no notification), keep going.
+
+## What counts as a workflow-mechanics decision
+
+**In scope (you decide — never ask):**
+- Which branch to create or switch to for new work
+- Whether to open a fresh worktree via `/fresh` or stay on the current checkout
+- How to map a ticket ID to a branch name (Linear MCP → use its `branchName` field; otherwise derive a slug using the rules in the `/fresh` command: lowercase, replace non-alphanumeric runs with `-`, infer verb prefix `fix/`/`feat/`/`refactor/`/`docs/`/`chore/`, truncate to 50 chars)
+- Whether to isolate unrelated work onto its own branch when the user is on a feature branch
+- Which base branch to branch from (default: repo default; override only if the user's request mentions a release branch explicitly)
+
+**Out of scope (existing rules still apply — don't confuse this section with those):**
+- Deciding whether to update a plan mid-flight — existing Phase 3 rule: report and ask.
+- Deciding whether to push, open a PR, or merge — always user-initiated via `/ship`. Hard rules below are the limit.
+- Commit message wording — `/ship` auto-derives it from the plan and diff, no user review step. The user can amend after the fact if they want.
+- Content decisions (file location, symbol naming, etc.) — follow the trivial-request defaults in Phase 1.
+
+## The deterministic heuristic
+
+Evaluate these rules in order. Stop at the first match. **No "it depends."** If you're picking between branches, use this table, not judgement.
+
+1. **Trivial request** (Phase 1 "trivial" path: <20 lines, 1 file, no behavior change): stay on current branch unconditionally. No branching, no announcement. A typo fix on `main` stays on `main`.
+2. **Substantial request, on default branch (`main`/`master`/repo default)** → auto-invoke `/fresh` with the work description as `$ARGUMENTS` (and a ticket ID if you have one). Announce: `→ Workflow: starting fresh worktree via /fresh (avoiding work on default branch)`. If `/fresh` is unavailable in this harness install, fall back to `git checkout -b <slug>` from current position and announce `→ Workflow: created branch <slug> on current worktree`.
+3. **Detached HEAD** → same as rule 2. Treat detached HEAD as "not on a branch" → needs isolation.
+4. **Substantial request, on default branch, dirty tree** → abort with a single-sentence message: *"Uncommitted changes on `<branch>`; commit or stash them, then re-run."* Do NOT stash automatically — the user's WIP is theirs.
+5. **Substantial request, on a feature branch, dirty tree, work unrelated to branch** → abort: *"On feature branch `<X>` with uncommitted changes; commit or stash before starting unrelated work."*
+6. **Substantial request, on a feature branch (clean), work unrelated to branch** → create a new branch from the default: `git fetch origin && git checkout -b <slug> origin/<default-branch>`. Announce: `→ Workflow: switching from <old-branch> to new branch <slug> for unrelated work`.
+7. **Substantial request, on a feature branch, work plausibly matches the branch** (branch name references same ticket, or same feature keyword) → stay. No announcement (status quo is the expected default).
+
+Announcement format: plain chat, prefixed `→ Workflow:`. No `question` tool, no notification — notifications stay reserved for "user action required." Carve-outs: `/fresh` is a user-initiated command; its internal `--clean` prompts are legitimate. `/ship` executes end-to-end without per-step prompts once invoked (see ship.md Stop conditions for the only exceptions). This rule governs *agent-initiated* decisions only.

package/dist/vendor/harness-opencode/dist/bin/memory-mcp-launcher.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# memory-mcp-launcher.sh — resolve per-repo MEMORY_FILE_PATH and exec the memory MCP server.
+#
+# Fixes glorious-opencode issue #24: the stock @modelcontextprotocol/server-memory
+# invocation via `npx -y ... ` with a RELATIVE MEMORY_FILE_PATH resolves inside the
+# npx cache directory (because OpenCode does not set cwd for MCP launches), so every
+# project silently shares one volatile file buried in ~/.npm/_npx/<hash>/.
+#
+# This launcher resolves the project root via git (worktree-aware, submodule-aware,
+# bare-repo-aware), sets an ABSOLUTE MEMORY_FILE_PATH, ensures the target directory
+# exists, adds a narrow entry to <repo>/.agent/.gitignore so memory.json is not
+# accidentally committed, then execs the real memory server.
+#
+# CONSTRAINTS (do not break these):
+# - Must be bash 3.2 compatible (macOS default /bin/bash).
+# - MUST NOT write anything to stdout before the final `exec npx`. MCP uses stdio
+#   JSON-RPC; any stdout noise corrupts the handshake. All diagnostics go to stderr.
+# - Called via `bash "$HOME/.config/opencode/bin/memory-mcp-launcher.sh"` from the
+#   opencode.json `command` array. The executable bit is nice-to-have (stored as
+#   100755 in git via `git update-index --chmod=+x`) but not required.
+#
+# ENV CONTRACT:
+# - MEMORY_MCP_LAUNCHER_DEBUG=1
+#     After resolving MEMORY_FILE_PATH, log it to stderr as
+#     `[memory-mcp-launcher] MEMORY_FILE_PATH=<path>` and still exec npx. Useful
+#     when a user asks "where is my memory going?".
+# - MEMORY_MCP_LAUNCHER_PRINT_AND_EXIT=1
+#     Test-only. After resolving MEMORY_FILE_PATH, print it to stderr and exit 0
+#     (skipping the npx exec). Enables launcher behavior tests without needing
+#     an actual MCP handshake. Intentionally undocumented to end users.
+
+set -Eeuo pipefail
+
+# Init under -u so we can do `[[ -n "$target_path" ]]` later without risk.
+target_path=""
+fallback_path="${HOME}/.config/opencode/memory/fallback.json"
+
+# -------- resolve target --------
+# Only attempt git-based resolution if git is on PATH. If anything goes wrong in
+# this block, we drop through to the fallback path — never hard-fail on a git
+# edge case (bare repo, damaged .git, submodule, worktree with missing main, etc).
+if command -v git >/dev/null 2>&1; then
+
+  # Bare-repo check FIRST, before any path resolution. A bare repo has no
+  # working tree so per-repo memory has no sensible location — fall back.
+  _is_bare="$(git rev-parse --is-bare-repository 2>/dev/null || printf "")"
+  if [[ "$_is_bare" != "true" ]]; then
+
+    # Get the current repo's working-tree root. Always returns an absolute path.
+    # Returns empty (stderr suppressed) when:
+    #   - not in a git repo
+    #   - CWD inside the .git directory itself
+    #   - git is too old / broken
+    _toplevel="$(git rev-parse --show-toplevel 2>/dev/null || printf "")"
+
+    if [[ -n "$_toplevel" ]]; then
+      target_path="$_toplevel"
+
+      # Worktree-share rewrite. For a `git worktree`, the per-worktree toplevel
+      # differs from the MAIN worktree — but we want all worktrees of the same
+      # repo to share one memory.json. `--git-common-dir` points at the shared
+      # .git dir. Its parent is the main working tree.
+      #
+      # Resolution is CWD-sensitive (common-dir may be relative), so canonicalize
+      # inside a subshell via `cd -P && pwd -P`. Failures fall back to _toplevel.
+      _common_dir_raw="$(git rev-parse --git-common-dir 2>/dev/null || printf "")"
+      if [[ -n "$_common_dir_raw" ]]; then
+        _common_abs="$(cd -P "$_common_dir_raw" 2>/dev/null && pwd -P || printf "")"
+        if [[ -n "$_common_abs" ]]; then
+          _main_candidate="$(dirname "$_common_abs")"
+          # Only rewrite if:
+          #   (a) candidate differs from current toplevel (i.e., we're in a worktree)
+          #   (b) candidate has a .git entry (real working tree — gitfile OR dir)
+          # Submodules: their common-dir is <super>/.git/modules/<name>, parent is
+          # .git/modules which has no .git entry, so (b) rejects and we keep the
+          # submodule's own toplevel. Bare repos were already skipped above.
+          if [[ "$_main_candidate" != "$_toplevel" ]] \
+             && [[ -e "$_main_candidate/.git" ]]; then
+            target_path="$_main_candidate"
+          fi
+        fi
+      fi
+    fi
+  fi
+  unset _is_bare _toplevel _common_dir_raw _common_abs _main_candidate
+fi
+
+# -------- validate target, create dir + narrow gitignore --------
+MEMORY_FILE_PATH=""
+if [[ -n "$target_path" ]]; then
+  if mkdir -p "${target_path}/.agent" 2>/dev/null; then
+    MEMORY_FILE_PATH="${target_path}/.agent/memory.json"
+
+    # Narrow gitignore: only ignore `memory.json`. Do NOT touch the file if it
+    # already exists — the user (or an earlier run) may have set their own rules
+    # and we refuse to clobber sibling tracked content like `.agent/plans/`.
+    _gi="${target_path}/.agent/.gitignore"
+    if [[ ! -e "$_gi" ]]; then
+      _tmp_gi="$(mktemp "${target_path}/.agent/.gitignore.XXXXXX" 2>/dev/null || printf "")"
+      if [[ -n "$_tmp_gi" ]]; then
+        if printf "memory.json\n" > "$_tmp_gi" 2>/dev/null; then
+          mv "$_tmp_gi" "$_gi" 2>/dev/null || rm -f "$_tmp_gi" 2>/dev/null || true
+        else
+          rm -f "$_tmp_gi" 2>/dev/null || true
+        fi
+      fi
+      unset _tmp_gi
+    fi
+    unset _gi
+  else
+    # mkdir failed (read-only mount, perms). Fall through to fallback.
+    target_path=""
+  fi
+fi
+
+# -------- fallback path --------
+if [[ -z "$MEMORY_FILE_PATH" ]]; then
+  # Use bash parameter expansion instead of `dirname` so the launcher works on
+  # restricted PATHs (e.g., when the environment is so bare that coreutils isn't
+  # on PATH, such as a session started with env -i + a minimal PATH).
+  _fb_dir="${fallback_path%/*}"
+  if ! mkdir -p "$_fb_dir" 2>/dev/null; then
+    printf "[memory-mcp-launcher] ERROR: cannot create %s — memory server cannot run\n" "$_fb_dir" >&2
+    exit 1
+  fi
+  MEMORY_FILE_PATH="$fallback_path"
+  unset _fb_dir
+fi
+
+# -------- debug/test hooks --------
+if [[ "${MEMORY_MCP_LAUNCHER_DEBUG:-0}" == "1" ]]; then
+  printf "[memory-mcp-launcher] MEMORY_FILE_PATH=%s\n" "$MEMORY_FILE_PATH" >&2
+fi
+
+if [[ "${MEMORY_MCP_LAUNCHER_PRINT_AND_EXIT:-0}" == "1" ]]; then
+  printf "%s\n" "$MEMORY_FILE_PATH" >&2
+  exit 0
+fi
+
+# Intentionally override any pre-existing MEMORY_FILE_PATH in the env. The whole
+# purpose of this launcher is to set the correct path — if a user wants a
+# project-local override, they should set it in their project's opencode.json.
+export MEMORY_FILE_PATH
+
+exec npx -y @modelcontextprotocol/server-memory "$@"

package/dist/vendor/harness-opencode/dist/bin/plan-check.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# plan-check.sh — parse a plan file's plan-state fence and report on it.
+#
+# Modes:
+#   plan-check.sh <path>        Prints a summary line then one line per item:
+#                               `total=N done=M pending=K invalid=I`
+#                               `STATUS ID VERIFY`  (one per item)
+#
+#   plan-check.sh --run <path>  Prints the verify command of each PENDING
+#                               item on stdout, one per line, raw. The
+#                               caller is responsible for executing them.
+#                               This script NEVER executes verify commands
+#                               itself — that would bypass the caller's
+#                               bash-permission scope.
+#
+#   plan-check.sh --check <path>
+#                               Structural validation only. Exits 1 if any
+#                               fence item is missing a required field.
+#
+# Fence format, inside `## Acceptance criteria`:
+#
+#   ```plan-state
+#   - [ ] id: a1
+#     intent: Prose description of business intent (one line).
+#     tests:
+#       - path/to/test.sh::"some test name"
+#       - path/to/other.ts::"another test"
+#     verify: bash path/to/test.sh
+#
+#   - [x] id: a2
+#     ...
+#   ```
+#
+# Backward compat: a plan without a ```plan-state fence emits the line
+# `legacy` and exits 0 — callers treat it as "old format, fall back".
+#
+# Portability: POSIX bash + awk + grep only. No sed -i.
+
+set -eu
+
+MODE=""
+PLAN_PATH=""
+
+case "${1:-}" in
+  --run)   MODE=run;    PLAN_PATH="${2:-}" ;;
+  --check) MODE=check;  PLAN_PATH="${2:-}" ;;
+  -h|--help|"")
+    sed -n '2,34p' "$0"
+    exit 0
+    ;;
+  *)       MODE=summary; PLAN_PATH="${1:-}" ;;
+esac
+
+if [[ -z "${PLAN_PATH:-}" ]]; then
+  echo "plan-check.sh: missing plan path" >&2
+  exit 2
+fi
+
+if [[ ! -f "$PLAN_PATH" ]]; then
+  echo "plan-check.sh: file not found: $PLAN_PATH" >&2
+  exit 2
+fi
+
+# Extract the plan-state fence body into a temp file. awk state machine:
+# enter `## Acceptance criteria`, enter ``` plan-state, exit on next ```.
+FENCE_BODY="$(awk '
+  /^## Acceptance criteria/ { in_ac = 1; next }
+  /^## / && in_ac && !in_fence { in_ac = 0 }
+  in_ac && /^```plan-state[[:space:]]*$/ { in_fence = 1; next }
+  in_fence && /^```[[:space:]]*$/ { in_fence = 0; next }
+  in_fence { print }
+' "$PLAN_PATH")"
+
+if [[ -z "$FENCE_BODY" ]]; then
+  # No fence found — legacy plan. Report and exit cleanly.
+  if [[ "$MODE" == "summary" ]]; then
+    echo "legacy (no plan-state fence)"
+  fi
+  # --run on a legacy plan emits nothing (no commands to run).
+  # --check on a legacy plan succeeds (we're accepting legacy plans).
+  exit 0
+fi
+
+# Parse items. awk state machine:
+# - A line `- [ ] id: ID` or `- [x] id: ID` starts a new item.
+# - While inside an item, indented keys `intent:`, `tests:`, `verify:` set
+#   fields. Under `tests:`, subsequent `  - ...` lines extend the list
+#   until the next key or the next item.
+# - Items are separated by one or more blank lines OR by the next `- [`.
+#
+# We emit a tab-delimited record per item:
+#   STATUS<TAB>ID<TAB>INTENT<TAB>TESTS<TAB>VERIFY
+# TESTS is a `|`-delimited list. Missing fields are the empty string.
+PARSED="$(echo "$FENCE_BODY" | awk '
+  function flush() {
+    if (cur_id != "") {
+      # Trim trailing/leading whitespace on each field
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", cur_intent)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", cur_verify)
+      gsub(/^\||\|$/, "", cur_tests)
+      printf "%s\t%s\t%s\t%s\t%s\n", cur_status, cur_id, cur_intent, cur_tests, cur_verify
+    }
+    cur_status = ""; cur_id = ""; cur_intent = ""; cur_tests = ""; cur_verify = ""
+    in_tests = 0
+  }
+
+  /^-[[:space:]]+\[[[:space:]xX[:space:]]\][[:space:]]+id:/ {
+    flush()
+    status = $0
+    sub(/^-[[:space:]]+\[[[:space:]]*/, "", status)
+    sub(/\].*$/, "", status)
+    # status is either empty/space (" ") -> pending, or "x"/"X" -> done
+    if (status ~ /[xX]/) cur_status = "done"; else cur_status = "pending"
+    # Capture id
+    id_part = $0
+    sub(/^.*id:[[:space:]]*/, "", id_part)
+    cur_id = id_part
+    next
+  }
+
+  /^[[:space:]]*intent:/ {
+    field = $0
+    sub(/^[[:space:]]*intent:[[:space:]]*/, "", field)
+    cur_intent = field
+    in_tests = 0
+    next
+  }
+
+  /^[[:space:]]*intent\b/ {
+    # already handled
+    next
+  }
+
+  /^[[:space:]]*tests:/ {
+    in_tests = 1
+    next
+  }
+
+  /^[[:space:]]*verify:/ {
+    field = $0
+    sub(/^[[:space:]]*verify:[[:space:]]*/, "", field)
+    cur_verify = field
+    in_tests = 0
+    next
+  }
+
+  # Continuation lines inside tests: list
+  in_tests && /^[[:space:]]+-[[:space:]]/ {
+    line = $0
+    sub(/^[[:space:]]+-[[:space:]]+/, "", line)
+    if (cur_tests == "") cur_tests = line
+    else cur_tests = cur_tests "|" line
+    next
+  }
+
+  # Continuation line for intent (indented without `-`, after intent is set
+  # and before another key). Append with a space separator.
+  !in_tests && /^[[:space:]]{4,}[^-[:space:]]/ && cur_id != "" && cur_intent != "" && cur_verify == "" {
+    line = $0
+    sub(/^[[:space:]]+/, "", line)
+    cur_intent = cur_intent " " line
+    next
+  }
+
+  END { flush() }
+' 2>&1)"
+
+# If PARSED contains awk errors, surface them as invalid.
+if echo "$PARSED" | grep -q '^awk:'; then
+  echo "plan-check.sh: parser error" >&2
+  echo "$PARSED" >&2
+  exit 3
+fi
+
+# Count totals.
+total=0
+done_count=0
+pending_count=0
+invalid_count=0
+invalid_reasons=()
+
+while IFS=$'\t' read -r status id intent tests verify; do
+  [[ -z "$status" ]] && continue
+  total=$((total + 1))
+  if [[ -z "$id" ]]; then
+    invalid_count=$((invalid_count + 1))
+    invalid_reasons+=("missing id")
+    continue
+  fi
+  if [[ -z "$intent" ]]; then
+    invalid_count=$((invalid_count + 1))
+    invalid_reasons+=("$id: missing intent")
+    continue
+  fi
+  if [[ -z "$tests" ]]; then
+    invalid_count=$((invalid_count + 1))
+    invalid_reasons+=("$id: missing tests")
+    continue
+  fi
+  if [[ -z "$verify" ]]; then
+    invalid_count=$((invalid_count + 1))
+    invalid_reasons+=("$id: missing verify")
+    continue
+  fi
+  if [[ "$status" == "done" ]]; then
+    done_count=$((done_count + 1))
+  else
+    pending_count=$((pending_count + 1))
+  fi
+done <<< "$PARSED"
+
+case "$MODE" in
+  summary)
+    printf 'total=%d done=%d pending=%d invalid=%d\n' \
+      "$total" "$done_count" "$pending_count" "$invalid_count"
+    while IFS=$'\t' read -r status id intent tests verify; do
+      [[ -z "$status" ]] && continue
+      # For the summary-per-item line, prefer displaying the verify
+      # command (truncated) so the reader sees what gates each item.
+      v="${verify:0:60}"
+      if [[ -n "$verify" && ${#verify} -gt 60 ]]; then v="${v}…"; fi
+      printf '%s %s %s\n' "$status" "$id" "$v"
+    done <<< "$PARSED"
+    if [[ "$invalid_count" -gt 0 ]]; then
+      echo "invalid:"
+      for r in "${invalid_reasons[@]}"; do
+        echo "  $r"
+      done
+    fi
+    ;;
+
+  run)
+    # Emit verify command per PENDING item, one per line. Skip done items,
+    # skip invalid items. Caller executes via their own bash permission.
+    while IFS=$'\t' read -r status id intent tests verify; do
+      [[ -z "$status" ]] && continue
+      [[ "$status" == "done" ]] && continue
+      [[ -z "$verify" ]] && continue
+      [[ -z "$intent" || -z "$tests" ]] && continue
+      echo "$verify"
+    done <<< "$PARSED"
+    ;;
+
+  check)
+    # Structural validation. Exit 1 if anything invalid.
+    if [[ "$invalid_count" -gt 0 ]]; then
+      echo "plan-check: $invalid_count invalid item(s):" >&2
+      for r in "${invalid_reasons[@]}"; do
+        echo "  $r" >&2
+      done
+      exit 1
+    fi
+    printf 'ok: %d item(s) pass structural validation\n' "$total"
+    ;;
+esac