>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588797. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Two distinct organizational debts in <code>docs/migration/</code> should be resolved together in a single dedicated pass:</p> <ol> <li><strong>Flat <code>content/</code> vs hierarchical <code>pages/</code>.</strong> Per-page content files live flat in <code>content/&lt;slug&gt;.md</code>, but every other per-page artifact (page manifest, screenshots) already lives in slug-named subdirectories under <code>pages/</code>. Agents that work with a page must look in three separate places: <code>pages/&lt;slug&gt;/index.json</code>, <code>screenshots/pages/&lt;slug&gt;/</code>, and <code>content/&lt;slug&gt;.md</code>. Merging into a single <code>pages/&lt;slug&gt;/</code> bundle creates self-contained per-page directories.</li> <li><strong>20+ root-level files of mixed type.</strong> State telemetry, schemas, derived aggregates, discovery artifacts, and runtime results all cohabit <code>docs/migration/</code> root. The <code>workflow/</code> subdirectory exists but is underused. Each phase added artifacts organically without a unified layout plan.</li> </ol> <p>The combined blast radius is HIGH: 47 unique <code>docs/migration/*</code> paths are referenced across agents, skills, reference documentation, and scripts. A partial restructure that misses even a handful of references produces silent path-not-found failures during migrations. The two issues must be done together, in isolation, with a comprehensive grep-then-update-then-test approach.</p> <p>This is organizational debt accumulated through organic growth, not a bug. It is the most blast-radius-heavy change in the entire backlog and must run only after all P0/P1 functional fixes (Sprint 1&ndash;6) are complete and deployed, to avoid merge conflicts and double-touch on agent files.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>From the project root, run <code>find docs/migration -maxdepth 1 -type f | wc -l</code> &mdash; observe 20+ files of mixed type at the root.</li> <li>Run <code>ls docs/migration/content/</code> and compare to <code>ls docs/migration/pages/</code> &mdash; observe content is flat, while pages is hierarchical with per-slug subdirectories.</li> <li>Run <code>grep -rn "docs/migration/" .claude/skills/ .claude/agents/ scripts/ --include="*.md" --include="*.mjs" --include="*.js" --include="*.json" --include="*.sh"</code> &mdash; observe 47 unique path references across agent definitions, skill files, scripts, and reference docs.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Target per-page bundle layout</strong> (from FOR_LATER Issue #2):</p> <pre>docs/migration/pages/about/ &#9500;&#9472;&#9472; index.json (existing page manifest) &#9500;&#9472;&#9472; content.md (moved from content/about.md) &#9500;&#9472;&#9472; desktop/ (moved from screenshots/pages/about/desktop/) &#9492;&#9472;&#9472; mobile/ (moved from screenshots/pages/about/mobile/)</pre><p>Self-contained per-page bundle. Everything about a page lives together.</p> <p><strong>Target root layout</strong> (from FOR_LATER Issue #3 natural-groupings table):</p> <table> <thead> <tr> <th>Group</th> <th>Files</th> <th>Proposed home</th> </tr> </thead> <tbody> <tr> <td>State / telemetry</td> <td>state.jsonl, timing.jsonl, token-usage.jsonl, progress.json, progress.md</td> <td><code>workflow/</code></td> </tr> <tr> <td>Schema / registry</td> <td>state-envelope.schema.json, workflow-state-files.md</td> <td><code>workflow/</code></td> </tr> <tr> <td>Derived aggregates</td> <td>component-map.{json,md}, component-page-map.json, components.json, phase1-summary.{json,md}</td> <td><code>derived/</code> or keep at root (decision)</td> </tr> <tr> <td>Discovery artifacts</td> <td>plan.md, section-reference.md, media-map.md, design-tokens.json, logo.png, decisions.md</td> <td>root (primary docs) or <code>artifacts/</code> (decision)</td> </tr> <tr> <td>Runtime / preflight</td> <td>preflight-result.json</td> <td><code>workflow/</code></td> </tr> </tbody> </table> <p><strong>Execution procedure:</strong></p> <ol> <li><strong>Before touching anything:</strong> Run <code>grep -rn "docs/migration/" .claude/skills/ .claude/agents/ scripts/ --include="*.md" --include="*.mjs" --include="*.js" --include="*.json" --include="*.sh" | sort -t: -k1,1</code> to enumerate all 47+ references. Save as the change manifest.</li> <li><strong>Confirm target layout with user</strong> (see Open questions for the two unresolved layout decisions).</li> <li><strong>Move files on disk</strong> per the confirmed target: merge <code>content/&lt;slug&gt;.md</code> into <code>pages/&lt;slug&gt;/content.md</code>; merge <code>screenshots/pages/&lt;slug&gt;/{desktop,mobile}/</code> into <code>pages/&lt;slug&gt;/{desktop,mobile}/</code>; move state/telemetry/schema/preflight files into <code>workflow/</code>.</li> <li><strong>Update each reference from step 1.</strong> Group updates by file to avoid N+1 edits.</li> <li><strong>Re-run the grep</strong> and verify zero matches for old path patterns.</li> <li><strong>Functional test:</strong> trigger a short migration run (or use the existing test harness) to confirm no broken path references produce runtime errors.</li> <li><strong>Commit as a single dedicated commit</strong> &mdash; do not interleave with any functional change. Suggested message: "refactor: migrate docs/migration/ to hierarchical per-page layout (47 path references updated)".</li> </ol> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Confirm with user: discovery artifacts at root vs <code>artifacts/</code>.</li> <li>Confirm with user: derived aggregates at root vs <code>derived/</code>.</li> <li>Confirm with user: screenshot merge into <code>pages/&lt;slug&gt;/desktop|mobile/</code> is acceptable (storybook-qa and visual-verifier use these paths heavily).</li> <li>Confirm with user: Sprint 1&ndash;6 are complete and deployed before this sprint begins.</li> <li>Run the comprehensive grep and save the change manifest.</li> <li>Move files on disk per the confirmed target layout.</li> <li>Update <code>.claude/skills/migrate-site/SKILL.md</code> &mdash; artifact path table and all phase descriptions referencing <code>content/&lt;slug&gt;</code>, <code>screenshots/pages/&lt;slug&gt;</code>, and root-level state files.</li> <li>Update <code>.claude/agents/site-analyzer.md</code>, <code>artifact-checker.md</code>, <code>content-composer.md</code>, <code>phase-verifier.md</code>, <code>storybook-qa.md</code>, <code>visual-verifier.md</code>.</li> <li>Update <code>scripts/finalize-bundle-run.mjs</code> (writes component-map, component-page-map, components, phase1-summary) and <code>scripts/capture-component-bundle.mjs</code>.</li> <li>Update <code>docs/migration/artifact-formats.md</code> if present, and any other <code>.md</code>, <code>.mjs</code>, <code>.js</code>, <code>.json</code>, <code>.sh</code> file referencing the moved paths.</li> <li>Re-run grep with old patterns and confirm zero hits.</li> <li>Run a functional migration test; verify no "file not found" errors.</li> <li>Single dedicated commit.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>On-disk artifact paths under <code>docs/migration/</code> are reorganized; no semantic change to artifact contents. Specifically:</p> <ul> <li><code>content/&lt;slug&gt;.md</code> &rarr; <code>pages/&lt;slug&gt;/content.md</code></li> <li><code>screenshots/pages/&lt;slug&gt;/{desktop,mobile}/</code> &rarr; <code>pages/&lt;slug&gt;/{desktop,mobile}/</code></li> <li><code>state.jsonl</code>, <code>timing.jsonl</code>, <code>token-usage.jsonl</code>, <code>progress.json</code>, <code>progress.md</code> &rarr; <code>workflow/</code></li> <li><code>state-envelope.schema.json</code>, <code>workflow-state-files.md</code> &rarr; <code>workflow/</code></li> <li><code>preflight-result.json</code> &rarr; <code>workflow/</code></li> <li>Derived aggregates and discovery artifacts: pending user decision (root vs <code>derived/</code> / <code>artifacts/</code>).</li> </ul> <p><strong>Verification queries</strong> (must all pass post-change):</p> <ul> <li><code>grep -rn "docs/migration/content/" .claude/ scripts/</code> returns zero results.</li> <li><code>grep -rn "docs/migration/screenshots/pages/" .claude/ scripts/</code> returns zero results.</li> <li><code>grep -rn "docs/migration/state.jsonl\|docs/migration/timing.jsonl\|docs/migration/token-usage.jsonl" .claude/ scripts/</code> returns only <code>workflow/</code> paths.</li> <li><code>find docs/migration -maxdepth 1 -type f | wc -l</code> shows significantly fewer root files (target: discovery artifacts only, if user keeps them at root).</li> <li>A migration run completes without any "file not found" errors referencing <code>docs/migration/</code>.</li> </ul> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-7-Organizational-Debt/02-P2-1-migration-directory-restructure.md</code> (id: P2-1)</li> <li>Proposed restructure source: <code>RESEARCH-2026-04-28/00-existing-issues/for-later-issues.md</code> Issue #2 (per-page bundles) and Issue #3 (root grouping)</li> <li>Blast radius and execution guidance: <code>RESEARCH-2026-04-28/00-existing-issues/for-later-issues.md</code> &sect; Execution guidance</li> <li>Root cause and consolidation: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P2-1</li> <li>Context cost connection: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P0-5 (root clutter contributes to context window explosion)</li> <li>Skill audit overlap: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P2-3</li> <li>Actionable list row: <code>RESEARCH-2026-04-28/99-final/actionable-list.md</code> (P2-1)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li><strong>Root-level discovery artifacts:</strong> Should <code>plan.md</code>, <code>section-reference.md</code>, <code>media-map.md</code>, <code>decisions.md</code>, <code>design-tokens.json</code>, <code>logo.png</code> stay at root as primary docs, or move into an <code>artifacts/</code> subdirectory?</li> <li><strong>Derived aggregates:</strong> Should <code>component-map.{json,md}</code>, <code>component-page-map.json</code>, <code>components.json</code>, <code>phase1-summary.{json,md}</code> move into <code>derived/</code>, or stay at root?</li> <li><strong>Screenshots merge:</strong> Confirm moving <code>screenshots/pages/&lt;slug&gt;/</code> into <code>pages/&lt;slug&gt;/desktop|mobile/</code> is acceptable. The storybook-qa and visual-verifier agents use these paths heavily and will require coordinated updates.</li> <li><strong>Timing:</strong> Confirm this sprint runs only after all Sprint 1&ndash;6 functional fixes are complete and deployed. Any in-flight Sprint 1&ndash;6 work that touches agent files will create merge conflicts with this restructure.</li> </ul>