edercnj/x-internal-verify-phase-gates

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

🔒 INTERNAL SKILL Esta skill é invocada apenas por outras skills (orquestradores). NÃO é destinada a invocação direta pelo usuário. Callers principais: x-implement-epic, x-implement-story, x-implement-task, x-release, x-orchestrate-epic, x-review-codebase, x-review-pr, x-manage-pr-merge-train (após retrofits em stories 0055-0003 a 0055-0010). Oitava skill no subdir internal/plan/ (após x-internal-load-story-context, x-internal-build-story-plan, x-internal-verify-story, x-internal-resume-story, x-internal-build-epic-plan, x-internal-verify-epic-integrity, x-internal-write-story-report). Primeira skill introduzida por EPIC-0055.

Skill: x-internal-verify-phase-gates

Purpose

Validates phase transitions in orchestrators governed by Rule 25. A phase gate is a synchronous, fail-fast check that runs around each numbered ## Phase N section: a PRE gate ensures the predecessor phases are cleanly completed; a POST gate ensures every child task of the current phase is completed AND every artifact the phase was supposed to produce exists on disk. Rule 25 moves enforcement from "Stop hook notices afterwards" (Rule 24 defense-in-depth) to sync gate before the phase is marked completed — missing tasks or artifacts abort the lifecycle with exit 12.

Responsibilities (single):

1. Parse arguments against the 4-mode matrix (pre / post / wave / final).
2. For PRE mode: scan predecessor phases' phaseGateResults in execution-state.json and TaskList for any non-completed sibling task.
3. For POST / WAVE / FINAL mode: intersect --expected-tasks against TaskList looking for completed status on each, AND stat-check every path in --expected-artifacts.
4. Atomically append a phaseGateResults[] entry to execution-state.json.taskTracking via x-internal-update-status (delegated).
5. Emit a single-line JSON envelope on stdout.
6. Translate every failure class to the exit-code catalogue.

Non-responsibilities (explicit):

• Does NOT mutate task state (no TaskUpdate(status: ...)). The caller owns task state transitions.
• Does NOT run the PostToolUse hook. The hook (verify-phase-gates.sh, story-0055-0002) reads phaseGateResults[] this skill writes.
• Does NOT emit TaskCreate unless --mode wave --emit-tracker true is set (Rule 25 Invariant 6 exception — one tracker task to surface wave wall-clock).
• Does NOT run tests, build, or any project-level validation. x-internal-verify-story / x-internal-verify-epic-integrity own those — this gate composes with them via --mode final.

Convention Anchors (x-internal-* — EPIC-0055)

| Aspect | Value | Rationale | | :--- | :--- | :--- | | Path | internal/plan/x-internal-verify-phase-gates/ | Read-and-compute carve-out, co-located with other story/epic gate skills. | | Frontmatter visibility | internal | Generator filters from /help menu. | | Frontmatter user-invocable | false | Declarative complement. | | Frontmatter model | haiku | Zero-reasoning lookup (RULE-023 utility tier). | | Body marker | > 🔒 **INTERNAL SKILL** | Rule 22 §Body marker. | | Allowed tools | Read, Bash | Read for artifact stat; Bash for jq + state-file I/O via x-internal-update-status. |

Triggers

Bare-slash form intentionally omitted — never invoked by a user. All invocations follow Rule 13 Pattern 1 (INLINE-SKILL):

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode pre --skill x-implement-story --phase Phase-1 --state-file ai/epics/epic-XXXX/execution-state.json")

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode post --skill x-implement-story --phase Phase-1 --expected-tasks 101,102,103,104,105,106 --expected-artifacts ai/epics/epic-XXXX/plans/arch-story-0060-0001.md,ai/epics/epic-XXXX/plans/plan-story-0060-0001.md --state-file ai/epics/epic-XXXX/execution-state.json")

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode wave --skill x-review-codebase --phase Phase-2 --expected-tasks 201,202,203,204,205,206,207,208,209 --state-file ai/epics/epic-XXXX/execution-state.json")

Parameters

