T-S4XK-entities-validate-and-migrate-report-everything

State: planning/draft · Impact: medium · Complexity: small

Goal

On an unmigrated planning tree, validate and migrate hide what is wrong and what will change. The validate error tells users to run entities migrate, which sdlc entities --help does not list. Found while checking determined’s tree (164 files on old schemas).

Today

• entities migrate is hidden: true (migrate.ts, around L755).
• validate stops at the first refine error per file, so it hides v5–v8 schema drift and understates what migrate will change.
• migrate’s text output prints “would fix (164 file(s))” with no plan lines, then repeats every refine message under manual review. Only --json shows the plan.
• Every non-README .md in a decision dossier folder fails validation (“no YAML frontmatter block found”); D-7VMX-…/ fails 11 of 12 files. A whole-tree validate is noise.

Proposed

entities migrate is listed in help. validate reports every error per file. migrate’s text output shows one plan line per file (from → to, and what changes). Validation treats a dossier’s supporting pages as part of the decision, not as entities.

Approach

1. Drop hidden: true from the migrate op.
2. Collect all issues per file in validate instead of returning on the first refine failure.
3. Render the migration plan in text mode; list manual-review items once each.
4. Skip non-README files inside a decision dossier folder in validate (and audit, if it has the same problem).

Areas

Area	Note
solutions/ontological/lib/model/	validate, migrate, entity discovery

Acceptance criteria

• AC-1: sdlc entities --help lists migrate.
• AC-2: A file with both a schema-version gap and a refine error reports both.
• AC-3: entities migrate --dry-run text output shows a plan line per file.
• AC-4: entities validate over docs/planning/decisions/ reports no errors for dossier supporting pages.

Out of scope

• Running the determined migration (T-8S38 in determined’s corpus).

---

← Back to Tasks