v0.46.2 — SLICE-0: §22.4a contract amendment (entry metadata is collection-configured, not type-driven)

Reframes binding SPEC.md §22.4a so a collection's entry metadata schema is
collection-configured — a `fields:` schema in `.collection.yaml` plus per-entry
`<slug>.meta.yaml` sidecars — rather than a frontmatter schema hard-wired to the
collection's `type`. Item 3's type-specific surfaces (release planning;
bdd scenario/coverage views) are deferred to a future design; bdd coverage is
recorded as a future `ref`-field surface rendered as hyperlinks (no cross-
collection corpus fusion). `type` still selects terminology (entry noun,
v0.45.0) + default initial_state/review posture (§22.4b-c).

SLICE-0 of docs/design/2026-06-06-configurable-collection-metadata.md (§7.2);
supersedes the per-type-surfaces draft (D11). Doc-only: per-type frontmatter
validation was never implemented, so no operator action, no schema/behavior
change. Sidecar storage + validation + UI arrive in SLICE-1+.

- SPEC.md §22.4a reframed; document/specification/bdd bullets updated; metadata
  amendment blockquote added.
- SPEC.md §2 and §22 forward-pointer blockquotes: "type-dependent frontmatter
  schema" -> "collection-configured, not type-driven (§22.4a, as amended)".