| Flag | Required | Default | Description | | :--- | :--- | :--- | :--- | | --mode <tier> | M | — | One of pre, post, wave, final. Case-insensitive; normalized to lowercase. | | --skill <name> | M | — | Calling orchestrator name (recorded in the envelope and state file). | | --phase <Phase N> | M | — | Exact phase label (matches ## Phase N — Name header). | | --parent-task-id <id> | O | — | Integer ID of the parent TaskCreate that owns the phase. Used to discover children via TaskList. | | --expected-tasks <ids> | O | — | Comma-separated integer task IDs the gate must see as completed. Required for post, wave, final. | | --expected-artifacts <paths> | O | — | Comma-separated relative paths that MUST exist on disk. Required for post and final. Optional for wave. | | --timeout-s <N> | O | 10 | Integer seconds to retry-poll if any --expected-tasks is still in_progress. Exceeded → exit 14. | | --emit-tracker <bool> | O | false | Only legal with --mode wave. Emits a single tracker TaskCreate with subject = <skill> › <phase> › wave-tracker for CLI visibility. | | --state-file <path> | O | auto | Path to execution-state.json. Auto-derived from $CWD/ai/epics/epic-XXXX/execution-state.json when epic is unambiguous. |

Response Contract

On success (exit 0) and on failure (exit 12) the skill writes a single-line JSON object to stdout:

| Field | Type | Always Present | Description | | :--- | :--- | :--- | :--- | | passed | Boolean | yes | true when all checks passed. | | mode | String | yes | Echo of --mode. | | skill | String | yes | Echo of --skill. | | phase | String | yes | Echo of --phase. | | expectedTasks | Array<Integer> | yes | Echo of --expected-tasks ([] if absent). | | completedTasks | Array<Integer> | yes | Subset of expectedTasks confirmed completed in TaskList. | | missingTasks | Array<Integer> | yes | expectedTasks \ completedTasks. Empty when passed=true. | | expectedArtifacts | Array<String> | yes | Echo of --expected-artifacts. | | missingArtifacts | Array<String> | yes | Subset of expectedArtifacts that do NOT exist on disk. Empty when passed=true. | | wallclockMs | Integer | yes | Gate execution time in milliseconds (monotonic clock). | | timestamp | String (ISO-8601) | yes | Gate completion timestamp in UTC. |

The envelope shape is authoritative. phaseGateResults[] in execution-state.json receives a slim projection: {phase, mode, passed, missingArtifacts, missingTasks, timestamp}.

Exit Codes

| Code | Name | Condition | | :--- | :--- | :--- | | 0 | OK | passed=true | | 12 | PHASE_GATE_FAILED | passed=false — at least one missing task or missing artifact | | 13 | PHASE_GATE_MALFORMED | Unknown flag, missing required flag, --emit-tracker true without --mode wave, --expected-tasks on --mode pre, etc. | | 14 | PHASE_GATE_TIMEOUT | An expected task is still in_progress after --timeout-s seconds of polling | | 64 | EX_USAGE | --mode value not in {pre, post, wave, final} or --phase fails Rule-25 subject regex |

No partial-success state: the first non-recoverable error aborts the run and yields a non-zero exit.

Workflow

Step 1 — Arg parse + validation

Parse arguments with the shared Rule-14 while (($#)) loop. Normalize --mode to lowercase. Validate:

• --mode ∈ {pre, post, wave, final} — else exit 64.
• --phase matches Rule-25 subject regex — else exit 64.
• For --mode post|wave|final: --expected-tasks MUST be present.
• For --mode post|final: --expected-artifacts MUST be present.
• For --mode pre: --expected-tasks / --expected-artifacts MUST be absent (checks come from state file only) — else exit 13.
• --emit-tracker true requires --mode wave — else exit 13.

Step 2 — Resolve --state-file

When --state-file absent, search upward from $PWD for ai/epics/epic-*/execution-state.json. Exactly one match → proceed. Zero or multiple → exit 13 with STATE_FILE_AMBIGUOUS.

Step 3 — Short-circuit on taskTracking.enabled=false

Read taskTracking.enabled from the state file. Default is true when the field is absent (Rule 19 fallback). Only when the value is explicitly false, emit:

{"passed":true,"mode":"<mode>","skill":"<skill>","phase":"<phase>","expectedTasks":[],"completedTasks":[],"missingTasks":[],"expectedArtifacts":[],"missingArtifacts":[],"wallclockMs":<N>,"timestamp":"<t>","note":"taskTracking disabled (legacy mode)"}

and exit 0. This is the Rule-19 backward-compat path — legacy epics treat gates as no-ops.

Step 4 — Mode-specific validation

4a. --mode pre

Read execution-state.json.taskTracking.phaseGateResults[]. Let N = int(phase.replace("Phase-","")). For every k ∈ [0, N-1], at least one entry with phase="Phase-k" AND mode="post" AND passed=true MUST be present. Missing entries → missingTasks=[<Phase-k-placeholder>], passed=false, exit 12.

No artifact checks in PRE mode.

4b. --mode post

• Tasks: For each id ∈ --expected-tasks, retrieve its status. Use TaskList via Bash (e.g., reading from ~/.claude/state/tasks/<session>/tasks.json when available, falling back to execution-state.json.taskTracking.taskIndex[]). completed → add to completedTasks; else add to missingTasks. If any task is in_progress, poll every 500ms up to --timeout-s; persistent → exit 14.
• Artifacts: For each path ∈ --expected-artifacts, [[ -e "$path" ]] — present → drop; absent → append to missingArtifacts.
• passed = missingTasks.isEmpty() && missingArtifacts.isEmpty().

4c. --mode wave

Same as POST, but:

• Semantics: ALL wave members must be completed simultaneously (no ordering assumption).
• --expected-artifacts is optional — waves that only produce task commits (no files) are valid.
• When --emit-tracker true, emit exactly one TaskCreate(subject: "<skill> › <phase> › wave-tracker") upfront and TaskUpdate(status: "completed") at the end, regardless of result.

4d. --mode final

Superset of POST. Additionally scans the Rule-24 mandatory artifact set (when --skill = x-implement-story): verify-envelope, review-story, techlead-review, story-completion-report. Acts as the synchronous Rule-24 gate the Stop-hook normally enforces asynchronously.

Step 5 — Write phaseGateResults[] entry

Atomically append to execution-state.json.taskTracking.phaseGateResults[] via:

Skill(skill: "x-internal-update-status",
      args: "--file <state-file> --type phase-gate --phase <phase> --mode <mode> --passed <true|false> --missing-artifacts <comma-list> --missing-tasks <comma-list>")

The status-update skill owns the flock-protected read-modify-write.

Step 6 — Emit envelope

Single-line JSON via jq -nc with all fields. Exit 0 on success, 12 on failure.

Idempotency Contract

The skill is idempotent by design:

• Re-invoking the same gate (same --mode, --skill, --phase) is a replay: it re-reads task state + artifact state, writes a fresh phaseGateResults[] entry, and returns the current result. Previous entries remain for audit history.
• Concurrent invocations serialize on x-internal-update-status's flock (file-level).

Performance Contract

| Mode | Budget | | :--- | :--- | | pre | < 50ms (single file read + jq projection) | | post | < 100ms + artifact stat × N (usually < 150ms total) | | wave | same as post | | final | < 200ms (adds Rule-24 scan) |

Target global overhead across an epic with ~30 gates: < 5 seconds, i.e., well below the EPIC-0055 DoD threshold of "< 2% wall-clock overhead".

Examples

Example 1 — Happy path, PRE mode

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode pre --skill x-implement-story --phase Phase-2 --state-file ai/epics/epic-XXXX/execution-state.json")

Output:

{"passed":true,"mode":"pre","skill":"x-implement-story","phase":"Phase-2","expectedTasks":[],"completedTasks":[],"missingTasks":[],"expectedArtifacts":[],"missingArtifacts":[],"wallclockMs":12,"timestamp":"2026-04-24T10:30:00Z"}

Exit: 0.

Example 2 — POST mode all green

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode post --skill x-implement-story --phase Phase-1 --expected-tasks 101,102,103,104,105,106 --expected-artifacts ai/epics/epic-XXXX/plans/arch-story-0060-0001.md,ai/epics/epic-XXXX/plans/plan-story-0060-0001.md")

Output:

{"passed":true,"mode":"post","skill":"x-implement-story","phase":"Phase-1","expectedTasks":[101,102,103,104,105,106],"completedTasks":[101,102,103,104,105,106],"missingTasks":[],"expectedArtifacts":["ai/epics/epic-XXXX/plans/arch-story-0060-0001.md","ai/epics/epic-XXXX/plans/plan-story-0060-0001.md"],"missingArtifacts":[],"wallclockMs":47,"timestamp":"2026-04-24T10:35:00Z"}

Exit: 0.

Example 3 — POST mode, missing artifacts

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode post --skill x-implement-story --phase Phase-1 --expected-tasks 101,102 --expected-artifacts ai/epics/epic-XXXX/plans/arch-story-0060-0001.md,ai/epics/epic-XXXX/plans/missing.md")

Output:

{"passed":false,"mode":"post","skill":"x-implement-story","phase":"Phase-1","expectedTasks":[101,102],"completedTasks":[101,102],"missingTasks":[],"expectedArtifacts":["ai/epics/epic-XXXX/plans/arch-story-0060-0001.md","ai/epics/epic-XXXX/plans/missing.md"],"missingArtifacts":["ai/epics/epic-XXXX/plans/missing.md"],"wallclockMs":38,"timestamp":"2026-04-24T10:40:00Z"}

Exit: 12.

Example 4 — WAVE mode, one member still running

With --timeout-s 2 and task 203 in in_progress:

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode wave --skill x-review-codebase --phase Phase-2 --expected-tasks 201,202,203,204,205,206,207,208,209 --timeout-s 2")

Stderr:

PHASE_GATE_TIMEOUT — task 203 still in_progress after 2s

Exit: 14.

Example 5 — Malformed: wave without expected-tasks

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode wave --skill x-review-codebase --phase Phase-2")

Stderr:

PHASE_GATE_MALFORMED — --mode wave requires --expected-tasks

Exit: 13.

Example 6 — Legacy short-circuit

When execution-state.json.taskTracking.enabled = false:

Skill(skill: "x-internal-verify-phase-gates",
      args: "--mode post --skill x-implement-story --phase Phase-1 --expected-tasks 101 --expected-artifacts foo.md")

Output:

{"passed":true,"mode":"post","skill":"x-implement-story","phase":"Phase-1","expectedTasks":[],"completedTasks":[],"missingTasks":[],"expectedArtifacts":[],"missingArtifacts":[],"wallclockMs":3,"timestamp":"2026-04-24T10:45:00Z","note":"taskTracking disabled (legacy mode)"}

Exit: 0.

Error Handling

| Scenario | Action | | :--- | :--- | | --mode value invalid | PHASE_GATE_MALFORMED; exit 13 | | --phase fails regex | Exit 64 | | Required flag missing per mode | PHASE_GATE_MALFORMED; exit 13 | | State file absent AND no --state-file override | STATE_FILE_AMBIGUOUS; exit 13 | | taskTracking.enabled=false | Short-circuit; passed=true; exit 0 | | Expected task in_progress beyond timeout | PHASE_GATE_TIMEOUT; exit 14 | | At least one expected task missing / non-completed | PHASE_GATE_FAILED; exit 12 | | At least one expected artifact absent | PHASE_GATE_FAILED; exit 12 | | x-internal-update-status delegation fails | Propagate stderr; exit 13 with STATE_UPDATE_FAILED |

Generator Filter Contract

The ia-dev-env generator excludes skills with visibility: internal from:

1. .claude/README.md inventory table.
2. /help menu.
3. User-facing autocomplete.

Still copied to .claude/skills/ (flat layout) so other skills can invoke via Skill(...).

Telemetry

Internal skills DO NOT emit phase.start / phase.end markers — the calling orchestrator owns telemetry wrapping. Passive hooks capture tool.call events for the underlying Bash/Read invocations.

Integration Notes

| Skill | Relationship | Context | | :--- | :--- | :--- | | x-internal-update-status | delegate | Atomic flock-protected write of phaseGateResults[] entry. | | x-implement-epic, x-implement-story, x-implement-task, x-release, x-orchestrate-epic, x-review-codebase, x-review-pr, x-manage-pr-merge-train | callers | Retrofit in stories 0055-0003 → 0055-0010. | | x-internal-verify-epic-integrity | composition | --mode final of x-implement-epic Phase 4 composes with integrity gate (gate runs first; integrity-gate is subsequent). | | x-internal-verify-story | composition | --mode final of x-implement-story Phase 3 composes with story-verify (verify runs first; gate confirms its outputs). | | .claude/hooks/verify-phase-gates.sh | consumer (Stop hook) | Reads phaseGateResults[] this skill writes; emits WARNING + exit 2 on gate failure at end of LLM turn. | | .claude/hooks/enforce-phase-sequence.sh | consumer (PreToolUse hook) | Reads phaseGateResults[] to block Skill(...) of an orchestrator whose predecessor phase has no passed=true entry. |

Rule References

• Rule 25 — the specification this skill enforces.
• Rule 22 — Skill Visibility convention (x-internal-*, visibility: internal).
• Rule 23 — Model Selection (haiku tier for utility skills).
• Rule 13 — Skill Invocation Protocol (INLINE-SKILL pattern).
• Rule 19 — Backward Compatibility (legacy short-circuit behavior).
• Rule 24 — Execution Integrity (composition via --mode final).

Full Protocol

Per-mode state-file schema, full flock + x-internal-update-status interaction pseudocode, polling algorithm for in_progress tasks, and the phaseGateResults[] append-only invariant live in references/full-protocol.md.