Skip to content

Alphabetize the default schema's field lists and add diataxis to assertion #759

Description

@williamthorsen

Problem

The @codeassembly/kb default schema (packages/kb/src/schema/default-schema.ts) declares its record-type field-name lists in arbitrary insertion order. That ordering is hard to scan, makes it non-obvious where a field belongs, and makes a missing field hard to spot. All four lists are affected: assertion.required, assertion.optional, event.required, and event.optional.

Separately, assertion.optional omits diataxis, even though the kb-add and kb-retrieve skills already read and write a diataxis facet and the personal coding vault's .kb/schema.yaml declares it. The default schema should both order its fields predictably and document diataxis as a recognized optional assertion field.

Context

  • The field-name arrays are descriptive metadata. frontmatterRule validates a record type's required set, date formats, the recordType discriminant, and tags shape; it never reads optional, and unknown fields are silently accepted, so diataxis is already accepted on notes today. Adding diataxis to optional therefore changes documentation and the generated seed, not validation.
  • The one observable runtime effect is finding order: frontmatterRule emits frontmatter.required findings in required-array order, so alphabetizing the required arrays makes kb check report a note's missing required fields alphabetically. The parity golden is recaptured to match.
  • Note serialization order is hardcoded in write-frontmatter.ts (title, recordType, created, updated, tags, then extras), independent of the schema arrays, and stays as-is.
  • Each list is mirrored in four places: the constant, default-schema.test.ts, and the README's TypeScript and YAML example blocks. The seed .kb/schema.yaml that kb create renders derives from the constant via renderSchemaSeed, and render-seeds.test.ts is an identity round-trip (expect(schema).toEqual(defaultSchema)), so it needs no change.
  • The README's two example blocks also order the record types and their keys inconsistently: the TypeScript block lists assertion first with keys required, optional, recall, immutable; the YAML block leads with event, uses a different key order, and omits immutable for assertion. Since this change already edits both blocks, it normalizes record-type and key order across them.
  • Value-level validation of the Diátaxis vocabulary (howto, concept, reference, tutorial) stays out of scope: the package loader reads only recordTypes: and has no field-value validation mechanism. That vocabulary lives in the vault's own check-notes script.

Proposed solution

Sort all four field-name lists in default-schema.ts alphabetically; diataxis takes its alphabetical place in assertion.optional. Leave the record types' key order in the constant, the recall/immutable policies, and the hardcoded note write-order untouched. Propagate the identical ordering to the README's TypeScript and YAML example blocks and to the literal assertions in default-schema.test.ts, including the mutation test's first-element assertion (which currently pins title). The rendered seed and its round-trip test require no change; the parity golden is recaptured to reflect the new missing-required finding order.

Also normalize the README's two example blocks so they present the record types in the same order (assertion first, matching the constant) with the same key order (required, optional, recall, immutable — the order the constant declares and renderSchemaSeed emits), and show immutable: false on the assertion YAML example. This is deliberately not alphabetical: the README should mirror what kb create writes.

The work ships as two commits: a reorder of the existing lists (semantics-preserving except for the finding-order ripple noted above), then the diataxis addition in its sorted slot.

Acceptance criteria

Must have

  • The four field-name lists in packages/kb/src/schema/default-schema.ts are alphabetized: assertion.required = [created, tags, title, updated]; assertion.optional = [applies-to, diataxis, last-verified, sources, superseded-by, supersedes]; event.required = [captured-at, cwd, id, session, summary]; event.optional = [correction, model, repo, skill, tags].
  • packages/kb/src/schema/__tests__/default-schema.test.ts asserts the alphabetized lists (including diataxis), and its first-element mutation assertion matches the new order.
  • The parity golden (packages/kb/src/rules/__tests__/fixtures/parity/expected-findings.json) reflects the missing-required finding order produced by the alphabetized required arrays.
  • The "The default schema" section of packages/kb/README.md reflects the alphabetized lists in both the TypeScript and YAML example blocks.
  • Both README example blocks present the record types in the same order (assertion first) and use the same key order (required, optional, recall, immutable), matching the constant and the rendered seed, and the assertion YAML example shows immutable: false.
  • The .kb/schema.yaml seed that kb create renders reflects the alphabetized lists with diataxis (flows automatically from the constant; confirm, no separate code change expected).
  • kb lint and test suites pass.

Metadata

Metadata

Labels

featureAdded or improved external functionalityscope:kb

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions