T-VDHJ-document-schema-version-bump-rule

Status: open/ready · Impact: medium · Complexity: small

AUTO-DEFINED: this spec was best-effort machine-authored by /sdlc:task-auto-define on 2026-08-03 because the task is autonomy: autonomous/pr. Review the Goal, Approach, Today, Files-to-touch, and Acceptance-criteria carefully before trusting it.

Goal

The entity schema docs do not state whether adding an optional, absent-defaulted field to an entity schema requires a schema_version bump, so a field author has to reconstruct the rule from git history. Originating from T-JOXA-task-kind-field-and-leaf-dispatch on git@github.com:sksizer/dev.git:

Whether adding an optional, absent-defaulted entity field requires a schema_version bump is undocumented, and the existing precedent is split — prs and priority bumped the task schema, autonomy did not — so the question had to be settled by reading git history mid-task. The entity schema docs should state the bump rule for optional, absent-defaulted fields outright, so a field author can decide without archaeology.

Today

Location	Role today
`apps/sdlc/conventions/schema-bump-checklist.md`	The cross-entity bump convention. Opens at “every task that results in an entity’s `schema_version` being bumped” and answers the five migration-behaviour questions — it never says which schema changes require a bump in the first place.
`apps/sdlc/lib/model/entities/_common.ts#schema_version`	The field’s own `describe()` text. Explains the value semantics (numeric string, `0` sentinel, optional in frontmatter) but not when an author must change it.
`apps/sdlc/lib/model/entities/task/migrations/_stamp_only.ts`	The stamp-only migration factory. Its doc-comment is the only written trace of the precedent: `v3-to-v4` (adds `prs:`) and `v4-to-v5` (adds `priority:`) “only ADD an optional field … so every existing instance is already valid under it and migrating is just restamping”.
`apps/sdlc/lib/model/entities/task/schema.ts#autonomy`	The counter-precedent: an optional, absent-defaulted enum field that landed with no bump — `SCHEMA_VERSION` is still `"5"` and no `v5-to-v6` transform exists.
`apps/sdlc/lib/model/ops/audit.ts`	Reports `schema_version <file> is older than current <n>` as drift for each instance below the current version, so a bump costs a restamp pass over the instances on disk.
`apps/sdlc/skills/task-new/SKILL.md`	Points authors at the checklist with a one-line bullet, inheriting the same silence about when a bump is needed.

Proposed

apps/sdlc/conventions/schema-bump-checklist.md opens with a short “Does this change need a bump?” section that answers the question outright: adding a field that is optional and absent-defaulted does NOT require a schema_version bump, because every instance already on disk stays valid under the new schema and a bump only buys a restamp pass plus audit drift until it runs. The same section enumerates the changes that DO require a bump, and names the split precedent (prs, priority, autonomy) so a reader who finds the history is not left guessing which case theirs is. The schema_version describe() text and the stamp-only factory’s doc-comment point at that section, so an author who starts from the schema or from the migration code reaches the same rule.

Approach

Add a ## Does this change need a bump? section at the top of apps/sdlc/conventions/schema-bump-checklist.md, before ## The five questions. State the rule in one sentence: a schema change needs a schema_version bump when an instance that is valid today could become invalid or need rewriting under the new schema; adding an optional field whose absence is a legal value is not such a change.
In that section, enumerate the bump-requiring changes as a list: a new required field; a narrowed or retyped existing field (enum value removed, type changed); a renamed, moved, or removed field; a body-shape change the verifier enforces (the v2-to-v3 touchpoint-table reshape is the worked example).
In the same section, record the precedent explicitly: prs (v3→v4) and priority (v4→v5) were optional-field additions that took a stamp-only bump; autonomy was an optional-field addition that took none. State that the rule above is what applies going forward and that the two stamp-only bumps stand as history rather than as a pattern to copy.
Note the cost that motivates the rule, citing apps/sdlc/lib/model/ops/audit.ts: after a bump, each instance below the new version is reported as schema_version drift until /sdlc:entities-migrate restamps it.
Extend the schema_version describe() string in apps/sdlc/lib/model/entities/_common.ts with a sentence pointing at apps/sdlc/conventions/schema-bump-checklist.md for when to change the value.
Add one line to the _stamp_only.ts module doc-comment pointing at the same section, so a reader who lands on the factory sees that a stamp-only bump is no longer the expected response to an optional-field addition.
Update the checklist bullet in apps/sdlc/skills/task-new/SKILL.md so its trailing summary says the checklist also answers whether a bump is needed at all.
Run bun test, bunx tsc --noEmit, and apps/sdlc/cli/sdlc entities audit to confirm the prose-only change plus the one-string edit leave the suites and the corpus audit green.

Files to touch

Location	Kind	Change
`apps/sdlc/conventions/schema-bump-checklist.md`	modify	Add the `## Does this change need a bump?` section: the rule, the bump-requiring list, the `prs`/`priority`/`autonomy` precedent, and the audit-drift cost.
`apps/sdlc/lib/model/entities/_common.ts`	modify	Extend the `schema_version` `describe()` text with a pointer to the convention doc.
`apps/sdlc/lib/model/entities/task/migrations/_stamp_only.ts`	modify	Add one doc-comment line pointing at the new section and marking the two stamp-only bumps as history.
`apps/sdlc/skills/task-new/SKILL.md`	modify	Reword the schema-bump-checklist bullet’s summary to cover the when-to-bump question.

Acceptance criteria

AC-1: apps/sdlc/conventions/schema-bump-checklist.md contains a section that states, in one sentence, whether adding an optional, absent-defaulted field requires a schema_version bump.
AC-2: That section names prs, priority, and autonomy and says which of them the stated rule would have applied to.
AC-3: That section carries a list of the changes that DO require a bump, including at minimum a new required field, a narrowed or retyped field, and a renamed or removed field.
AC-4: The schema_version describe() string in apps/sdlc/lib/model/entities/_common.ts cites apps/sdlc/conventions/schema-bump-checklist.md by path.
AC-5: The doc-comment in apps/sdlc/lib/model/entities/task/migrations/_stamp_only.ts cites the same section.
AC-6: bun test, bunx tsc --noEmit, and apps/sdlc/cli/sdlc entities audit exit zero on the branch.

Out of scope

Changing SCHEMA_VERSION for any entity, or adding a migration transform — this task documents the rule and does not exercise it.
Retro-migrating instances that carry an older schema_version.
Machine-enforcing the rule (a gate that fails a PR adding a required field without a bump); the rule lands as prose first.

Dependencies

none

Discovery context

Spawned by /sdlc:spawn-task-pr on 2026-08-03 UTC from T-JOXA-task-kind-field-and-leaf-dispatch in git@github.com:sksizer/dev.git.

← Back to Tasks