- CHANGELOG 0.46.2; VERSION + frontend/package.json -> 0.46.2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ben Stull
2026-06-07 07:32:27 -07:00
parent 36cb6187eb
commit 5cb5f4a4a2
4 changed files with 103 additions and 32 deletions
+62 -30
View File
@@ -121,9 +121,11 @@ live in the meta repo — they live in the app database (see §5).
> **Three-tier amendment (v0.45.0 — see §22).** Slugs are unique **per
> collection** (§22.4): `model/intro` and `specs/intro` coexist. The entry
> frontmatter schema is **type-dependent** on the collection's `type`
> (§22.4a) — `document` keeps the fields below; `specification` and `bdd`
> add their type metadata. The §2.3 `RFC-NNNN` `max+1` allocation is
> **metadata schema is collection-configured** (§22.4a, as amended by
> v0.46.2) — each collection declares a `fields:` schema in its
> `.collection.yaml` and stores per-entry values in a `<slug>.meta.yaml`
> sidecar; the fields below are the `document` baseline, **not**
> type-driven. The §2.3 `RFC-NNNN` `max+1` allocation is
> **removed** (the slug is the identity); pre-change `id` values survive as
> frozen legacy labels. New `active`-entry frontmatter: `unreviewed` (bool)
> and the `reviewed_at` / `reviewed_by` provenance pair (§22.4c).
@@ -5125,39 +5127,67 @@ never used for routing or lookup. New entries are never assigned one.
### 22.4a Collection type
> **Metadata amendment (v0.46.2 — Configurable Collection Metadata).** Item 1
> below originally made the **entry metadata schema type-driven** — a
> `document`/`specification`/`bdd` frontmatter schema baked into a per-type
> module. That is **superseded**: entry metadata is **collection-configured**,
> not type-driven. Each collection declares a `fields:` schema in its
> `.collection.yaml`, and per-entry values live in a `<slug>.meta.yaml`
> **sidecar** (the `.md` body stays pure prose; a parser reads the sidecar
> else legacy top-of-doc frontmatter). See the
> [Configurable Collection Metadata](./docs/design/2026-06-06-configurable-collection-metadata.md)
> design, which supersedes the
> [per-type-surfaces](./docs/design/2026-06-06-per-type-surfaces.md) draft
> (D11). Item 3's **type-specific surfaces** (release planning for
> `specification`; scenario/coverage views for `bdd`) are **deferred** to a
> future design; the `bdd` **coverage** capability is recorded there as a
> future `ref`-field surface that maps features to the spec entries they
> verify **as hyperlinks**, honoring the §22 rule against fusing corpora
> across collections. What `type` still selects is the **terminology** (item 2,
> the entry noun, shipped v0.45.0) and the **default `initial_state` / review
> posture** (§22.4bc).
Every collection declares a `type` in its `.collection.yaml` manifest
(§22.2), chosen at creation and **immutable**: one of `document`,
`specification`, or `bdd`. Type does not change the engine — every type uses
the same content repo (§22.3), the same propose→branch→PR→discuss→graduate
lifecycle (§§913), the same threads, flags, and chat. Type selects exactly
three things:
lifecycle (§§913), the same threads, flags, and chat. Type selects:
1. the **entry frontmatter schema** the collection validates entries against (§2);
2. the **terminology** the chrome uses for an entry (the §8.1 noun, catalog labels);
3. the set of **type-specific surfaces** layered on top of the shared §7 catalog.
1. the **terminology** the chrome uses for an entry (the §8.1 noun, catalog
labels) — the entry noun, shipped v0.45.0;
2. the **default `initial_state`** a new entry lands in, and its review
posture (§22.4b, §22.4c).
Type-specific behavior is implemented as a per-type module the framework
selects on `collection.type`; the engine itself treats every entry as
markdown + frontmatter regardless of type. `type` is an **open set** in shape
— a future type is a new module plus a new allowed enum value, no schema
rebuild. The type names and their behavior are framework concepts (like role
names), not deployment content: a deployment picks which type each collection
is, but does not define or rename types.
Entry **metadata** is **not** selected by type — it is **collection-configured**
(a `.collection.yaml` `fields:` schema + per-entry `<slug>.meta.yaml`
sidecars; see the amendment above, the Configurable Collection Metadata
design, and the §2 baseline). **Type-specific surfaces** layered on the shared
§7 catalog are **deferred** to a future design.
Type-specific behavior, where it exists, is implemented as a per-type module
the framework selects on `collection.type`; the engine itself treats every
entry as markdown + a metadata sidecar regardless of type. `type` is an
**open set** in shape — a future type is a new module plus a new allowed enum
value, no schema rebuild. The type names and their behavior are framework
concepts (like role names), not deployment content: a deployment picks which
type each collection is, but does not define or rename types.
- **`document`** — long-form normative prose (OHM: a model of principles and
definitions). Frontmatter is the §2 baseline. No type-specific surfaces. The
§22.13 generated default collection is a `document` collection, so the N=1
case is unchanged.
definitions). Metadata is the §2 baseline; no collection-configured `fields:`
are required. The §22.13 generated default collection is a `document`
collection with no `fields:`, so the N=1 case is unchanged.
- **`specification`** — a versioned technical specification (this framework's
own `SPEC.md` is the archetype). Frontmatter adds spec metadata (`version`,
lifecycle `status` of draft/active/superseded, `supersedes`). Type-specific
surface — **release planning:** group entries/changes into versioned
releases with a changelog + §20-style upgrade-steps per release.
own `SPEC.md` is the archetype). A deployment that wants spec metadata
(`version`, lifecycle `status` of draft/active/superseded, `supersedes`)
declares those as collection `fields:`. **Release planning** grouping
entries into versioned releases with a changelog + §20-style upgrade-steps
is a **deferred** type surface.
- **`bdd`** — behavior-driven feature specs: each entry states a feature as
Given/When/Then scenarios with acceptance criteria. Frontmatter adds feature
metadata and an optional link to the `specification` entries a feature
verifies. Type-specific surface: a scenario/acceptance view and a coverage
view mapping features to the spec sections they exercise.
Given/When/Then scenarios with acceptance criteria. Feature metadata is
declared as collection `fields:`. The **scenario/acceptance view** and a
**coverage view** (mapping features to the spec entries they verify via a
future `ref` field, rendered as hyperlinks — never fusing corpora across
collections) are **deferred** type surfaces.
### 22.4b Initial state of a new entry
@@ -5400,10 +5430,12 @@ The single-corpus sections defer to §22; the load-bearing reinterpretations:
a project's repo (§22.3). The bot and app-owned-authorization paragraphs are
unchanged and now read org-wide.
- **§2 Schema / §2.3 IDs.** Slugs are unique **per collection**; the entry
frontmatter schema is **type-dependent** (§22.4a). The `RFC-NNNN` `max+1`
allocation is **removed** — the slug is the identity (§22.4). New
`active`-entry fields: `unreviewed` (bool) and the `reviewed_at`/
`reviewed_by` provenance pair (§22.4c).
**metadata schema is collection-configured**, not type-driven (§22.4a, as
amended by v0.46.2) — a `.collection.yaml` `fields:` schema + per-entry
`<slug>.meta.yaml` sidecars. The `RFC-NNNN` `max+1` allocation is
**removed** — the slug is the identity (§22.4). New `active`-entry fields:
`unreviewed` (bool) and the `reviewed_at`/`reviewed_by` provenance pair
(§22.4c).
- **§2.4 State machine.** The `(no entry) ─[idea-PR merged]→` transition
targets the collection's `initial_state` (§22.4b); a new `active
─[mark-reviewed, Owner]→ active` self-transition clears the `unreviewed`