scholaraio

ScholarAIO Directory Migration Execution Sequence

Status: Historical compatibility-window record

Last Updated: 2026-04-24

Scope: historical execution order for directory and path migration. This file preserves the compatibility-window migration record; it is no longer the source of truth for the active breaking-cleanup runtime.

2026-04-24 breaking cleanup note:

1. Purpose

This document defines the recommended execution order for migrating ScholarAIO toward the target directory structure described in docs/development/directory-structure-spec.md.

This is an implementation-order document, not a vision document. Its job is to answer:

This document should be read together with:

That companion document defines the control-plane contract (instance.json, migration.lock, journal, verification, cleanup gating). This document defines when that machinery must appear in the execution order.

2. Audited Baseline

The sequence below is based on direct inspection of the current codebase and on path-related regression tests revalidated on 2026-04-19 after the earlier 2026-04-16, 2026-04-17, and 2026-04-18 audits.

2.1 Code Areas Audited

The entries in this subsection describe the compatibility-window state that was audited before the 2026-04-24 breaking cleanup. Parenthetical legacy import paths below are historical targets from that window; they are not active public facades in the current release generation.

Historical audited facts from the compatibility-window generation:

The following bullets intentionally preserve the pre-cleanup compatibility language used during migration planning. In the active release generation, legacy public import facades have been removed; see docs/development/breaking-compat-cleanup-plan.md and docs/guide/agent-reference.md for the current contract.

2.2 Tests Run

The following test batches were executed successfully as migration-baseline verification:

python -m pytest -q \
  tests/test_cursor_rules.py \
  tests/test_writing_docs_alignment.py \
  tests/test_academic_writing_skills.py \
  tests/test_skill_routing_smoke.py \
  tests/test_workspace.py \
  tests/test_config.py

python -m pytest -q \
  tests/test_explore.py \
  tests/test_translate.py \
  tests/test_webtools_source.py \
  tests/test_ingest_link_cli.py \
  tests/test_proceedings.py \
  tests/test_cli_messages.py

# 2026-04-17 revalidation after additional develop-branch merges
python -m pytest -q \
  tests/test_config.py \
  tests/test_explore.py \
  tests/test_translate.py \
  tests/test_proceedings.py \
  tests/test_metrics.py

python -m pytest -q \
  tests/test_patent_tools.py \
  tests/test_backup.py \
  tests/test_diagram.py \
  tests/test_document.py

Observed result:

3. Non-Negotiable Invariants

These constraints are already enforced by current code, wrappers, and tests. The migration sequence MUST treat them as frozen until their replacements are intentionally designed and tested.

3.1 Config Discovery Invariant

Compatibility-window behavior in scholaraio/core/config.py (before removal of the legacy scholaraio.config import path):

Implication:

3.2 Root Agent Integration Invariant

Current wrappers and tests assume fixed root-level entry points:

Implication:

3.3 Canonical Skill Root Invariant

Current audited behavior:

Implication:

3.4 Runtime Top-Level Compatibility Invariant

Current code assumes both of the following runtime top-level directories exist:

Implication:

3.5 Method Invariant

Migration MUST follow this order:

  1. freeze invariants and tests
  2. add path accessors
  3. switch consumers to accessors
  4. add compatibility readers/writers if formats change
  5. perform physical moves last

Direct physical directory moves before consumer cutover are explicitly out of order.

4. Current Coupling Summary

The execution order below follows the actual current coupling, not the desired architecture.

4.1 Config Is Now the Runtime Path Authority for First Migration Roots

scholaraio/core/config.py currently exposes accessors for the major runtime roots:

ensure_dirs() now routes through these accessors rather than recreating fixed legacy strings.

Implication:

4.2 Workspace Contract Is Hardcoded in Both Code and Tests

Current behavior:

Implication:

4.3 Ingest and Queue Paths Are Concentrated in pipeline.py

Current behavior:

Implication:

4.4 Leaf Stores Already Form Natural Low-Risk Migration Units

Current audited path helpers:

Implication:

4.5 Backup Scope Is Not a Migration Contract

Current behavior:

Implication:

5. Execution Order

The migration is split into two tracks:

Track A is the critical path and MUST happen first. Track B SHOULD begin only after Track A has established stable accessors and compatibility layers.

6. Track A: Runtime-Instance Migration

Phase A0. Freeze Invariants and Expand Regression Coverage

Objective:

Actions:

Do not do yet:

Exit criteria:

Phase A1. Make Config the Complete Path Authority

Objective:

Primary audit reference:

