opencue · NagyVikt · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-30
@@ -0,0 +1,15 @@
+## Why
+
+`gx claude install` bakes a SessionStart hook calling `scripts/agent-stalled-report.sh` into a target repo's `settings.json` (via `TEMPLATE_DEFAULT_SETTINGS`), but neither that shim nor the watcher it wraps (`scripts/agent-autofinish-watch.sh`, shipped in #665) was ever delivered to target repos: `gx claude install` only copies `.claude/hooks/*.py`, and the two scripts were absent from `TEMPLATE_FILES`. Result: every target repo got a hook pointing at a missing script, so stalled-worktree recovery silently no-op'd everywhere except gitguardex itself.
+
+## What Changes
+
+- Move `scripts/agent-stalled-report.sh` and `scripts/agent-autofinish-watch.sh` to `templates/scripts/` (the real files) and replace `scripts/<file>` with tracked symlinks — the PAIRED convention used by `agent-preflight.sh`.
+- Register both in `TEMPLATE_FILES` (`src/context.js`) so `gx setup` copies them verbatim into a target's `scripts/`, and in `scripts/check-script-symlinks.sh` so the pairing stays enforced.
+- Extend `test/setup.test.js` `requiredFiles` to assert both land after setup.
+
+## Impact
+
+- Affected surfaces: `src/context.js`, `scripts/check-script-symlinks.sh`, `templates/scripts/` (2 new), `scripts/` (2 → symlinks), `test/setup.test.js`.
+- Delivery vector is `gx setup` / `gx doctor` (which scaffold `TEMPLATE_FILES`), NOT `gx claude install` (which never touches `scripts/`). No `claude.js` / `MANAGED_HOOK_FILES` change is needed — that earlier-suspected lever was wrong.
+- Low risk: additive distribution following an existing precedent; verified end-to-end that `gx setup --target` delivers both scripts as runnable executables.
@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Stalled-report hook and watcher reach target repos
+`gx setup` SHALL deliver both `scripts/agent-stalled-report.sh` (the SessionStart hook shim) and `scripts/agent-autofinish-watch.sh` (the watcher it invokes) into a target repo's `scripts/` directory as regular executable files, so the SessionStart hook baked into the target's `settings.json` references a script that actually exists. Both scripts SHALL follow the PAIRED convention: the real file lives under `templates/scripts/` and `scripts/<file>` is a tracked symlink to it.
+
+#### Scenario: setup delivers both scripts
+- **WHEN** `gx setup` runs against a target repo
+- **THEN** `scripts/agent-stalled-report.sh` and `scripts/agent-autofinish-watch.sh` exist in the target as executable regular files whose content matches `templates/scripts/`
+- **AND** the delivered `agent-stalled-report.sh` runs and resolves the watcher next to it.
+
+#### Scenario: pairing stays enforced
+- **WHEN** `scripts/check-script-symlinks.sh` runs
+- **THEN** both `scripts/agent-stalled-report.sh` and `scripts/agent-autofinish-watch.sh` are verified as symlinks into `templates/scripts/`
+- **AND** replacing either symlink with a regular file fails the check.
@@ -0,0 +1,34 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-claude-distribute-autofinish-watcher-stalled-re-2026-06-30-02-56`; branch=`agent/<your-name>/<branch-slug>`; scope=`distribute agent-stalled-report.sh + agent-autofinish-watch.sh to target repos via TEMPLATE_FILES (PAIRED pattern)`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`.
+- Copy prompt: Continue `agent-claude-distribute-autofinish-watcher-stalled-re-2026-06-30-02-56` on branch `agent/<your-name>/<branch-slug>`. Work inside the existing sandbox, review `openspec/changes/agent-claude-distribute-autofinish-watcher-stalled-re-2026-06-30-02-56/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-claude-distribute-autofinish-watcher-stalled-re-2026-06-30-02-56`.
+- [x] 1.2 Define normative requirements in `specs/distribute-autofinish-watcher-stalled-report-hook-to-target-repos-via-gx-claude-install/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Implement scoped behavior changes.
+- [x] 2.2 Add/update focused regression coverage.
+
+## 3. Verification
+
+- [x] 3.1 Run targeted project verification commands.
+- [x] 3.2 Run `openspec validate agent-claude-distribute-autofinish-watcher-stalled-re-2026-06-30-02-56 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).
@@ -0,0 +1 @@
+../templates/scripts/agent-autofinish-watch.sh
@@ -0,0 +1 @@
+../templates/scripts/agent-stalled-report.sh