gg-skill-phase

GG-SKILL-PHASE — Senior-Grade Phase Executor

Wraps execute-phase with three enforcement layers before any code is written:

1. Architecture Contract Injection — reads architecture-patched.md Section 0, injects hard_constraints, forbidden_patterns, anti_patterns, and test_expectations as hard constraints into execute-phase.
2. Spec Quality Gate — refuses to execute if the spec file contains [TBD] markers in task definitions or acceptance criteria.
3. RISK_GUARD Map — identifies [RISK_GUARD] components in the architecture, injects per-component validation assertions, and surfaces a summary before any code is written.

After execution, produces a Post-Phase Drift Report comparing the updated dep-tree against the architecture Module Registry.

---

Workflow Position

gg-skill-prd -apply        → PRD-patched.md
      ↓
gg-skill-architecture      → architecture-patched.md  (confidence ≥ 0.8)
      ↓
gg-skill-specs N           → docs/phases/phaseN.md + docs/dev/phaseN-enhancement.md
      ↓
gg-skill-phase -a -p N -enh N   ← you are here
      ↓
   Code + tests + dep-tree updated + drift report

---

Flags

Flag	Description
-p N	Phase number — resolves docs/phases/phaseN.md + docs/dev/phaseN.md
-f PATH	Custom path to spec file
-d PATH	Custom path to tracker file
-arch PATH	Custom path to architecture file (default: auto-detect architecture-patched.md then architecture.md)
-enh N|PATH	Enhancement file — integer N auto-deduces -p N; B1/B2/B3 injected after architecture contract
-g GROUP	BE | FE | DO | ALL (default ALL)
-from ID	Resume from task ID
-to ID	Stop after task ID
-a	Full autonomy — no confirmations
-s	Save outputs to .claude/output/phase/
-x	Adversarial multi-agent review after S05
-b	Branch mode
-pr	Create PR at end (implies -b)
-ci	CI watch — iterate until green (implies -b)
-e	Economy mode — no subagents, inline only

---

Phase 0 — Context Load & Architecture Gate

Step 1 — Locate architecture file (GATE):

IF -arch PATH provided:
  → verify the file exists at PATH
  IF not found:
    ⛔ Architecture file not found at {PATH}. Halting.

ELSE (auto-detect):
  → check for `architecture-patched.md` at project root → use it if found

  ELSE → check for `architecture.md` at project root
  → use it (warn: run /gg-skill-architecture -apply to upgrade)

  ELSE:
    ⛔ No architecture file found.
    Options:
      1. Run /gg-skill-architecture {PRD path} to generate it
      2. Use -arch PATH to point to an existing file
      3. Use execute-phase directly (no contract enforcement)
    Halting.

Step 2 — Read context silently (do not mention in output unless a finding drives a decision):

1. Architecture file
2. dep-tree.md — existing module map, high-coupling zones
3. Spec file — docs/phases/phaseN.md or -f PATH
4. Enhancement file — if -enh flag present

---

Phase 1 — Architecture Contract Extraction

Extract from Section 0 only (see references/contract-format.md for the full injected block format):

• Section 0.1: hard_constraints, forbidden_patterns, required_patterns
• Section 0.2: decision_shortcuts
• Section 0.3: anti_patterns (name + fix)
• Section 0.4: test_expectations — filter to entries relevant to current phase
• Section 0.6: dependency_graph → requires[] and called_by[] per component (for RISK_GUARD map)
• Section 0.5: module registry state (for post-phase drift report)

If Section 0 is absent:

⚠ Architecture file found but has no Section 0 (Agent Contract).
  Running /gg-skill-architecture -f {path} -enh first is recommended.
  Proceeding without architecture contract injection.

---

Phase 2 — Spec Quality Gate

Scan the spec file for [TBD] markers.

In task definitions or acceptance criteria:

⛔ Spec gate failed — [TBD] markers found in task definitions:
  - Task {ID}: "{line containing [TBD]}"

  Options:
    1. Fix [TBD] items and re-run
    2. Use -from / -to to skip affected tasks
    3. Confirm to proceed anyway (not recommended)

  Waiting for input...

In non-critical sections (rationale, notes, context): log warning, do not block.

In -a mode: gate still fires — full autonomy does not bypass incomplete specs.

---