Required additions in or around scholaraio/core/config.py:

Immediate consumer updates in this phase:

Rationale:

Exit criteria:

Phase A2. Cut Over Leaf Store Consumers First

Objective:

Modules in scope:

Required changes:

Why this phase comes early:

Exit criteria:

Phase A3. Cut Over Shallow CLI and Analytics Consumers

Objective:

Modules in scope:

Required changes:

Why this phase is separate from A2:

Exit criteria:

Phase A4. Introduce Workspace Compatibility Layer Before Workspace Migration

Objective:

Current constraint:

Required changes:

Do not do yet:

Rationale:

Phase A4 Outcome: Workspace Topology Decision

For the compatibility window and the next migration design pass, the workspace-topology direction is now fixed:

Exit criteria:

Implementation status (2026-04-20):

Phase A5. Abstract Queue and Proceedings Paths in pipeline.py

Objective:

Modules in scope:

Required changes:

Why this is late:

Exit criteria:

Phase A6. Split State/Cache/Runtime Logically Before Moving Libraries

Objective:

Current central state locations:

Required changes:

Why this phase precedes major library moves:

Exit criteria:

Implementation status (2026-04-19):

Phase A6.5. Introduce Migration Control Plane Before Physical Moves

Objective:

Required changes:

Required reference:

Why this phase exists here:

Exit criteria:

Historical implementation status during the compatibility window (2026-04-23, superseded by the 2026-04-24 breaking cleanup):

The bullets below are retained as an execution log. Statements that a legacy module path “remains” an alias refer to the compatibility-window implementation, not to the active release generation.

Phase A7. Physically Move Isolated Libraries First

Objective:

Recommended move order:

  1. citation_styles
  2. toolref
  3. explore

Target subtree:

Recommended approach:

Why these three come first:

Exit criteria:

Phase A8. Move proceedings as a Durable Library

Objective:

Target:

Why this is not grouped with A7:

Why this still happens before papers:

Exit criteria:

Implementation status (2026-04-20):

Phase A9. Physically Move Queue/Spool Subtree

Objective:

Recommended target:

Notes:

Exit criteria:

Implementation status (2026-04-20):

Phase A10. Move papers Last

Objective:

Target:

Why this is last:

Required preconditions:

Exit criteria:

Implementation status (2026-04-20):

Phase A11. Freeze Compatibility Window and Update Public Docs

Objective:

Actions:

Exit criteria:

Do not do yet:

Implementation status (2026-04-20):

7. Track B: Source-Repository Package Migration

Track B is intentionally later and slower than Track A.

Phase B0. Reserve gui/ Immediately

Low-risk action:

Constraint:

Implementation status (2026-04-20):

Phase B1. Introduce New Package Namespaces Without Moving Behavior Yet

Recommended target namespaces:

Method:

Why not earlier:

Historical implementation status during the compatibility window (2026-04-23; superseded by the 2026-04-24 breaking cleanup):

Phase B2. Move Low-Coupling Modules Before Central Orchestrators

Recommended order:

  1. store-like or provider-like leaves
    • toolref/*
    • explore.py
    • citation_styles.py
    • proceedings.py
    • sources/webtools.py
    • uspto_odp.py
    • uspto_ppubs.py
  2. project boundary module
    • workspace.py
  3. service modules
    • diagram.py
    • translate.py
    • insights.py
    • ingest metadata helpers

Additional constraint for webtools:

Late movers:

Reason:

Historical implementation status during the compatibility window (2026-04-23; superseded by the 2026-04-24 breaking cleanup):

The bullets below are retained as historical execution notes. Statements that a legacy module path “remains” an alias do not describe the active breaking-cleanup release generation.

Phase B3. Split cli.py and pipeline.py Last

Recommended target:

Precondition:

Implementation status (2026-04-20):

8. Items Explicitly Deferred

The following implementation details should remain deferred until the earlier phases above are complete:

9. Practical Summary

The safe execution order is:

  1. freeze root integration and config invariants
  2. make Config the complete path authority
  3. convert leaf modules and shallow CLI consumers to accessors
  4. introduce a workspace compatibility layer
  5. abstract queue/proceedings paths in pipeline.py
  6. separate state/cache/runtime logically
  7. move isolated libraries first
  8. move proceedings as a durable library
  9. move queue/spool paths
  10. move papers last
  11. clean up compatibility layers

Anything that starts by directly renaming data/, workspace/, or .claude/skills/ is not aligned with the audited current codebase.

This site is open source. Improve this page.