# Phase 06 — Commit & Memory

**Mode:** INLINE (orchestrator performs every git operation; user authorization implicit from Phase 05 Verdict = READY-TO-COMMIT).
**Workflow CLI param:** `--workflow=migration`.
**Inputs (must exist on entry):** `tmp/${MIGRATION_ID}/verification-report.md` with Verdict `READY-TO-COMMIT` (a `DRY-RUN-COMPLETE` Verdict HALTs before Phase 06; a `DEFER-WITH-OPEN-FLAGS` Verdict was rejected at Phase 05 exit).
**Outputs (must exist on exit):** One git commit containing exactly the migration's edits (no working-tree noise); `tmp/${MIGRATION_ID}/session.md` appended with the commit hash and timestamp for resume capability.

---

## Entry Gate [MANDATORY]

```bash
devforgeai-validate phase-check ${SESSION_ID} --workflow=migration --from=05 --to=06
```
IF exit != 0: HALT — Phase 05 incomplete, OR Verdict was not READY-TO-COMMIT.

Read the verification report Verdict line:
```
Grep(pattern="^## Verdict$|^- (READY-TO-COMMIT|DEFER-WITH-OPEN-FLAGS|DRY-RUN-COMPLETE)$", path="tmp/${MIGRATION_ID}/verification-report.md")
```
IF Verdict is not `READY-TO-COMMIT`: HALT — Phase 06 must not commit a dry-run or deferred-flag migration.

---

## Reference Loading [MANDATORY]

```
# No required references for this phase. Phase 06 reads the workflow's
# phase-04-cluster-reports.md, design-sensitive-handled.md, and
# verification-report.md artifacts (all produced by Phases 03-05) to
# compose the commit body, then executes git add/commit and appends to
# session.md. No skill reference Reads are required.
```

---

## Step 6.1: Stage Migration Files (Explicit Add, NOT `git add -A`)

The DevForgeAI working tree carries standing noise patterns that MUST NOT enter the migration commit. Per the long-standing carve-out protocol ([[feedback_multi_pr_carveout_workflow.md]] precedent): use explicit `git add <path>` of the migration's edited paths — NEVER `git add -A` or `git add .`.

**EXECUTE:**

Build the staging set from the consolidated cluster reports + design-sensitive log + FLAGGED resolutions:
```
Read(file_path="tmp/${MIGRATION_ID}/phase-04-cluster-reports.md")
Read(file_path="tmp/${MIGRATION_ID}/design-sensitive-handled.md")
Read(file_path="tmp/${MIGRATION_ID}/verification-report.md")
```

Extract the union of:
- Every file listed under "## (a) Files edited" across the cluster reports (both .claude/ and src/claude/ pairs).
- Every file listed in the design-sensitive log (both copies).
- Every file edited during Step 5.3 FLAGGED resolution (both copies).

Then stage explicitly:
```bash
git add <path-1> <path-2> ... <path-N>
```
Batch as needed (one `git add` invocation per ~50 paths to keep the command line tractable).

**Explicit exclusions (standing noise):**
The following paths MUST NOT be staged even if they appear modified — they are independent ongoing working-tree noise:
- `.claude/settings.local.json`
- `.claude/agent-memory/*/MEMORY.md`
- `devforgeai/logs/*`
- `devforgeai/feedback/ai-analysis/*/.conviction-evidence.jsonl`

If any of these paths are dirty in the working tree, leave them unstaged. Do not `git restore` them — they are independent state owned by other workflows.

**VERIFY:**
- `git status --short` shows the migration files as staged (`M`/`A` in column 1).
- The 4 noise patterns above are NOT in the staged-column listing.

**RECORD:**
```bash
devforgeai-validate phase-record ${SESSION_ID} --workflow=migration --phase=06 --step=staged
```

---

## Step 6.2: Verify Staged Set Excludes Noise

The previous step's `git add` was explicit, but defense-in-depth is non-negotiable here — a single accidental `git add -A` upstream could have polluted the index. Verify the staged set is exactly the migration scope.

**EXECUTE:**
```bash
git diff --cached --name-only > /tmp/.staged-check-${MIGRATION_ID}
```
Then re-inspect by reading the file in-context — but per CLAUDE.md project-scoped tmp rule, route through the project's tmp dir:
```bash
git diff --cached --name-only
```
and capture the output directly. Grep for each noise pattern:
```bash
git diff --cached --name-only | grep -E '(\.claude/settings\.local\.json|\.claude/agent-memory/.*/MEMORY\.md|devforgeai/logs/|\.conviction-evidence\.jsonl)' || echo "CLEAN"
```
The expected output is the literal string `CLEAN` (the grep finds nothing; `||` triggers).

**VERIFY:**
- The grep returned `CLEAN`.
- The total staged file count matches (within ±2 for any FLAGGED-resolution files added late) the count expected from Step 6.1's union calculation.

IF the grep matched any noise pattern: HALT — unstage that path with `git restore --staged <path>` (user-approval-gated per git-operations.md if needed) and re-verify. Do NOT proceed to commit until CLEAN.

**RECORD:**
```bash
devforgeai-validate phase-record ${SESSION_ID} --workflow=migration --phase=06 --step=noise-excluded
```

---

## Step 6.3: Commit with Provenance Message

