project-init 0.3.0__tar.gz → 0.5.0__tar.gz

{project_init-0.3.0/templates/base/dot_claude → project_init-0.5.0/.claude}/hooks/dag_workflow.py

@@ -5,8 +5,9 @@ Subcommands:
   check <node>          exit 0 if every prerequisite of <node> is satisfied,
                         exit 2 otherwise (with reason on stdout).
   guard                 read PreToolUse hook input JSON from stdin, map the
-                        Bash command to a target node, emit
-                        {decision: block, reason: ...} if disallowed.
+                        Bash command to a target node, emit a PreToolUse
+                        hookSpecificOutput with permissionDecision: deny if
+                        disallowed (the documented Claude Code schema).
   nodes                 list every DAG node and its prerequisites.
   push [<branch>] [N]   push current (or named) branch with retry + remote-SHA
                         verification (handles transient GitHub 5xx).
@@ -239,12 +240,16 @@ def prereqs_satisfied(node: str, _seen: set[str] | None = None) -> tuple[bool, s
 # DAG validation; otherwise, prereqs of target_node are appended to the reason.
 COMMAND_RULES: list[tuple[re.Pattern[str], str | None, str]] = [
     (
-        re.compile(r"git\s+push\s+(?:\S+\s+)?(?:origin\s+)?(?:main|master)\b"),
+        re.compile(r"git\s+push\b[^|;&\n]*?[\s:]['\"]?(?:refs/heads/)?(?:main|master)(?![\w./-])"),
         None,
         "Direct pushes to main/master are blocked. Open a feature branch and PR.",
     ),
     (
-        re.compile(r"\bgh\s+api\s+repos/[^/\s]+/[^/\s]+/pulls/\d+/merge\b"),
+        # `[^&;]*?` allows flags between `gh api` and the endpoint (a real merge
+        # needs `--method PUT`/`-X PUT`, often written before the path). `|` is NOT
+        # excluded: a pipe inside a quoted flag (e.g. `--jq '.a|.b'`) must not let a
+        # merge slip past the guard — only `;`/`&` end the command segment (PI-198).
+        re.compile(r"\bgh\s+api\b[^&;]*?repos/[^/\s]+/[^/\s]+/pulls/\d+/merge\b"),
         "pr.merged",
         "Use .claude/scripts/monitor_pr.sh <pr> --merge instead of `gh api .../merge` so CI and review gates are honored.",
     ),
@@ -300,7 +305,19 @@ def _redirect_target_exists(reason: str) -> bool:
     m = re.search(r"\.claude/scripts/([\w.-]+)", reason)
     if not m:
         return True
-    return (Path(".claude/scripts") / m.group(1)).exists()
+    # Resolve the PROJECT's wrapper-scripts dir, never the process CWD (#429).
+    # Prefer $CLAUDE_PROJECT_DIR — Claude Code sets it on every hook invocation,
+    # including the default plugin mode where this file lives under the plugin
+    # root, not the project (#447 review). Otherwise — the codex/cursor/
+    # antigravity adapter path, which runs the project's own .claude/hooks/ copy
+    # and sets no such var — anchor on this file's location (.claude/hooks ->
+    # .claude/scripts). Mirrors prod_guard.py's project-root resolution.
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if project_dir:
+        scripts_dir = Path(project_dir) / ".claude" / "scripts"
+    else:
+        scripts_dir = Path(__file__).resolve().parent.parent / "scripts"
+    return (scripts_dir / m.group(1)).exists()
 
 
 def guard(payload: dict) -> dict | None:
@@ -325,7 +342,13 @@ def guard(payload: dict) -> dict | None:
             ok, why = prereqs_satisfied(target)
             if not ok:
                 reason = f"{message}\n\nDAG prerequisite for {target} not met: {why}."
-        return {"decision": "block", "reason": reason}
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
     return None
 
 
@@ -339,7 +362,7 @@ def cmd_check(node: str) -> int:
         own_ok, own_reason = CHECKS[node]()
         marker = "OK" if own_ok else "REACHABLE (state not yet satisfied)"
         sys.stdout.write(f"{marker}: {node} — {own_reason}\n")
-        return 0 if own_ok else 0  # prereqs satisfied = transition allowed
+        return 0  # prereqs satisfied = transition allowed (own check is advisory)
     sys.stdout.write(f"BLOCKED: cannot reach {node}: {reason}\n")
     return 2
 
@@ -380,8 +403,12 @@ def cmd_push(branch: str | None, max_retries: int, *, force: bool = False) -> in
     if not branch:
         sys.stderr.write("push: no current branch\n")
         return 1
-    if force and branch in ("main", "master"):
-        sys.stderr.write("push: refusing to force-push main/master\n")
+    if branch in ("main", "master"):
+        # Refuse main/master for ANY push, not only force-pushes — otherwise
+        # running push_branch.sh while on main bypasses the direct-push guard,
+        # since the internal `git push` subprocess is invisible to the
+        # PreToolUse hook (PI-202).
+        sys.stderr.write("push: refusing to push main/master directly — open a feature branch + PR\n")
         return 1
 
     code, sha_out = _git(["rev-parse", branch])
@@ -455,18 +482,49 @@ def cmd_promote(pr_number: int | None) -> int:
 
 def cmd_finish(pr_number: int | None, review_cycle: int | None) -> int:
     """Push, promote, then hand off to monitor_pr.sh for CI/review/merge."""
-    rc = cmd_push(None, 3)
-    if rc != 0:
-        return rc
+    # Resolve the PR BEFORE pushing so we push that PR's head branch, never
+    # whatever happens to be checked out. Pushing the current branch first let
+    # a concurrent branch switch make `finish` push an unrelated branch (PI-458).
     if pr_number is None:
         pr_number = _detect_pr_number()
     if pr_number is None:
         sys.stderr.write("finish: no PR found for current branch.\n")
         return 1
+    code, head = _gh(
+        ["pr", "view", str(pr_number), "--json", "headRefName", "-q", ".headRefName"]
+    )
+    head = head.strip()
+    if code != 0 or not head:
+        sys.stderr.write(
+            f"finish: cannot resolve head branch for PR #{pr_number} — refusing to push.\n"
+        )
+        return 1
+    current = _current_branch()
+    if current is None:
+        sys.stderr.write(
+            f"finish: no current branch (detached HEAD or not a git repo) — check out "
+            f"PR #{pr_number}'s head '{head}' and re-run.\n"
+        )
+        return 1
+    if current != head:
+        sys.stderr.write(
+            f"finish: checked-out branch '{current}' is not PR #{pr_number}'s head "
+            f"'{head}'. Check out '{head}' and re-run — refusing to push the wrong branch.\n"
+        )
+        return 1
+    rc = cmd_push(head, 3)
+    if rc != 0:
+        return rc
     rc = cmd_promote(pr_number)
     if rc != 0:
         return rc
-    monitor_args = [".claude/scripts/monitor_pr.sh", str(pr_number), "--merge"]
+    # Invoke via an explicit `bash` on an absolute path instead of exec'ing the
+    # .sh directly (PI-361): that avoids depending on the script's executable
+    # bit or shebang resolution (fragile on native Windows / Git Bash) and on
+    # the current working directory. cmd_finish always runs from the scaffolded
+    # .claude/hooks/ copy, so ../scripts/monitor_pr.sh resolves in every mode.
+    script = Path(__file__).resolve().parent.parent / "scripts" / "monitor_pr.sh"
+    monitor_args = ["bash", str(script), str(pr_number), "--merge"]
     if review_cycle is not None:
         monitor_args += ["--review-cycle", str(review_cycle)]
     return subprocess.run(monitor_args).returncode
@@ -538,6 +596,7 @@ def cmd_create_pr_nojira(
     # Conventional Commits, no scope = no linked issue (ADR-006)
     pr_title = f"{type_}: {title}"
     pr_body = "No linked issue (nojira)."
+    # Single trunk: with no explicit --base, gh targets the repo default branch.
     args = ["pr", "create", "--draft", "--title", pr_title, "--body", pr_body]
     if base:
         args += ["--base", base]

{project_init-0.3.0 → project_init-0.5.0}/.claude/hooks/workflow_state_reminder.sh

@@ -68,5 +68,5 @@ context = (
     f"{state_block}"
 )
 
-print(json.dumps({"additionalContext": context}))
+print(json.dumps({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": context}}))
 '

{project_init-0.3.0/templates/base/dot_claude → project_init-0.5.0/.claude}/scripts/monitor_pr.sh

@@ -63,7 +63,11 @@ import json, sys
 data = json.load(sys.stdin)
 # Exclude review/decision; it is a derived commit status that only appears
 # after a review event. We detect review state directly via reviewDecision.
-print(sum(1 for c in data if c.get('name') != 'review/decision' and c.get('state') in ('PENDING', 'IN_PROGRESS', 'EXPECTED')))
+# Gate on gh's authoritative 'bucket' rollup (pass/fail/pending/skipping/
+# cancel), not a hand-rolled state allowlist: just-queued Actions report
+# state=QUEUED (and WAITING/REQUESTED for env-gated jobs), all bucket=pending.
+# An allowlist that omitted those let the CI-wait break before CI ran (#428).
+print(sum(1 for c in data if c.get('name') != 'review/decision' and c.get('bucket') == 'pending'))
 "
 }
 
@@ -146,14 +150,28 @@ _has_review_activity() {
 # --- Wait for all CI checks (excludes review/decision commit status) ---
 # Guard: if checks haven't registered yet (empty list), keep polling.
 # An empty list is indistinguishable from "all done" without this guard,
-# which caused premature merges before CI even started.
+# which caused premature merges before CI even started. Bounded by CI_TIMEOUT
+# so a required check that never registers can't hang the script — and any
+# autonomous caller — forever; fail closed on timeout (PI-186/PI-203).
+CI_TIMEOUT=900
+CI_ELAPSED=0
 while true; do
   CHECKS=$(gh pr checks "$PR_NUMBER" --json name,state,bucket 2>/dev/null) || CHECKS="[]"
   CHECK_COUNT=$(echo "$CHECKS" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))")
-  [ "$CHECK_COUNT" -eq 0 ] && { sleep 10; continue; }
-  PENDING=$(_count_pending "$CHECKS")
-  [ "$PENDING" -eq 0 ] && break
+  if [ "$CHECK_COUNT" -gt 0 ] && [ "$(_count_pending "$CHECKS")" -eq 0 ]; then
+    break
+  fi
+  if [ "$CI_ELAPSED" -ge "$CI_TIMEOUT" ]; then
+    echo "PR #$PR_NUMBER: CI did not settle within ${CI_TIMEOUT}s. Still pending:"
+    echo "$CHECKS" | python3 -c "import json,sys
+for c in json.load(sys.stdin):
+    if c.get('name') != 'review/decision' and c.get('bucket') == 'pending':
+        print('  -', c.get('name'))" 2>/dev/null || true
+    echo "Re-run once the check registers, or investigate why it never started."
+    exit 1
+  fi
   sleep 10
+  CI_ELAPSED=$((CI_ELAPSED + 10))
 done
 
 FAIL_CODE=0

{project_init-0.3.0 → project_init-0.5.0}/.claude/skills/INDEX.md

@@ -11,6 +11,7 @@ Load the relevant skill file when the trigger applies. Do not load all skills at
 | Summarize the session | `.claude/skills/session_summary/SKILL.md` |
 | Add a hook | `.claude/skills/add_hook/SKILL.md` |
 | Add a slash command | `.claude/skills/add_command/SKILL.md` |
+| Live E2E test the scaffolder (build+install wheel, scaffold real projects, use them) | `.claude/skills/live_test/SKILL.md` (user-only: `/live_test`) |
 
 ## Note for this repo
 

{project_init-0.3.0 → project_init-0.5.0}/.claude/skills/README.md

@@ -6,8 +6,11 @@ Project-local Claude Code skills. Each skill is a directory `.claude/skills/<nam
 |---|---|
 | `session_summary` | End of session — summarize work and save to vault |
 | `start_task` | Before any non-trivial task — create a GitHub Issue |
+| `github_workflow` | Any push, PR, review-response, or merge action |
+| `wiki` | Publish or update GitHub Wiki pages |
 | `add_hook` | When you need a new deterministic hook (safety, lint, logging) |
 | `add_command` | When you need a new slash command for a recurring workflow |
+| `live_test` | User-only `/live_test` — live E2E: build+install the wheel, scaffold real projects, and use them to surface bugs pytest can't |
 
 See `INDEX.md` for a trigger-based lookup table.
 

project_init-0.5.0/.claude/skills/add_command/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: add_command
+description: Creates a new slash command (skill) that users can invoke with /name. Use when asked to add a command, automate a repeatable workflow step, or expose a task as a /name shortcut.
+when_to_use: Use when the user says "add a /command", "make a shortcut for X", or "I want to run this with a slash command".
+argument-hint: "<command-name> <what it does>"
+allowed-tools: Write
+---
+
+## Create a skill
+
+Slash commands in this project live in `.claude/skills/<name>/SKILL.md`. Each skill is a markdown file with YAML frontmatter.
+
+## Step 0 — Confirm the current schema (best-effort)
+
+The frontmatter fields below are a snapshot and can lag Claude Code releases.
+**If** a docs-lookup tool is available to you — the Context7 MCP, or WebFetch
+when it's permitted — confirm the field name / value against the current
+reference (<https://docs.claude.com/en/docs/claude-code/slash-commands>) before
+relying on it. This skill's `allowed-tools` does not grant those tools, so skip
+this step cleanly whenever the tool is unavailable, unapproved, egress is
+disabled (`--no-egress` / air-gapped), or the lookup fails — fall back to the
+embedded reference below. Don't request extra permissions and never block on it.
+
+## Step 1 — Create the file
+
+Create `.claude/skills/<name>/SKILL.md` where `<name>` is the command name (lowercase, hyphen-separated).
+
+## Step 2 — Write the frontmatter
+
+```yaml
+---
+name: <name>
+description: <What it does and when to use it. Third person. Include trigger keywords.>
+when_to_use: <Extra trigger context — action phrases the user might say.>
+argument-hint: "<expected arguments>"
+allowed-tools: Bash Read Write   # tools pre-approved while this skill is active
+model: <model-id>                # optional override — provider-specific (e.g. sonnet/opus on Claude)
+effort: medium                   # low | medium | high | xhigh | max
+disable-model-invocation: true   # true = user-only; Claude won't auto-invoke
+user-invocable: false            # false = Claude-only background knowledge
+context: fork                    # fork = runs in isolated subagent
+---
+```
+
+Not all fields are required — only include what changes the default behaviour.
+
+## Step 3 — Write the body
+
+```markdown
+Run this command to <what it does>.
+
+## Steps
+
+1. <step one — prefer shell commands over prose>
+2. <step two>
+
+## Rules
+
+- <constraint if any>
+```
+
+**`$ARGUMENTS`** expands to the full argument string. Use `$1`, `$2` for positional args.
+
+## Guidelines
+
+- **Name**: lowercase, hyphen-separated, max 64 chars
+- **Description quality is load-bearing**: if Claude doesn't trigger it automatically, the description is too vague — add keywords users would naturally say
+- **No file reads in the body**: embed what the agent needs inline; don't say "read X first"
+- **Side-effect commands**: set `disable-model-invocation: true` so only the user can invoke them
+- **Background conventions**: set `user-invocable: false` so Claude loads them automatically

{project_init-0.3.0/templates/codex/dot_agents → project_init-0.5.0/.claude}/skills/add_hook/SKILL.md

@@ -6,9 +6,16 @@ argument-hint: "<hook-name> <event> <description>"
 allowed-tools: Read Write Bash
 ---
 
-> **Claude Code specific**: this skill manages Claude Code configuration
-> (settings.json wiring). Other agents do not consume what it produces.
+## Step 0 — Confirm the current schema (best-effort)
 
+The event names and output schema below are a snapshot and can lag Claude Code
+releases. **If** a docs-lookup tool is available to you — the Context7 MCP, or
+WebFetch when it's permitted — confirm the event name / output field against the
+current reference (<https://docs.claude.com/en/docs/claude-code/hooks>) before
+relying on it. This skill's `allowed-tools` does not grant those tools, so skip
+this step cleanly whenever the tool is unavailable, unapproved, egress is
+disabled (`--no-egress` / air-gapped), or the lookup fails — fall back to the
+embedded reference below. Don't request extra permissions and never block on it.
 
 ## Step 1 — Choose an event
 
@@ -18,20 +25,24 @@ Pick the event that matches when the hook should fire:
 - `PreToolUse` — before a tool runs; output block JSON to block it
 - `PostToolUse` — after a tool runs; cannot block, can log or validate
 - `PostToolBatch` — after a batch of parallel tool calls completes
+- `PostToolUseFailure` — after a tool fails
 - `PermissionRequest` — when Claude asks for permission; can auto-approve
+- `PermissionDenied` — when permission is denied; can request a retry
 
 **Session lifecycle:**
 - `SessionStart` — when a session begins
+- `SessionEnd` — when a session closes
+- `PreCompact` — before context compaction (can block)
 - `Stop` — when Claude stops generating (end of turn)
 - `StopFailure` — when a turn fails
 
 **User input:**
 - `UserPromptSubmit` — when the user submits a prompt
-- `UserPromptExpansion` — when slash commands expand
+- `UserPromptExpansion` — when a typed command expands into a prompt (can block)
 
-**Agent/task events:**
+**Agent / task events:**
 - `SubagentStart` / `SubagentStop` — subagent lifecycle
-- `TaskCreated` / `TaskCompleted` — task tracking events
+- `TaskCreated` / `TaskCompleted` — task lifecycle (via `TaskCreate` / completion)
 
 **File/config events:**
 - `FileChanged`, `CwdChanged`, `ConfigChange`
@@ -46,7 +57,8 @@ Create `.claude/hooks/<name>.sh`:
 INPUT=$(cat)
 
 # exit 0 = allow (or no-op for non-blocking events)
-# stdout JSON with {"decision":"block","reason":"..."} = block (PreToolUse)
+# PreToolUse block: stdout JSON {"hookSpecificOutput":{"hookEventName":
+#   "PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}
 # stdout JSON with {"additionalContext":"..."} = inject context
 # Always exit 0 — exit 1 means hook error, not a block
 
@@ -63,7 +75,7 @@ print((data.get('tool_input', {}) or {}).get('command', '') or '')
 [ -z "$CMD" ] && exit 0
 
 if echo "$CMD" | grep -qE 'git push.*(main|master)'; then
-  python3 -c "import json,sys; print(json.dumps({'decision':'block','reason':sys.argv[1]}))" \
+  python3 -c "import json,sys; print(json.dumps({'hookSpecificOutput':{'hookEventName':'PreToolUse','permissionDecision':'deny','permissionDecisionReason':sys.argv[1]}}))" \
     "Direct push to main is not allowed. Use a branch and PR."
   exit 0
 fi

project_init-0.5.0/.claude/skills/live_test/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: live_test
+description: Live E2E of the scaffolder — build+install the wheel, scaffold real mini-projects, and *use* them to surface bugs the pytest suite can't. Drives the real install path, exercises hooks/guards in the correct mode, walks the local git/PR lifecycle against a stubbed gh, and writes a severity-ranked REPORT.md.
+when_to_use: Use when the user says "/live_test", "run the live E2E", "live-test the scaffolder", or wants to validate that scaffolded projects actually work end-to-end (not just that pytest passes).
+argument-hint: "[--matrix=1,2,3] [--keep]"
+allowed-tools: Bash Read Write Glob Grep
+disable-model-invocation: true
+effort: high
+---
+
+Run a live end-to-end test of the **project-init scaffolder**. Deterministic pytest
+coverage (`tests/smoke/test_packaging.py`, the `wheel-smoke` CI job, ~70 contract tests)
+already proves files land with the right exec bits. This command tests what those can't:
+whether a **scaffolded project actually works in real use** — do its hooks fire, do
+lifecycle scripts run, does `just ci` pass, would an agent landing in the project find
+coherent instructions. It captures the manual 0.4.0 "external live test" (which found 13
+real bugs, epics #440–444) as a repeatable procedure.
+
+It builds the wheel once, installs it into a throwaway venv, scaffolds a representative
+matrix of mini-projects, fans out **one isolated subagent per project** to exercise four
+depths, and aggregates a timestamped severity-ranked `REPORT.md`. **No GitHub side effects,
+no auto-issue-filing, no merge path.**
+
+## Execution model (with fallback)
+
+The default is a **parallel one-subagent-per-project fan-out** (general-purpose or Explore
+subagent). If the subagent/Task tool is unavailable or refused, **fall back to a serial
+single-agent loop** that runs the same per-project steps and writes the same `result.json`
+files. The fan-out is an optimization, not a hard dependency.
+
+Claude (the orchestrator) runs Steps 1–3 centrally, fans out Step 4, then runs Steps 5–6
+after the barrier.
+
+## Steps
+
+Define the run root up front and print it before any fan-out:
+
+```bash
+RUNID="${1:-$(date +%s 2>/dev/null || echo run)}"   # arg wins; never rely on a clock for correctness
+RUN="${SCRATCHPAD:-$(mktemp -d)}/live-test-$RUNID"
+mkdir -p "$RUN"/{build,logs}
+echo "RUN=$RUN"
+```
+
+### 1. Build once, isolated
+
+From the repo root, gate on `uv` (mirror `has_uv_and_can_build()` in `tests/helpers.py`;
+if `uv` is absent, print a clear skip message and stop — nothing else can run).
+
+```bash
+command -v uv >/dev/null || { echo "SKIP: uv not installed — cannot build wheel"; exit 0; }
+uv build --wheel -o "$RUN/build"                 # single FRESH wheel — never dist/*.whl (can be stale)
+uv venv "$RUN/venv"
+uv pip install --python "$RUN/venv" "$RUN"/build/*.whl
+PI="$RUN/venv/bin/project-init"                   # resolved installed binary
+"$PI" --version
+```
+
+### 2. Build the stateful local GitHub stub
+
+Create `"$RUN/stub-bin/gh"` — a **stateful** stub that logs every argv to a per-project log
+and returns canned responses for every shape the *exercised* lifecycle scripts use. Clear
+`GH_TOKEN`/`GITHUB_*` and prepend the stub dir to `PATH` so `gh` can **never** reach the real
+API. Each subagent asserts `command -v gh` resolves to the stub before running anything.
+
+**The stub command→response table is the source of truth — embed it, don't leave it to future
+diligence.** Enumerated from `create_issue.sh`, `start_issue.sh`, `push_branch.sh` /
+`promote_review.sh` (both shim to `dag_workflow.py`). The merge/monitor path (`monitor_pr.sh`,
+`gh pr checks` / `gh pr merge` / `gh api .../pulls/.../comments`) is **intentionally out of
+scope** (see Step 4 lifecycle), so its `gh` shapes are deliberately absent from this table:
+
+| `gh` invocation | Canned response (stdout) |
+|---|---|
+| `gh repo view --json owner -q .owner.login` | `livetest-owner` |
+| `gh repo view --json name -q .name` | `<project>` |
+| `gh repo view --json nameWithOwner ...` | `livetest-owner/<project>` |
+| `gh repo view --json url -q .url` | `https://example.invalid/livetest-owner/<project>` |
+| `gh label list --search <n> --json name -q '.[].name'` | empty (label absent → caller creates it) |
+| `gh label create <n> ...` | exit 0, no output |
+| `gh issue create ...` | `https://example.invalid/.../issues/101` |
+| `gh issue view <n> --json title -q '.title'` | `Stubbed issue` |
+| `gh api .../issues/<n> --jq '.node_id'` | `I_stubnode101` |
+| `gh api graphql -f query=...` | `{"data":{}}` (project-board mutations no-op) |
+| `gh pr create ...` | `https://example.invalid/.../pull/202` |
+| `gh pr view <n> --json isDraft -q .isDraft` | `true` |
+| `gh pr view <n> --json headRefName -q .headRefName` | the current branch name |
+| `gh pr view <n> --json url -q .url` | `https://example.invalid/.../pull/202` |
+| `gh pr view --json number,state` | `{"number":202,"state":"OPEN"}` (PR auto-detect, `check_pr_opened`) |
+| `gh pr view --json number -q .number` | `202` (bare PR-number auto-detect, e.g. `promote_review.sh`) |
+| `gh pr view --json number,reviewDecision` | `{"number":202,"reviewDecision":""}` |
+| `gh pr ready <n>` | exit 0, no output |
+| anything else | log argv, exit 0, empty stdout |
+
+A reference generator for the stub (the skill writes this file, then `chmod +x`):
+
+```bash
+mkdir -p "$RUN/stub-bin"                          # the redirect below needs this dir to exist
+cat > "$RUN/stub-bin/gh" <<'STUB'
+#!/usr/bin/env bash
+echo "gh $*" >> "${GH_STUB_LOG:-/dev/null}"
+proj="${GH_STUB_PROJECT:-proj}"; branch="$(git branch --show-current 2>/dev/null || echo main)"
+case "$*" in
+  "repo view --json owner"*)        echo "livetest-owner" ;;
+  "repo view --json name"*)         echo "$proj" ;;
+  "repo view --json nameWithOwner"*) echo "livetest-owner/$proj" ;;
+  "repo view --json url"*)          echo "https://example.invalid/livetest-owner/$proj" ;;
+  "label list"*)                    : ;;                         # empty → caller creates
+  "label create"*)                  : ;;
+  "issue create"*)                  echo "https://example.invalid/livetest-owner/$proj/issues/101" ;;
+  "issue view"*"title"*)            echo "Stubbed issue" ;;
+  "api graphql"*)                   echo '{"data":{}}' ;;
+  "api"*"node_id"*)                 echo "I_stubnode101" ;;
+  "pr create"*)                     echo "https://example.invalid/livetest-owner/$proj/pull/202" ;;
+  "pr view"*"isDraft"*)             echo "true" ;;
+  "pr view"*"headRefName"*)         echo "$branch" ;;
+  "pr view"*"number,state"*)        echo '{"number":202,"state":"OPEN"}' ;;   # check_pr_opened / PR auto-detect
+  "pr view"*"reviewDecision"*)      echo '{"number":202,"reviewDecision":""}' ;;
+  "pr view"*"url"*)                 echo "https://example.invalid/livetest-owner/$proj/pull/202" ;;
+  "pr view"*"number"*)              echo "202" ;;                 # bare --json number -q .number (promote_review auto-detect); after the number,state/reviewDecision cases so they win first
+  "pr ready"*)                      : ;;
+  *)                                : ;;
+esac
+STUB
+chmod +x "$RUN/stub-bin/gh"
+```
+
+Per subagent: `export GH_STUB_LOG="$RUN/<proj>/gh.log" GH_STUB_PROJECT="<proj>"`,
+`export PATH="$RUN/stub-bin:$PATH"`, `unset GH_TOKEN GITHUB_TOKEN GITHUB_ACTIONS`.
+
+**Validation boundary:** plugin-mode hook execution validates the **repo plugin payload**
+(`plugins/project-init-workflow/hooks/*` from the source checkout); the installed wheel
+validates **scaffolder/template installation**. Keep these distinct in findings so a
+plugin-source drift isn't reported as a wheel-install failure.
+
+### 3. Scaffold the matrix (default ~5, representative — each hits a distinct path)
+
+All non-interactive, `--non-interactive --strict --name <n> --description <d>`. `--matrix=`
+selects a subset by number.
+
+1. `--preset obsidian-only --language python` (**plugin mode** — designate this the
+   plugin-mode hook-resolution project; see depth 2)
+2. `--preset obsidian-graphify --language node --no-plugin`
+3. `--preset governed --language python --governance --observability`
+4. `--preset obsidian-only --language go --delivery service --deploy cloud-run --iac opentofu`
+5. `--preset obsidian-only --language python --agents claude,codex,cursor,antigravity --multi-model --mcps context7 --browser`
+
+**+ 1 interactive smoke:** drive the *full* wizard prompt sequence via piped stdin (the real
+sequence in `main()` / the interactive gather path — **not** the leaf helpers in
+`test_interactive_prompts.py`, which don't cover the full flow). Feed Enter-defaults; a
+prompt-order mismatch is a **finding**, not a crash.
+
+```bash
+"$PI" --non-interactive --strict --preset obsidian-only --language python \
+      --name lt1 --description "live-test project 1" "$RUN/proj1"
+```
+
+### 4. Fan out — one isolated subagent per mini-project
+
+Each subagent gets: its project dir, its own `PATH` with the stub `gh` + per-project
+`GH_STUB_LOG`, its own **local bare remote**, and **must write `"$RUN/<proj>/result.json"`**.
+It first asserts `command -v gh` resolves to the stub. **Wrap every external command in an
+explicit `timeout`**; a timeout is a finding with captured stdout/stderr paths.
+
+**Shared per-project git bootstrap — run ONCE before both the gate and lifecycle depths,
+idempotently:** `git init`, an initial `main` commit, `git init --bare "$RUN/<proj>.git"`
+added as `origin`. Both `just scan` (needs a repo + staged content) and the lifecycle walk
+reuse this single bootstrap. `push_branch.sh`'s real `git push -u origin` then succeeds
+offline against the bare remote.
+
+`result.json` schema (fixed):
+
+```json
+{
+  "project": "proj1",
+  "depths": {
+    "gates":     {"status": "pass|fail|skipped", "note": ""},
+    "hooks":     {"status": "pass|fail|skipped", "note": ""},
+    "lifecycle": {"status": "pass|fail|skipped", "note": ""},
+    "read":      {"status": "pass|fail|skipped", "note": ""}
+  },
+  "findings": [
+    {"severity": "P1|P2|P3", "what": "", "repro": "", "suspected_file": "", "fix_sketch": ""}
+  ]
+}
+```
+
+The four depths:
+
+- **Run scaffolded gates.** `cd` in; **preflight each tool** (`just`, `uv`/`bun`/`go`/
+  `golangci-lint`, `gitleaks`). A missing tool ⇒ `status:skipped` "not exercised: missing X",
+  **distinct from fail**. Then `just ci` (lint+test). For `just scan`: reuse the bootstrap
+  repo and stage a harmless file first (the recipe runs `gitleaks git --pre-commit --staged`,
+  meaningless without a repo + staged content); no-git/no-staged ⇒ skipped, not fail.
+  `just ci` for node/go *may* fetch deps — allowed (matches a real user); a **network failure
+  is reported distinctly**, not as scaffold breakage.
+- **Exercise hooks & guards — in the correct mode:**
+  - *Plugin-mode project (#1):* the **event-wired** guard hooks
+    (`github_command_guard.sh`, `pre_commit_gate.sh`, `session_setup.sh`,
+    `workflow_state_reminder.sh`, `post_edit_lint.sh`) are supplied by the **plugin payload**
+    — invoke `plugins/project-init-workflow/hooks/*` with `CLAUDE_PLUGIN_ROOT` +
+    `CLAUDE_PROJECT_DIR` set. Note: the scaffolded project still carries a **reduced** local
+    `.claude/hooks/` (`dag_workflow.py`, `prod_guard.py`, `_py.sh`) because the lifecycle
+    scripts shim to `../hooks/dag_workflow.py` and `enabledPlugins` lists
+    `project-init-workflow@project-init` — the same hook *set* fires in both modes
+    (`capabilities.py`), plugin mode just sources the wired ones from the plugin. Specifically
+    verify scripts-dir/redirect resolution honors `$CLAUDE_PROJECT_DIR` — **the exact 0.4.0
+    P1.** First-class depth.
+  - *`--no-plugin` project (#2):* invoke the scaffolded `.claude/hooks/*`.
+  - Feed banned commands and confirm **block**; feed allowed and confirm **pass**; run
+    `pre_commit_gate.sh` with stdin JSON.
+- **Walk the git/PR lifecycle (fully local, scoped).** Reuse the bootstrap repo + bare
+  `origin`, run `install_hooks.sh`, make a commit (commit-msg + pre-commit fire), then run
+  `create_issue.sh`, `start_issue.sh`, `push_branch.sh`, `promote_review.sh` against the stub.
+  **Skip `finish_pr.sh`** — it chains into `dag_workflow.py finish` → `monitor_pr.sh --merge`,
+  which carries CI/review/merge assumptions a stub can't honestly satisfy; note the merge path
+  as "not exercised by design".
+- **Read-as-an-agent sanity.** Read `AGENTS.md`/`CLAUDE.md`/`settings.json`/per-surface
+  configs; judge whether instructions are coherent and non-contradictory.
+
+### 5. Aggregate & report
+
+After *all* subagents finish, read every `result.json` and write one timestamped
+`"$RUN/REPORT.md"`: a summary table (project × depth × pass/fail/skipped) + severity-ranked
+findings (what / repro / suspected file / fix sketch). **No auto-filing of GitHub issues.**
+
+### 6. Cleanup
+
+**Always preserve `REPORT.md`.** Before deleting any *passing* project dir, copy its
+per-project logs (subagent stdout/stderr, `gh.log`, timeout artifacts) into
+`"$RUN/logs/<project>/"` so audit trails survive even for clean passes. Then delete only the
+*passing* project dirs; preserve any failing project dir whole. `--keep` preserves everything.
+Print all preserved paths.
+
+## Rules
+
+- **No network/GitHub side effects.** `gh` is stubbed; `GH_TOKEN`/`GITHUB_*` cleared; the only
+  remote is a local bare repo. Never run the real merge path.
+- **`skipped` ≠ `fail`.** A missing host tool (`just`, `go`, `gitleaks`, `golangci-lint`) is a
+  skip with a reason, never a failure.
+- **Single fresh wheel** from an isolated `-o` build dir — never `dist/*.whl`.
+- **Timeout-wrap every external command;** a timeout is a finding.
+- **Mode-aware hooks:** plugin project → repo plugin payload; `--no-plugin` project →
+  scaffolded `.claude/hooks/*`. Don't cross-report.
+- **Deterministic-clock-free:** never depend on `date`/`Date.now()` for correctness; the runid
+  is a label, passed in or best-effort.
+- This skill is **source-only** — it lives under this repo's `.claude/skills/`, is **not** in
+  `templates/fallback/` and **not** part of `tools/sync_plugin.py`. It tests the scaffolder; it
+  is not shipped into scaffolded output.