>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588761. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The <code>migration_completed</code> state event is logged before Phase 7 finishes, resulting in pages containing only skeleton (header + footer) when the migration is declared done &mdash; directly triggering an entire follow-up recovery session to repair the damage.</p> <p>In a recorded session, <code>migration_completed</code> was logged at <code>2026-04-22T16:53:35Z</code>. The component-page-map at the start of the next session showed 7 of 8 pages with only 2 components (<code>site-footer</code>, <code>site-header</code>); only the homepage had real content (13 components). The premature completion declaration triggered an 11-hour second session with 20+ context rollovers and 64 minutes of dead time from menu failures &mdash; purely as a recovery operation. This is the most expensive defect class in the corpus.</p> <p>The root cause: <code>migration_completed</code> fires when Phase 7 starts (or reaches an intermediate checkpoint), not when it finishes successfully with real content. There is no terminal completion gate that checks all pages exist as JSON files, each has 3+ non-skeleton components, all media is uploaded, and all earlier gates passed.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run a migrate-site session against a multi-page site, allow it to enter Phase 7 but exhaust its budget before composing all pages.</li> <li>Inspect <code>state.jsonl</code> for <code>migration_completed</code> events.</li> <li>Inspect <code>content/page/*.json</code>: most pages contain only header + footer.</li> <li>Observe: <code>migration_completed</code> exists despite empty pages.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Move the <code>migration_completed</code> log out of Phase 7 dispatch into a new Phase 8 final completion gate that runs <em>after</em> Phase 7:</p> <pre>PHASE 8 &mdash; Final Completion Gate Run artifact-checker with these criteria: 1. All pages in page inventory have page JSON files in content/page/ 2. Each page JSON has at least 3 components EXCLUDING site-header and site-footer 3. All media files uploaded (media-map.md shows no "pending" entries) 4. All hard gates have "passed: true" in their checklist JSON files Only after all 4 criteria pass may you log migration_completed in state.jsonl. Write 08-migration-complete-checklist.json to docs/migration/workflow/.</pre><p>If Phase 8 fails: the orchestrator MUST NOT log <code>migration_completed</code>. Instead, list the failing pages with their component counts, dispatch content-composer agents for them, and re-run Phase 8.</p> <p>Add a session-start guard: if <code>state.jsonl</code> has <code>migration_completed</code> but <code>08-migration-complete-checklist.json</code> does not exist, treat the migration as incomplete and surface a warning.</p> <p><strong>Optional fifth criterion (per scope-update note):</strong> use the <code>canvas:page:read</code> scope token (verified by 1-08) to query <code>/api/page/{uuid}</code> and verify components exist server-side, not just locally. This provides ground-truth verification.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Move the <code>migration_completed</code> state event log from Phase 7 to a new Phase 8 gate.</li> <li>Add Phase 8 Final Completion Gate text to SKILL.md.</li> <li>Extend artifact-checker to validate the four criteria; add the <code>08-migration-complete-checklist.json</code> artifact template.</li> <li>Add session-start guard for orphaned completion signals.</li> <li>Verify by intentionally leaving 2 pages uncomposed &mdash; Phase 8 must FAIL and the migration must NOT be declared complete.</li> <li>Verify on full success &mdash; <code>08-migration-complete-checklist.json</code> exists with <code>passed: true</code> for all four criteria.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None internal. Optionally consumes <code>GET /api/page/{uuid}</code> with a <code>canvas:page:read</code> token for ground-truth verification (criterion 5 &mdash; depends on 1-08).</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifact: <code>docs/migration/workflow/08-migration-complete-checklist.json</code>. The <code>migration_completed</code> state event semantics change: emitted only after Phase 8 passes.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-1-Foundations/06-P2-9-stale-migration-completed-empty-pages.md</code> (id: P2-9)</li> <li>I1 evidence: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/issues-found.md</code></li> <li>Phase 8 verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (Phase 8 Final Completion Gate block)</li> <li>CRITICAL deep finding: <code>RESEARCH-2026-04-28/00-existing-issues/prior-deep-analysis-key-points.md</code> ("Only 4 of 8 pages were composed")</li> <li>Empirical scope evidence: <code>RESEARCH-2026-04-28/99-final/SCOPE-PROBE-FINDINGS-2026-05-01.md</code> &sect; 4 (canvas:page:read works at <code>/api/page/{uuid}</code>) and &sect; 5 (path.alias inline ignored &mdash; see related issue NEW-12)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/patterns.md</code> &sect; A1</li> <li>Anti-pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/session-anti-patterns.md</code> &sect; AP2</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Exact location of <code>migration_completed</code> emission in current SKILL.md needs to be identified before moving it.</li> <li>"3 components excluding header/footer" threshold &mdash; appropriate, or too low? Homepage had 13; threshold of 5 may be more meaningful.</li> <li>Extend existing <code>artifact-checker.md</code> or create a new <code>phase-reviewer.md</code> agent for Phase 8?</li> <li>Does <code>canvas:page:create</code> set <code>path.alias</code> inline? Empirical probe says NO &mdash; see related issue NEW-12 (Sprint 2). If aliases require a separate write, Phase 8 may need an alias-verification criterion too.</li> </ul>