validate-milestone.ts writes disk before DB — crash inconsistency

[igouss]

Summary

validate-milestone.ts writes assessment files to disk (line ~80) before writing to the DB (transaction at line ~104). Every other handler in the engine writes DB first, then disk. This inverts the recovery guarantee.

Impact

If the process crashes between the disk write and the DB transaction:

• Assessment file exists on disk
• DB has no record of it
• The system believes the assessment never happened
• Stale assessment file sits on disk, potentially picked up by a projection renderer expecting DB-backed content

Context

All other handlers follow the pattern: DB transaction → disk render → (if disk fails, compensate DB). This handler does: disk render → DB transaction → (if DB fails, orphaned file on disk).

Fix

Invert the order to match every other handler: write DB first, then render to disk. If disk render fails, compensate the DB write.

Files

• src/resources/extensions/gsd/tools/validate-milestone.ts — lines ~80 (disk write), ~104 (DB transaction)

Confidence

82%

[igouss]

Investigation Results — CONFIRMED

Operation order in validate-milestone.ts

1. Lines 79-99: Disk write FIRST

   • Renders validation markdown
   • Line 93: await saveFile(validationPath, validationMd) — writes to .gsd/milestones/{id}-VALIDATION.md
   • On failure: catches, returns { error }, exits

2. Lines 101-116: DB write SECOND

   • Line 104: transaction(() => {
   • Lines 107-115: INSERT OR REPLACE INTO assessments via raw _getAdapter() SQL
   • On failure: no compensation for the disk file already written

Comparison with correct pattern

Handler	Order	Compensation
complete-task.ts	DB first (155-208), disk second (235)	Disk fail → rollback DB (254)
complete-slice.ts	DB first (223-257), disk second	Disk fail → rollback DB
validate-milestone.ts	Disk first (93), DB second (104)	DB fail → nothing

Crash scenario

1. saveFile() succeeds at line 93 — validation markdown on disk
2. Process crashes before transaction at line 104
3. On restart: stale .gsd/milestones/{id}-VALIDATION.md exists, assessments table has no row
4. System behavior depends on which is checked first — file presence or DB query
5. If projections check the file, they see a validation that the DB doesn't know about

No intentional-order comment found

Searched the file for any comment explaining why disk-first was chosen. None found. This appears to be an oversight, not a design decision.

Fix

Invert to match all other handlers: DB transaction first, disk write second. Add compensation (delete the assessment row) if disk write fails.