Phase 3 — RISK_GUARD Map

Identify all components tagged # [RISK_GUARD] or in intent: # [RISK_GUARD] blocks. For each, extract: id, path, constraint, validation assertion.

Cross-reference with spec tasks: identify which tasks touch a RISK_GUARD component by name match.

---

Phase 4 — Build Enriched Constraints Block

Assemble the full constraints preamble to inject into execute-phase. See references/contract-format.md for the complete block structure.

---

Phase 5 — Invoke execute-phase

Skill: execute-phase
Arguments: {original flags without -arch}
Preamble: {enriched constraints block from Phase 4}

Let execute-phase manage the full S00→S08 workflow.

---

Phase 7 — Post-Phase Drift Report

Step 1 — Update dep-tree:

• If dep-tree.md exists → invoke gg-skill-dep-tree -u -p N automatically
• If absent → ℹ dep-tree.md absent. Run /gg-skill-dep-tree to initialize.

Step 2 — Architecture Drift Check:

For each module in registry with state: TO_BUILD:
  IF module now appears in dep-tree → flag as newly BUILT

For each file in dep-tree not in registry:
  → flag as UNREGISTERED (potential architecture drift)

For each RISK_GUARD component touched this phase:
  → verify validation assertion was satisfied
  → report: PASSED / FAILED / NOT_VERIFIED

Output drift report in chat:

## Post-Phase Drift Report — Phase {N}

### Module Registry Delta
  ✅ Newly built: {list}
  ⚠  Unregistered: {list — may need architecture update}

### RISK_GUARD Validation
  ✅ {ComponentName}: assertion passed
  ❌ {ComponentName}: assertion FAILED — {what failed}
  ⚠  {ComponentName}: not verified (no test output found)

### Architecture Sync
  → Run: /gg-skill-architecture -f architecture-patched.md -update
    {IF unregistered files exist}
  → Architecture in sync. Ready for Phase {N+1}.
    {IF all modules registered and RISK_GUARD passed}

---

Pre-flight Summary

Output before invoking execute-phase:

## gg-skill-phase — Pre-flight Summary

Architecture contract: {✅ injected from architecture-patched.md | ✅ injected from architecture.md (upgrade recommended)}
Spec gate:            {✅ 0 [TBD] blockers | ⛔ {N} blockers — halted}
Enhancement:          {✅ B1/B2/B3 injected from phaseN-enhancement.md | ℹ no -enh flag}

Hard constraints injected:   {N}
Forbidden patterns injected: {N}
Anti-patterns injected:      {N}
Test expectations injected:  {N} (phase-relevant only)

⚠ RISK_GUARD components touched by this phase:
  {IF none: ℹ none — no RISK_GUARD components in scope}
  {IF any:
    - {ComponentName} → {constraint (one line)} → validation: {test_expectation name}
    These components have extra validation assertions injected into execute-phase.
    Review test output carefully after tasks touching them.}

Invoking execute-phase...

---

DO / DON'T

DO:

• Inject architecture Section 0 verbatim — do not summarize or paraphrase constraints
• Gate on spec [TBD] even in -a mode
• Gate on missing architecture file — offer clear recovery options
• Surface RISK_GUARD components once in Pre-flight Summary — one consolidated warning

DON'T:

• Re-read or re-generate the spec — only validate it
• Override architecture constraints with spec content — Section 0 wins
• Silently skip the architecture gate
• Mention dep-tree.md or architecture files in output unless a decision comes from them

---

Examples

# Standard execution with architecture contract
/gg-skill-phase -a -p 1

# With enhancement + adversarial review (-enh 6 implies -p 6)
/gg-skill-phase -a -x -enh 6

# Custom architecture path
/gg-skill-phase -a -p 3 -arch docs/architecture-patched.md

# Backend only, interactive
/gg-skill-phase -g BE -p 7

# Full pipeline
/gg-skill-phase -a -s -pr -ci -enh 5

---

Success Criteria

• Architecture Section 0 found and injected (or absence warned)
• Spec had 0 [TBD] blockers in task definitions before execute-phase was invoked
• RISK_GUARD map built and constraints injected for relevant tasks
• Enhancement B1/B2/B3 injected if -enh provided
• execute-phase ran S00→S08
• Post-phase drift report produced after S08
• dep-tree updated (or absence flagged)