Repository navigation
Description
Problem
When the LLM orchestrator processes the compose_pr recipe step, issue_number is passed as a with: key alongside skill_command — but run_skill's Python function does not accept issue_number as a parameter. A note: field instructs the LLM to "append it as the 5th positional argument for Closes #N injection." When the LLM fails to follow this instruction, compose-pr receives only 4 positional arguments, silently omits Closes #N, and the PR body has no issue reference.
Meanwhile, release_issue_success still applies the staged label after PR merge (based solely on target_branch != promotion_target at tools_issue_lifecycle.py:546), creating an invariant violation: the system asserts "implementation has landed" without ensuring the issue will auto-close on promotion.
This caused 6 staged issues (#2201, #2198, #2189, #2185, #2179, #2166) to remain open after promotion PR #2213 merged — all 6 implementation PRs had zero Closes #N references in their bodies. The carry-forward chain (compose-pr → open-integration-pr → promote-to-main) works correctly but is garbage-in/garbage-out.
Solution: Two-Hook Guard Architecture
Implement a two-hook solution within the existing session — no orchestrator changes, no extra sessions required.
Hook 1: PostToolUse on claim_and_resolve_issue — State Bridge
- Matcher:
mcp__.*autoskillit.*__claim_and_resolve_issue.* - Event:
PostToolUse - Behavior: When
claim_and_resolve_issuesucceeds (parsetool_responseforsuccess: true), extractissue_numberfrom the response JSON and persist it to.autoskillit/temp/.issue_context.json(e.g.,{"issue_number": 2201}). When the tool fails or the issue_url was absent (step skipped → no hook fires), no state file is written. - Pattern precedent:
review_gate_post_hook.pyalready does exactly this — PostToolUse writesreview_gate_state.jsonfor downstream PreToolUse consumption. - Cleanup: The state file should be removed by
close_kitchen(alongsidehook_config.jsoncleanup) or at session end.
Hook 2: PreToolUse on run_skill — Compose-PR Issue Guard
- Matcher:
mcp__.*autoskillit.*__run_skill.*(add to existing HookDef or create new entry) - Event:
PreToolUse - Script:
guards/compose_pr_issue_guard.py - Behavior:
- Parse
tool_input.skill_commandfrom stdin JSON - Check if skill_command targets
compose-prorprepare-pr - If neither, exit 0 (pass-through)
- Read
.autoskillit/temp/.issue_context.json— if absent, exit 0 (no issue expected, pass-through) - Extract
issue_numberfrom state file - For
compose-pr: check if issue number appears as 5th positional argument. Forprepare-pr: check 4th positional argument. - If missing: deny with
permissionDecision: "deny"and a reason like:"compose-pr requires issue number #{N} as the 5th positional argument. Re-invoke run_skill with the issue number appended to skill_command." - If present: exit 0 (approve)
- Parse
- Session scope:
headless_only— only fire in headless recipe sessions, not interactive invocations - Fail mode: fail-open on malformed JSON (matches all existing guard conventions)
Hook Registry Changes
In hook_registry.py:
-
New PostToolUse
HookDefforclaim_and_resolve_issue:matcher:mcp__.*autoskillit.*__claim_and_resolve_issue.*event_type:PostToolUsescripts:["issue_context_post_hook.py"]session_scope:headless_only
-
Add
guards/compose_pr_issue_guard.pyto the existingrun_skillPreToolUse HookDef scripts list (the one with matchermcp__.*autoskillit.*__run_skill.*that already runsskill_cmd_guard.py,quota_guard.py,skill_command_guard.py)
Key Design Constraints
- Both hooks MUST be stdlib-only (no autoskillit imports) — matches all existing hook conventions
- The state file is written by Python code (PostToolUse hook reading the mechanical tool response), NOT by the LLM — this is the critical architectural difference from the current
note:-based approach - The deny reason must be specific and actionable (include the exact issue number and expected skill_command format) so the LLM can retry correctly
- The guard should NOT fire for interactive sessions or ad-hoc compose-pr invocations
Files to Create/Modify
- Create:
src/autoskillit/hooks/issue_context_post_hook.py— PostToolUse state bridge - Create:
src/autoskillit/hooks/guards/compose_pr_issue_guard.py— PreToolUse deny guard - Modify:
src/autoskillit/hook_registry.py— add new HookDef entries + update existing run_skill scripts list - Modify:
src/autoskillit/server/tools/tools_kitchen.py— cleanup.issue_context.jsoninclose_kitchen - Tests: Add tests for both hooks (stdin JSON → stdout decision), state file lifecycle, and the deny → retry scenario
Requirements
HOOK — Hook Infrastructure
REQ-HOOK-001: The system must persist the issue_number from a successful claim_and_resolve_issue tool response to a state file at .autoskillit/temp/.issue_context.json via a PostToolUse hook.
REQ-HOOK-002: The PostToolUse hook must only write the state file when the claim_and_resolve_issue response contains success: true and a non-empty issue_number.
REQ-HOOK-003: The state file must be removed during close_kitchen cleanup alongside the existing hook_config.json removal.
REQ-HOOK-004: A PreToolUse guard on run_skill must deny calls where skill_command targets compose-pr and the expected issue number (read from .issue_context.json) is absent from the 5th positional argument.
REQ-HOOK-005: The same PreToolUse guard must deny calls where skill_command targets prepare-pr and the expected issue number is absent from the 4th positional argument.
REQ-HOOK-006: The PreToolUse guard must pass through (exit 0) when .issue_context.json does not exist, indicating no issue is expected for this session.
REQ-HOOK-007: The PreToolUse guard must pass through (exit 0) when skill_command does not target compose-pr or prepare-pr.
REQ-HOOK-008: The deny reason must include the exact expected issue number and the corrected skill_command format so the LLM can retry with corrected parameters.
SCOPE — Session Scope and Fail Mode
REQ-SCOPE-001: Both hooks must have session_scope: headless_only to avoid interfering with interactive sessions or ad-hoc skill invocations.
REQ-SCOPE-002: Both hooks must be stdlib-only (no autoskillit.* imports) to match the existing hook subprocess contract.
REQ-SCOPE-003: Both hooks must fail-open on malformed JSON input (JSON decode failure = sys.exit(0) = approve), matching the established guard fail-mode convention.
REG — Hook Registry Integration
REQ-REG-001: A new PostToolUse HookDef entry must be added to HOOK_REGISTRY with matcher mcp__.*autoskillit.*__claim_and_resolve_issue.* and event type PostToolUse.
REQ-REG-002: The PreToolUse guard script must be added to the existing run_skill PreToolUse HookDef scripts list (matcher mcp__.*autoskillit.*__run_skill.*).
REQ-REG-003: New hook scripts must be registered in HOOK_REGISTRY and must not reuse any basename from RETIRED_SCRIPT_BASENAMES.
TEST — Testing
REQ-TEST-001: Tests must verify the PostToolUse hook writes .issue_context.json with correct content when claim_and_resolve_issue succeeds.
REQ-TEST-002: Tests must verify the PostToolUse hook does not write a state file when claim_and_resolve_issue fails.
REQ-TEST-003: Tests must verify the PreToolUse guard denies compose-pr calls missing the issue number when .issue_context.json exists.
REQ-TEST-004: Tests must verify the PreToolUse guard approves compose-pr calls that include the correct issue number.
REQ-TEST-005: Tests must verify the PreToolUse guard passes through when .issue_context.json is absent.
REQ-TEST-006: Tests must verify the PreToolUse guard passes through for non-compose-pr/prepare-pr skill commands.
Activity
Trecek commentedon May 31, 2026
Superseded by #3421 — updated design with broader architectural context, PreToolUse-on-Bash interception (prevents bad PR creation), and implementation flexibility for the hook pattern.