[Split Scope Migration](2) Remind agents to read split-scope on planning prompts

[EdbertChan]

Summary

Planning prompts for stacked or multi-slice work now remind agents to read the split-scope skill.

The reminder reaches Claude, Codex, and Cursor through a fail-open hook installed by the repository installer.

Review Claim

The new prompt hook injects a split-scope reminder for multi-PR and migration plans without blocking unrelated prompts.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The hook is inject-only and fail-open: it never blocks a tool and emits nothing when the prompt does not match.

Slice Rationale

This slice adds the detector, harness entrypoints, installers, and focused tests together so the activation path is reviewable end to end.

The split-scope skill text landed in the preceding slice, so this slice only activates it on planning prompts.

Non-goals

• Do not change product/skills/split-scope, build-the-lever, playbook-router, or pr-schema-gate.
• Do not edit the repository README.md or docs/ecosystem.md tables.
• Do not add blocking behavior or change unrelated prompt handling.

Architecture

Before

graph TD
    A["Planning prompt"] --> B["Harness"]
    B --> C["Agent plans without an automatic split-scope reminder"]

Loading

After

graph TD
    A["Planning prompt"] --> B["Claude, Codex, or Cursor hook"]
    B --> C["Detector checks for multi-PR, slice, or migration language"]
    C -->|"match"| D["Inject split-scope reminder"]
    C -->|"no match or error"| E["Continue silently and fail open"]
    D --> F["Agent plans with split-scope guidance"]

Loading

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/split-scope/tests -v && python3 scripts/check_hook_test_coverage.py engine/hooks/split-scope && python3 -m unittest discover -s tests -p "test_install.py"
• bash scripts/scrub-handoff-artifacts.sh

Revert Plan

Revert Plan

• Safe to revert? Yes.
• Revert command: git revert <sha>.
• Post-revert steps: Re-run the hook and installer test commands above.
• Data migration? No.

---

Note

Low Risk
Adds optional prompt context only; it does not block tools and follows the same install/merge pattern as other catstack hooks.

Overview
Adds a new split-scope prompt hook that nudges agents to read the split-scope skill before they write multi-slice plans or PR stacks.

When user text matches regex triggers (e.g. PR stack, multiple PRs, migration plan), Claude and Codex inject additionalContext on UserPromptSubmit. Cursor records a pending flag on beforeSubmitPrompt and delivers the same reminder once on the first postToolUse, using TTL state under ~/.cache/catstack-split-scope. Behavior is inject-only and fail-open (no blocking; malformed input logs to stderr).

install.sh symlinks the hook for all three harnesses and runs idempotent merge installers; tests/test_install.py and engine/hooks/split-scope/tests cover detection, entrypoints, and wiring.

^{Reviewed by Cursor Bugbot for commit 2060337. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_9747c2a9-e994-427b-ad91-32f1dfab3df7)

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_65b34f51-ccf7-4082-819c-a533b86554ba)