The commit message is the durable provenance record of the migration. The verification report's content becomes the commit body — anyone reviewing the commit can reconstruct the migration's intent, scope, and validation result.

**EXECUTE:**

Compose the commit message:
- **Title:** `feat(migration): <FROM_PATTERN> → <TO_PATTERN> via spec-driven-migration (refs <MIGRATION_ID>)`
  - Example: `feat(migration): source-tree.md → source-tree/ via spec-driven-migration (refs source-tree-2026-05-19)`
- **Body:** populate `assets/templates/migration-report-template.md` (forward-declared; if absent, paste the verification-report.md content directly under the title with two blank lines separating them).

The body MUST include:
- Intent block (from_pattern, to_pattern, to_type, scope_dirs, exclusions).
- Cluster summary (N clusters, total files edited, FLAGGED count).
- Residual classification (per-bucket counts; ZERO transformable).
- FLAGGED resolution count + deferral count.
- Dual-path sweep result (clean).
- Test re-run result (or skip rationale).

Then issue the commit:
```bash
git commit -m "<title>" -m "<body>"
```
(Multi-line bodies — use a heredoc or a temporary message file under `tmp/${MIGRATION_ID}/commit-message.txt`. Do NOT bypass pre-commit hooks; per CLAUDE.md HALT trigger #3, `--no-verify` is forbidden.)

**VERIFY:**
- `git log -1 --format=%H` returns the new commit hash.
- The commit title matches the expected format (Grep `git log -1 --format=%s` for `^feat\(migration\): .* → .* via spec-driven-migration`).
- `git log -1 --stat` shows the expected file count and no noise files.

IF the commit was rejected by a pre-commit hook: HALT — investigate the hook failure. Do NOT retry with `--no-verify`. Per [[feedback_brainstorm_phase_gate_scope_defect]], some phase-gate hooks may falsely block migration commits if a STORY is in Phase 02 elsewhere; the recovery is to suspend the hook externally and re-commit, NOT to bypass.

**RECORD:**
```bash
devforgeai-validate phase-record ${SESSION_ID} --workflow=migration --phase=06 --step=committed
```

---

## Step 6.4: Append Session Record

The session record lives in `tmp/${MIGRATION_ID}/session.md` and is the human-readable resume-capable summary of the migration. Phase 00 reads this on a future re-invocation to determine workflow state.

**EXECUTE:**

Build the session entry:
```
## Session: ${SESSION_ID}
- Captured: <ISO 8601 timestamp>
- MIGRATION_ID: ${MIGRATION_ID}
- FROM_PATTERN: <from intent.json>
- TO_PATTERN:   <from intent.json>
- Commit hash:  <from `git log -1 --format=%H`>
- Files edited: <count from verification report>
- Clusters:     <N>
- FLAGGED resolved: <count>
- FLAGGED deferred: <count>
- Verdict:      READY-TO-COMMIT → COMMITTED
- Artifacts:    tmp/${MIGRATION_ID}/intent.json, classification.md, transform-rules.md, clusters.json, phase-04-cluster-reports.md, design-sensitive-handled.md, verification-report.md
```

If `tmp/${MIGRATION_ID}/session.md` already exists (a prior partial run was resumed), append the entry; otherwise create the file with the entry as its first content.

```
Write(file_path="tmp/${MIGRATION_ID}/session.md", content=<full file content with new entry appended>)
```
(Read-then-Write since the Edit tool would require a unique anchor; per [[feedback_dual_path_mechanical_migration]] the session log is single-path — only `tmp/` — so no dual-path concern here.)

**VERIFY:**
- `tmp/${MIGRATION_ID}/session.md` exists.
- The latest entry's "Commit hash" matches `git log -1 --format=%H`.

**RECORD:**
```bash
devforgeai-validate phase-record ${SESSION_ID} --workflow=migration --phase=06 --step=session-recorded
```

---

## Exit Gate [MANDATORY]

```bash
devforgeai-validate phase-complete ${SESSION_ID} --workflow=migration --phase=06 --checkpoint-passed
```
IF exit != 0: HALT.

Display the final summary to the user — title, commit hash, files-edited count, FLAGGED-deferred count (if any), and the path to `tmp/${MIGRATION_ID}/verification-report.md` for review.

---

## Phase 06 Success Criteria

- [ ] Migration files were staged explicitly via `git add <path>` invocations — NOT `git add -A` / `git add .`.
- [ ] The staged set excludes all 4 standing noise patterns (`settings.local.json`, `agent-memory/MEMORY.md`, `devforgeai/logs/`, `conviction-evidence.jsonl`) — verified by an explicit `git diff --cached --name-only | grep -E 'noise'` returning empty.
- [ ] One commit was created with title `feat(migration): <FROM_PATTERN> → <TO_PATTERN> via spec-driven-migration (refs <MIGRATION_ID>)`.
- [ ] The commit body carries the full verification-report content (Intent + Cluster summary + Residual classification + FLAGGED log + Dual-path sweep + Test re-run).
- [ ] No pre-commit hook was bypassed (`--no-verify` was NOT used).
- [ ] `tmp/${MIGRATION_ID}/session.md` was appended with the new commit hash + timestamp; the file persists for future resume detection.
- [ ] `phase-record` was called for each of the 4 steps (`staged`, `noise-excluded`, `committed`, `session-recorded`).
- [ ] The Exit Gate `phase-complete` returned exit 0.
