ADR-175: Component Migration Process

Status

ACCEPTED

Date

2026-02-11

Context

CODITECT is a multi-repository platform with 97 submodules and 3,458 components (agents, commands, skills, hooks, scripts, workflows, schemas). As the platform matures, components naturally need to move between repositories — from R&D incubation in coditect-core to dedicated product repositories, from product repos to customer-specific repos, or between environments (dev → staging → production).

Problem

Prior to this ADR, CODITECT had 12 migration-related components (skills, agents, hooks, commands), but all handled code-level migrations (database schema changes, naming conventions, framework upgrades). Zero components addressed cross-repository component relocation — the process of moving a component from one repository to another while maintaining framework discoverability.

The first migration (H.22, 2026-02-11) moved the pdf-to-markdown pipeline (4 components, 29 files) from coditect-core to coditect-research-continuum. This exposed the need for a standardized, auditable, repeatable process.

Requirements

1. Discoverability — Migrated components must remain findable by framework discovery (component indexer, search commands, MoE classifier)
2. Auditability — Every migration must produce a complete audit trail (who, what, when, where, why)
3. Reversibility — Migrations must be rollback-capable
4. Standards Compliance — Process must align with ISO 10007, NIST SP 800-128, ITIL v4 change management
5. Customer Applicability — Process must support CODITECT customers moving artifacts between environments (R&D → dev → staging → production)

Decision

We adopt a 12-step interactive migration workflow with a 5-phase execution pipeline as the standard process for all component relocations.

12-Step Workflow

#	Step	Type	Description
1	Initiation	User Input	Specify components, source, target, reason
2	Discovery	Automated	Discover all files for each component
3	Inventory Report	Display	Show migration manifest with file counts
4	Strategy Selection	User Choice	Full Move / Split / Deprecate / Keep Source
5	Preflight Check	Automated	Validate source exists, target writable, no conflicts
6	Dry-Run Preview	Display	Show exact changes that will be made
7	Approval Gate	User Gate	Approve, modify, or abort
8	Execution	Automated	Copy → Stub → Registry updates
9	Verification	Automated	Validate stubs, registries, file counts
10	Audit Log	Automated	Session log + manifest + evidence
11	Commit & Push	User Gate	Bottom-up commit across repos
12	Completion Report	Display	Summary with metrics and next steps

5-Phase Execution Pipeline (Step 8)

PREFLIGHT → COPY → STUB → REGISTRY → VERIFY

Each phase is atomic per component. Failure at any phase triggers rollback of that component.

Redirect Stubs

When a component is migrated, a redirect stub remains in the source repository with:

• status: relocated in frontmatter
• relocated_to, relocated_path, relocated_date, original_path, reason fields
• Human-readable redirect message

This ensures framework discovery continues to find the component and directs users to its new location.

Seven Component Types Supported

Type	Source Pattern	Stub Strategy
skill	skills/{name}/	Directory stub (SKILL.md only)
command	commands/{name}.md	File replacement
agent	agents/{name}.md	File replacement
hook	hooks/{name}.py	Python stub
script	scripts/{name}.py	Python stub
workflow	workflows/{name}.yaml	YAML stub
schema	config/schemas/{name}.schema.json	No stub (copy only)

Registry Updates

Three registries are updated atomically:

1. config/framework-registry.json — Status → relocated, add relocated_to and relocated_date
2. config/component-activation-status.json — Status → relocated
3. config/component-counts.json — Refresh counts via update-component-counts.py

Standards Alignment

Standard	How We Comply
ISO 10007 (Configuration Management)	5 activities mapped: planning, identification, change control, status accounting, verification/audit
NIST SP 800-128 (Security-Focused CM)	Baseline configuration (registry), change control (approval gates), audit trail (session logs), continuous monitoring (stub status)
NIST CSF 2.0	PR.IP-3 (Configuration change control), ID.AM (Asset Management)
ITIL v4	Change enablement (approval gate), release management (bottom-up commit), configuration management (registries)

Alternatives Considered

Alternative 1: Manual File Copy + README Note

• Pros: Simple, no tooling needed
• Cons: No audit trail, no registry updates, stubs not discoverable, error-prone
• Rejected: Fails all standards compliance requirements

Alternative 2: Git Submodule Reference (Symlink)

• Pros: No file duplication, single source of truth
• Cons: Complex git setup, breaks when submodule structure changes, no clear ownership transfer
• Rejected: Doesn't represent actual organizational relocation

Alternative 3: Package Registry (npm/pip publish)

• Pros: Standard distribution mechanism
• Cons: CODITECT components are markdown/YAML, not packages; adds unnecessary complexity
• Rejected: Over-engineering for document-based components

Consequences

Positive

• Repeatable — Same process for every migration, regardless of component type
• Auditable — Full trail: session log, commit hashes, registry diffs, manifest
• Discoverable — Stubs ensure no "broken links" in framework
• Compliant — Meets ISO 10007, NIST 800-128, ITIL v4 requirements
• Customer-applicable — Same workflow for R&D → dev → staging → production promotions

Negative

• Stub maintenance — Stubs accumulate over time; need periodic cleanup review
• Three-repo commits — Bottom-up commit required for each migration (target → source → parent)
• Script dependency — component-migration.py becomes critical infrastructure

Risks

• Stub validation hook (H.22.2) not yet implemented — stubs could have malformed frontmatter
• No automated dependency graph check — broken cross-references possible
• Registry updates are JSON file-based, not database-backed — concurrent migrations could conflict

Implementation

Component	File	Status
Migration Engine	scripts/component-migration.py	✅ Complete
Workflow Definition	workflows/component-migration.yaml	✅ Complete
Component Lifecycle v1.1.0	commands/component-lifecycle.md	✅ Complete
Component Create v1.1.0	commands/component-create.md	✅ Complete
Analysis Document	internal/analysis/research-continuum/component-migration-standardized-workflow-2026-02-11.md	✅ Complete
Stub Validation Hook	hooks/stub-validator.py	Planned (H.22.2)
Stub Template	config/templates/relocated-stub.md	Planned (H.22.4)

Related

• ADR-164 — Universal Document Object Model (triggered the first migration)
• H.22 — TRACK-H Framework Autonomy: Component Migration Workflow
• ISO 10007:2017 — Quality Management Guidelines for Configuration Management
• NIST SP 800-128 — Guide for Security-Focused Configuration Management
• ITIL v4 — Change Enablement Practice

---

Author: Claude (Opus 4.6) Reviewed: 2026-02-11 Task: H.22 Project: PILOT