# Phase 08: Git Workflow & Commit

## Entry Gate

```bash
devforgeai-validate phase-check ${STORY_ID} --from=07 --to=08
# Exit 0: proceed | Exit 1: Phase 07 incomplete (DoD not validated) | Exit 2: DoD validation failed
```

## Contract

PURPOSE: Stage files, create a properly formatted git commit, and verify commit success.
REQUIRED SUBAGENTS: None (git operations only)
REQUIRED ARTIFACTS: None
STEP COUNT: 6 mandatory steps

**GIT POLICY:** See `.claude/rules/core/git-operations.md` for safe vs approval-required operations.

## Reference Loading [MANDATORY]

```
# No required references for this phase. Self-contained — git workflow
# operations only; error-recovery Read of
# .claude/rules/workflow/commit-failure-recovery.md sits outside the 4
# declared categories (skill ref / context file / memory / story).
```

---

## Mandatory Steps

### Step 1: Budget Enforcement Check

EXECUTE: Check deferral budget for this story via CLI.
```bash
devforgeai-validate check-deferral-budget --story-file=${STORY_FILE} --project-root=${PROJECT_ROOT}
```
VERIFY: Exit code 0 = within budget.
```
IF exit code == 1: HALT — "Deferral budget exceeded."
IF new incomplete items detected: Return to Phase 06.
```

### Step 2: Stage Files for Commit

EXECUTE: Stage all relevant files.
```bash
git add ${STORY_FILE}
git add ${IMPL_FILES}    # Implementation files created/modified
git add ${TEST_FILES}    # Test files from Phase 02
```
VERIFY: Files staged successfully.
```bash
git status --porcelain
# Verify expected files appear with 'A' or 'M' status
```

### Step 3: Create Git Commit

EXECUTE: Create commit with conventional commit format.
```bash
git commit -m "feat(${STORY_ID}): ${STORY_TITLE}

- Implemented ${FEATURE_DESCRIPTION}
- Tests passing (${PASS_COUNT}/${TOTAL_COUNT})
- Coverage: ${COVERAGE}%

Refs: ${STORY_ID}"
```
**Commit types:** feat, fix, refactor, test, docs
VERIFY: Commit succeeds (exit code 0).
```
IF exit code != 0:
  # Pre-commit hook blocked. `--no-verify` is hook-blocked by `pre-commit-no-verify-guard.sh` (exit 2).
  Read(file_path=".claude/rules/workflow/commit-failure-recovery.md")
  # Follow recovery workflow.
```

### Step 4: Verify Commit Success

EXECUTE: Confirm the commit was created.
```bash
git log -1 --format="%H %s"
```
VERIFY: Output shows new commit hash and message matching the story.
```
IF no new commit: HALT — "Git commit did not succeed."
```

### Step 5: Update AC Checklist (Deployment Items) [CONDITIONAL: ac_checklist_updates_enabled]

CONDITIONAL: If `ac_checklist_updates_enabled` is false, SKIP this step. Rely on Phase 07 DoD tracking instead. Default: true.

EXECUTE: Mark git/deployment-related acceptance criteria as completed.
```bash
devforgeai-validate update-ac-checklist --story-file=${STORY_FILE} --category=deployment
```
VERIFY: Exit code 0 = items updated. Command displays progress summary.

### Step 6: Capture Observations

EXECUTE: Write observation file for this phase via CLI.
```bash
devforgeai-validate write-observation --story=${STORY_ID} --phase=08 --observations='${OBS_JSON}' --project-root=${PROJECT_ROOT}
```
OBS_JSON must be a JSON array. Each object requires 7 fields: `id` (obs-STORY-NNN-08-001), `phase` (08), `source` (agent name), `category` (friction|success|pattern|gap|idea|bug), `note` (description), `severity` (low|medium|high), `timestamp` (ISO 8601).
VERIFY: Exit code 0 = observation file written. Non-blocking on failure.

---

## Exit Gate

```bash
devforgeai-validate phase-complete ${STORY_ID} --phase=08 --checkpoint-passed
# Exit 0: proceed to Phase 09 | Exit 1: commit failed
```
