Skip to content

feat(decision-records): flatten accepted/ into one directory - #12

Merged
trungfinity merged 1 commit into
mainfrom
feat/decision-records-flat-layout
Sep 7, 2026
Merged

trungfinity merged 1 commit into
mainfrom
feat/decision-records-flat-layout

Conversation

@trungfinity

Copy link
Copy Markdown
Contributor

What

S1 of the decision-records convention refresh: accepted/<type>/ collapses to a flat accepted/ — the type subdirectory was a layer of hierarchy the convention never needed, since identity is the global counter, type already lives in front-matter, and the INDEX groups by it. All three lifecycle dirs are now flat.

How it lands

  • promote writes to accepted/NNNN-title.md; drafts/ and accepted/ being siblings means same-depth relative links survive promotion unchanged, and a path into the old drafts/ dir is still re-expressed.
  • The new-type heads-up now reads the set of types the accepted records carry (front-matter) instead of listing directories.
  • check refuses a nested record with the fix by name: the new one-shot migrate-layout command. It refuses duplicate filenames before moving anything, re-paths each moved record's hand-authored relative links one level up, retargets links elsewhere in docs whose target record moved (the class neither --relink nor spelled-out-path rewriting reaches), repoints spelled-out paths, and finishes with build --relink.
  • Filenames — the identity — survive the move, so the origin/main collision warning stays correctly silent across a migration, even while origin/main is still nested mid-migration.

Consumers

No flag-day: consumers pin by hash in skills-lock.json and migrate when they bump. lanh-ai (55 records in 4 type dirs) is the only real migration; axie-principles has zero accepted records. Follow-up PRs handle each.

Verification

  • 105 tests pass, including 5 new migrate-layout tests (flatten + relink + retarget, check guidance, no-op idempotency, refuse-before-move on duplicates).
  • Smoke-tested migrate-layout against a copy of lanh-ai's real docs tree: all 55 records flattened, 70 files relinked, zero residual link breakage (the only check complaints in the sandbox were files outside the copied tree).
  • validate_skills.py and pre-commit run --all-files clean.

The accepted/<type>/ subdirectories were a layer the convention never
needed: identity is the global counter, `type` already lives in
front-matter, and the INDEX groups by it. Records now land in a flat
accepted/, matching archived/ and drafts/, and the new-type heads-up
reads the types accepted records carry instead of listing directories.

Since drafts/ and accepted/ are siblings now, promotion keeps
same-depth links as they are and still re-expresses paths into the old
directory (a link to a fellow draft reaches back into drafts/).

`check` refuses a nested record by naming the fix: the new one-shot
`migrate-layout`. It refuses duplicate filenames before moving
anything, re-paths each moved record's hand-authored links one level
up, retargets links elsewhere whose target record moved, repoints
spelled-out paths, and ends with `build --relink` so ID references
self-heal. Filenames survive the move, so the origin/main collision
warning stays silent across a migration; verified against a copy of
lanh-ai's 55-record corpus with zero residual breakage.
@trungfinity
trungfinity merged commit e219705 into main Sep 7, 2026
10 checks passed
@trungfinity
trungfinity deleted the feat/decision-records-flat-layout branch September 7, 2026 16:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant