Context
ADR 0004 moved resources/content/ to the Universal Ordinal-100 Content Architecture and explicitly anchors recovery on clean deletion plus sync_all regeneration. During PR #11403 follow-up review, ai/scripts/migrate-substrate-11360.mjs stood out as leftover one-shot substrate code from the pre-ADR #11360 cleanup path.
This ticket exists because the script now points in the wrong architectural direction: it preserves a migration affordance after the architecture has chosen a clean cut.
The Problem
ai/scripts/migrate-substrate-11360.mjs is a one-shot repair script introduced for #11360 / PR #11362. It remains tracked after that migration completed and after ADR 0004 established the new source-of-truth model.
Current evidence:
ai/scripts/migrate-substrate-11360.mjs:2 identifies itself as a one-shot script for Epic #11187 Phase 6 sub-issue #11360.
ai/scripts/migrate-substrate-11360.mjs:29-31 still advertises manual --dry-run / --apply execution.
ai/scripts/migrate-substrate-11360.mjs:56 defines local chunkPath() for the retired pre-ADR ID-range model.
ai/scripts/migrate-substrate-11360.mjs:171, :208, and :232-233 still generate retired resources/content/issues/<NNN>xx/ and resources/content/pulls/pr-<NNN>xx/ paths.
rg migrate-substrate-11360 found no live consumer outside the script itself.
- Git history preserves the audit trail:
559c73d43 introduced the script for #11360 / #11362, and 79ac1f8c9 only adjusted its comment while deleting retired path helpers for #11390 / #11403.
The Architectural Reality
ADR 0004 is the source of authority:
learn/agentos/decisions/0004-github-content-architecture.md:51-53 states resources/content/ and .sync-metadata.json are regeneratable; sync_all is the recovery mechanism.
learn/agentos/decisions/0004-github-content-architecture.md:68-84 defines the target shape as universal chunk-N/ directories with no <NNN>xx/, no GitHub-ID-stream math, and one primitive.
learn/agentos/decisions/0004-github-content-architecture.md:284-294 rejects deprecation or coexistence windows for retired primitives and prescribes deletion when migration lands.
Keeping the old script creates a misleading executable artifact for future agents and conflicts with the clean-cut mental model. Git history is sufficient audit trail; tracked executable substrate should reflect the current architecture.
The Fix
Delete ai/scripts/migrate-substrate-11360.mjs.
Do not replace it with a new migration script, shim, wrapper, or compatibility alias. If local resources/content/ state needs repair, the operator or agent should use the ADR 0004 recovery path: clean substrate deletion where needed, then run sync_all from dev.
Coordinate with #11406 if its retired-primitive grep enforcement lands first or in parallel, so the deleted script does not require a special allowlist.
Acceptance Criteria
Out of Scope
- Rewriting
contentPath.mjs or syncer chunk semantics.
- Mutating
resources/content/ data files.
- Running
sync_all from a feature branch.
- Deleting or rewriting historical GitHub issue, PR, or ADR content that references the old model.
- Updating unrelated release JSDoc comments unless the close-out lane explicitly owns that scope.
Related
- Parent Epic: #11372
- Predecessor cleanup ticket: #11360
- PR #11362 introduced the one-shot script for the old cleanup path.
- PR #11403 deleted the retired shared path helpers and exposed this script as the remaining live executable artifact.
- #11406 tracks CI grep-fail enforcement for retired primitive imports.
- ADR 0004:
learn/agentos/decisions/0004-github-content-architecture.md
Origin Session ID: 56d01d8b-ce3f-4194-9441-e4941ae07be8
Handoff Retrieval Hint: "ADR 0004 migrate-substrate-11360 clean cut sync_all retired chunkPath"
Context
ADR 0004 moved
resources/content/to the Universal Ordinal-100 Content Architecture and explicitly anchors recovery on clean deletion plussync_allregeneration. During PR #11403 follow-up review,ai/scripts/migrate-substrate-11360.mjsstood out as leftover one-shot substrate code from the pre-ADR #11360 cleanup path.This ticket exists because the script now points in the wrong architectural direction: it preserves a migration affordance after the architecture has chosen a clean cut.
The Problem
ai/scripts/migrate-substrate-11360.mjsis a one-shot repair script introduced for #11360 / PR #11362. It remains tracked after that migration completed and after ADR 0004 established the new source-of-truth model.Current evidence:
ai/scripts/migrate-substrate-11360.mjs:2identifies itself as a one-shot script for Epic #11187 Phase 6 sub-issue #11360.ai/scripts/migrate-substrate-11360.mjs:29-31still advertises manual--dry-run/--applyexecution.ai/scripts/migrate-substrate-11360.mjs:56defines localchunkPath()for the retired pre-ADR ID-range model.ai/scripts/migrate-substrate-11360.mjs:171,:208, and:232-233still generate retiredresources/content/issues/<NNN>xx/andresources/content/pulls/pr-<NNN>xx/paths.rg migrate-substrate-11360found no live consumer outside the script itself.559c73d43introduced the script for #11360 / #11362, and79ac1f8c9only adjusted its comment while deleting retired path helpers for #11390 / #11403.The Architectural Reality
ADR 0004 is the source of authority:
learn/agentos/decisions/0004-github-content-architecture.md:51-53statesresources/content/and.sync-metadata.jsonare regeneratable;sync_allis the recovery mechanism.learn/agentos/decisions/0004-github-content-architecture.md:68-84defines the target shape as universalchunk-N/directories with no<NNN>xx/, no GitHub-ID-stream math, and one primitive.learn/agentos/decisions/0004-github-content-architecture.md:284-294rejects deprecation or coexistence windows for retired primitives and prescribes deletion when migration lands.Keeping the old script creates a misleading executable artifact for future agents and conflicts with the clean-cut mental model. Git history is sufficient audit trail; tracked executable substrate should reflect the current architecture.
The Fix
Delete
ai/scripts/migrate-substrate-11360.mjs.Do not replace it with a new migration script, shim, wrapper, or compatibility alias. If local
resources/content/state needs repair, the operator or agent should use the ADR 0004 recovery path: clean substrate deletion where needed, then runsync_allfromdev.Coordinate with #11406 if its retired-primitive grep enforcement lands first or in parallel, so the deleted script does not require a special allowlist.
Acceptance Criteria
ai/scripts/migrate-substrate-11360.mjsis deleted.rg "migrate-substrate-11360|function chunkPath|pr-\\$\\{chunkPath|issues/\\$\\{chunkPath" ai buildScripts test package.jsonfinds no live-code reference requiring the retired ID-range model.Out of Scope
contentPath.mjsor syncer chunk semantics.resources/content/data files.sync_allfrom a feature branch.Related
learn/agentos/decisions/0004-github-content-architecture.mdOrigin Session ID: 56d01d8b-ce3f-4194-9441-e4941ae07be8
Handoff Retrieval Hint: "ADR 0004 migrate-substrate-11360 clean cut sync_all retired chunkPath"