# Draft spec — §22.4a per-type surfaces (the last S6 item) > # ⛔ SUPERSEDED (2026-06-06) > > This draft is **superseded by** > [`2026-06-06-configurable-collection-metadata.md`](./2026-06-06-configurable-collection-metadata.md), > which reframes §22.4a item 1 as **collection-configured** metadata in > **sidecars** (not type-driven frontmatter) and defers item 3's surfaces. > Harvested into the successor: the validation seam (A.1), the malformed-metadata > catalog flag (A.5), unknown-fields-ride-along (C.1), the engine-unchanged rule > (§0), and the N=1 `document` backcompat anchor (A.2). The **bdd coverage** > capability (`feature`/`verifies` → coverage view, Part B.2) is preserved there > as a *future* per-type surface over a generic `ref` field. The binding > `SPEC.md` §22.4a contract is to be amended by the successor's SLICE-0. Kept for > historical rationale; do not build from this document. > **Status:** discovery/spec pass — *not yet sliced into a shipped release.* > Author session: 0083 (2026-06-06). This document is the spec pass the §22 S6 > remainder called for: it specifies **§22.4a item 1** (the per-type entry > **frontmatter schema**) and **§22.4a item 3** (the per-type **surfaces**) for > the `specification` and `bdd` collection types, with BDD-style acceptance > scenarios and a delivery slicing, so a later coding session can build them > against a written contract rather than improvising. > > It is the sibling of > [`2026-06-05-three-tier-projects-collections.md`](./2026-06-05-three-tier-projects-collections.md) > (the three-tier model, S1–S6 core, shipped through v0.46.0) and refines, in > implementable detail, what `SPEC.md` §22.4a states at the contract level. > §22.4a **item 2** (the type-driven entry noun / terminology) shipped in the S6 > core (v0.45.0) and is out of scope here. ## 0. Why this is its own pass `SPEC.md` §22.4a says a collection's immutable `type` selects exactly three things: (1) the entry **frontmatter schema**, (2) the **terminology**, and (3) the **type-specific surfaces**. The S6 core shipped (2) and merged the contract into `SPEC.md`; it also shipped the type *plumbing* — `collections.type` is immutable, validated (`registry.VALID_TYPES = {document, specification, bdd}`), and drives the entry noun. What it did **not** ship is any *behavior* keyed on type beyond the noun: every type today parses the same §2 baseline frontmatter (`backend/app/entry.py` is type-agnostic and lenient about unknown keys) and renders the same §7 catalog with no type-specific surface. Items 1 and 3 were deliberately deferred at v0.45.0 (CHANGELOG: "they want a discovery/spec pass first, lacking BDD scenarios in Part C"). The three-tier design doc's Part C scenarios are all about **roles** (C.1–C.3); there are no scenarios describing what a `specification` release-planning view *does* or what a `bdd` coverage view *shows*. This document supplies them. The governing constraint from §22.4a, which every proposal below honors: > Type does not change the **engine** — every type uses the same content repo > (§22.3), the same propose→branch→PR→discuss→graduate lifecycle (§§9–13), the > same threads, flags, and chat. … the engine itself treats every entry as > markdown + frontmatter regardless of type. So a per-type surface is **additive and read-mostly**: it reads the (now type-aware) frontmatter and presents a derived view. It never forks the write path, the PR lifecycle, or the storage model. --- # Part A — Item 1: the per-type frontmatter schema ## A.1 Where validation lives today, and where it should land `entry.py:parse()` reads a fixed set of §2 baseline fields and is **lenient**: unknown keys are ignored, future fields ride along untouched (its own docstring says so). That leniency is the seam. The per-type schema is layered as a **validator**, not a parser rewrite: - `entry.py` keeps parsing the union of all known fields into the `Entry` dataclass (add the new optional fields below; absent → `None`/default, exactly as `models`/`funder`/`unreviewed` already do). The parser stays type-agnostic. - A new **`entry_schema.py`** module exposes `validate(entry, collection_type) -> list[str]` returning human-readable problems (empty = valid). It is the one place that knows which fields a type **requires**, which it **forbids**, and the **enum/shape** of each. - Validation is **advisory at parse, enforced at the write boundary.** The propose/edit/PR-merge paths (§9.1, §22.4b) call `entry_schema.validate` and surface problems the way the propose modal already surfaces field errors. A malformed historical file still *parses* (we never hard-fail a read — a deployment's existing corpus must keep loading), but the catalog flags it (§A.4) and the next write must fix it. This mirrors how visibility/initial_state are validated centrally in `registry.py` rather than at each call site. ## A.2 `document` — unchanged (the §2 baseline) `document` is the baseline: the §2 fields exactly as today (`slug, title, state, id, repo, proposed_by, proposed_at, owners, arbiters, tags`, plus the §6.6/§6.7 `models`/`funder` and §22.4c `unreviewed`/`reviewed_*`). No new fields, no type-specific surface. The §22.13 generated default collection is `document`, so **N=1 deployments see zero change** — the load-bearing backcompat guarantee. ## A.3 `specification` — versioned-spec metadata A `specification` entry is a versioned technical spec (the archetype is this framework's own `SPEC.md`). Frontmatter **adds** (all optional at parse, required/validated per A.1 at write): | Field | Shape | Meaning | Required when | |---|---|---|---| | `spec_version` | semver string (`MAJOR.MINOR.PATCH`) | the entry's own version | `state = active` | | `lifecycle` | enum `draft \| active \| superseded` | spec lifecycle, **orthogonal to** the §2.4 entry `state` | always (defaults `draft`) | | `supersedes` | list of slugs (in this collection) | specs this one replaces | optional | Notes / decisions: - **`lifecycle` ≠ `state`.** The §2.4 `state` (super-draft/active/withdrawn) is the *engine's* workflow position; `lifecycle` is the *spec's* editorial status. An `active` (graduated) entry can be `lifecycle: draft` (published but not yet ratified) or `superseded`. Keeping them orthogonal avoids overloading the shared state machine (the §22.4a "engine unchanged" rule). - **`supersedes` is validated as in-collection slugs** (§22.14 §2: slugs are unique *per collection*). A `superseded` lifecycle with no inbound `supersedes` from a newer entry is a soft warning in the surface, not a write error (the replacement may land later). - `spec_version` uses the same semver vocabulary as the framework `VERSION`/§20 so the release surface (A.5 / Part B) can sort and group. ## A.4 `bdd` — feature/scenario metadata A `bdd` entry states a feature as Given/When/Then scenarios. Frontmatter **adds**: | Field | Shape | Meaning | Required when | |---|---|---|---| | `feature` | string | the feature's one-line statement (the "In order to / As a / I want" intent) | `state = active` | | `verifies` | list of refs | the `specification` entries/sections this feature exercises | optional | | `scenarios` | derived, **not** frontmatter | count/list parsed from the body's `Scenario:` blocks | n/a | Notes / decisions: - **`verifies` is a cross-collection ref.** A ref is `"/"` or `"/#"`. The default `` is a sibling `specification` collection in the same project; an unqualified `` means "a spec slug in this project's specification collection" (resolved at render). This is the one place a `bdd` surface reaches across collections — and §22's "no app surface joins across collections" rule (`SPEC.md` line 5016) is **honored**: `verifies` is a *declared link rendered as a hyperlink*, not a query that fuses two corpora. The coverage view (B.2) aggregates these links but each entry still lives in exactly one collection. - **Scenarios are parsed from the body, not frontmatter.** Gherkin-style `Scenario:` / `Given`/`When`/`Then` lines in the markdown body are the source of truth; the surface counts and lists them. This keeps the authoring experience plain-markdown (the engine's invariant) — no structured scenario-editor write path. - `bdd` collections default `initial_state: active` (§22.4b) so a feature lands active-but-`unreviewed`; the schema validator therefore requires `feature` for active entries, which is every freshly-landed `bdd` entry. ## A.5 Schema surfacing in the existing chrome Item-1 work is mostly invisible plumbing, but two small surfaces make it real without waiting for Part B: 1. **Propose/edit validation** — the propose modal and edit-branch flow run `entry_schema.validate` for the collection's type and block submit on errors (e.g. proposing into a `specification` collection without a `lifecycle`). 2. **A "malformed frontmatter" catalog flag** — the §7 catalog marks entries whose stored frontmatter fails its type's schema (parallel to the §22.4c `unreviewed` filter), so a corpus migrated from `document`→… or hand-edited is visibly fixable. --- # Part B — Item 3: the type-specific surfaces A surface is an **additional view** layered on the shared §7 catalog + §8 entry view, selected on `collection.type`. It is read-derived from frontmatter + body; it adds no write path the engine doesn't already have. ## B.1 `specification` → the release-planning surface §22.4a: "group entries/changes into versioned releases with a changelog + §20-style upgrade-steps per release." Concretely, a per-collection **Releases** view at `/p//c//releases`: - **A release** is a named, ordered version (e.g. `0.46.0`) with: the set of spec entries at a given `spec_version`/`lifecycle`, a changelog body, and an optional upgrade-steps block (the §20.4 RFC-2119 convention reused verbatim). - **Source of truth = the content repo**, per §22.2/§22.3. A release is a file in the collection's subfolder (proposal: `releases/.md`, frontmatter `version` + `released_at` + `entries: [slug@spec_version, …]`, body = changelog + upgrade-steps). The registry mirror caches a `releases` table the way it caches `collections` — git is truth, the table is a cache (§22.2 "never written except by the mirror"). - **The view** lists releases newest-first; each expands to its changelog + upgrade-steps and the entries it cut. An Owner (scope-role, §22.6) can cut a new release (a bot-committed file, exactly like create-collection commits a manifest — §22 S5 pattern); contributors read. - **Reuse, don't reinvent:** the changelog + upgrade-steps renderer is the same markdown the framework's own `CHANGELOG.md`/§20.4 uses; the "cut a release" write is the §22 S5 bot-commit-then-mirror pattern. Deliberately **out of this surface** (deferred): cross-release diffing, automated version bumping, dependency graphs between specs. The MVP is "see the releases, their changelog, their upgrade-steps, and what each contained." ## B.2 `bdd` → the scenario/acceptance + coverage surfaces §22.4a: "a scenario/acceptance view and a coverage view mapping features to the spec sections they exercise." Two read-derived views: 1. **Scenario/acceptance view** (per entry, on the §8 entry page): renders the body's parsed `Scenario:` blocks as a structured checklist — each scenario's Given/When/Then, plus the entry's `feature` line as the header. No new storage; pure body parse. This is the `bdd` analogue of the `document` entry's prose view. 2. **Coverage view** (per collection, at `/p//c//coverage`): a matrix of **features → the spec entries/sections they `verifies`**. Rows are this collection's `bdd` entries; columns (or grouped rows) are the referenced `specification` entries. Cells show "covered / declared-but-spec-missing / spec-section-with-no-feature". The view aggregates the `verifies` links (A.4) across the collection but renders each as a hyperlink into the spec collection — it does not fuse the corpora (the §22 cross-collection rule, B/A.4). Deliberately **out of this surface** (deferred): executing scenarios, CI/test result ingestion, auto-detecting coverage from code. The MVP maps *declared* coverage (`verifies`), surfacing gaps for humans to close. ## B.3 How a surface is selected and routed - The collection payload already carries `type` and `entry_noun` (`GET /api/projects/:id/collections/:cid`). The frontend's `ProjectLayout` / collection chrome reads `type` and mounts the type's surface routes (`releases` for `specification`; `coverage` for `bdd`) alongside the shared catalog. `document` mounts none. - Backend: a per-type router group (`api_releases.py`, `api_coverage.py`) guarded by the same §22.5 read gates as the rest of the collection; the release-cut write reuses `auth.is_collection_superuser` / the S5 bot pattern. - The "per-type module the framework selects on `collection.type`" (§22.4a) is realized as: backend `entry_schema.py` (item 1) + the two router groups (item 3), and frontend a `typeModules[type]` map of `{ schema, surfaces }`. Adding a future type = a new map entry + enum value, no rebuild (§22.4a "open set"). --- # Part C — Behavioral scenarios (BDD) > Tagged for the proposed slices in Part D (`@S7a` = item 1 schemas; `@S7b` = > specification releases; `@S7c` = bdd surfaces). These are the acceptance gate > the implementing session writes tests against, in the Part C style of the > three-tier doc. ## C.1 Per-type frontmatter schema (`@S7a`) ```gherkin Scenario: document collection is unchanged Given a "document" collection When a contributor proposes an entry with the §2 baseline frontmatter only Then the proposal is accepted with no schema error Scenario: specification entry requires a lifecycle Given a "specification" collection When a contributor proposes an entry with no `lifecycle` Then it defaults to lifecycle "draft" and is accepted And when an Owner graduates it to active without a `spec_version` Then the write is blocked with "spec_version is required for an active specification" Scenario: bdd entry requires a feature statement once active Given a "bdd" collection whose initial_state is "active" When a contributor proposes an entry with no `feature` Then the write is blocked with "feature is required for a bdd entry" Scenario: unknown future field still rides along Given any collection When an entry carries a frontmatter key no schema names Then it parses unchanged and is not reported as malformed Scenario: malformed existing entry loads but is flagged Given a stored specification entry missing a required field When the catalog renders Then the entry still loads (read never hard-fails) And the catalog marks it "malformed frontmatter" ``` ## C.2 specification release-planning surface (`@S7b`) ```gherkin Scenario: an Owner cuts a release Given a "specification" collection with two active entries When the collection Owner cuts release "1.0.0" with a changelog and upgrade-steps Then a releases/1.0.0.md file is committed to the content repo And the registry mirror caches the release And the Releases view lists "1.0.0" newest-first with its changelog + upgrade-steps Scenario: a contributor reads releases but cannot cut one Given a contributor (not Owner) in the collection Then the Releases view is read-only (no "Cut release" control) Scenario: upgrade-steps render with the §20.4 convention Given a release whose body uses MUST/SHOULD/MAY upgrade-steps Then they render with the same normative-language styling as CHANGELOG.md ``` ## C.3 bdd scenario + coverage surfaces (`@S7c`) ```gherkin Scenario: an entry's scenarios render as an acceptance checklist Given a "bdd" entry whose body has two Scenario: blocks When the entry page renders Then it shows the `feature` header and both scenarios' Given/When/Then Scenario: coverage maps features to the specs they verify Given a "bdd" entry that `verifies: ["spec/auth#sessions"]` And a sibling "specification" collection "spec" containing entry "auth" When the coverage view renders Then a row links the feature to spec/auth#sessions as covered Scenario: a declared ref to a missing spec is surfaced as a gap Given a "bdd" entry that `verifies: ["spec/ghost"]` where no such spec exists Then the coverage view marks that ref "declared but spec missing" Scenario: coverage does not fuse corpora Then each cell is a hyperlink into the spec collection And no entry from the spec collection is listed as if it belonged to the bdd collection ``` --- # Part D — Delivery slicing Each slice lands a usable increment + a runnable acceptance gate (`--tags @S7x`), in the three-tier doc's slicing style. Suggested order (item 1 first — the surfaces read its fields): - **S7a — per-type frontmatter schema (item 1).** `entry_schema.py` + the new optional `Entry` fields + write-boundary validation + the catalog "malformed" flag. **Usable:** proposing into a typed collection is validated; N=1 `document` unchanged. **Completes:** `@S7a` (C.1). *Non-breaking, additive.* - **S7b — specification release planning (item 3a).** `releases/.md` storage + registry mirror + `api_releases.py` + the Releases view + cut-release write. **Usable:** a spec collection has versioned releases with changelog + upgrade-steps. **Completes:** `@S7b` (C.2). - **S7c — bdd scenario + coverage surfaces (item 3b).** Body scenario parser + the per-entry acceptance view + the per-collection coverage view + `api_coverage.py`. **Usable:** a bdd collection shows scenarios and declared coverage. **Completes:** `@S7c` (C.3). All three are **additive** (new optional frontmatter, new tables that are pure caches, new read views): each is a minor, non-breaking release, and a `document` N=1 deployment is unaffected by any of them. None touches the engine, the PR lifecycle, or the role model — they consume the §22 three-tier + §22.6 role work already shipped. ## D.1 Open questions for the implementing session 1. **Release identity vs. entry `spec_version`.** Should a release's `entries` pin exact `slug@spec_version` (immutable snapshot) or just slugs (live)? This doc proposes the pinned snapshot; confirm against a real spec-collection workflow before building S7b. 2. **`verifies` ref grammar.** `"/#"` is proposed; anchor resolution into a spec entry's section needs the spec body to carry stable anchors. May want a lightweight `## §n` anchor convention on `specification` entries first. 3. **Whether `lifecycle` belongs in the shared state machine after all.** Kept orthogonal here; revisit if product wants `superseded` to gate the catalog. These are genuine product decisions a discovery/spec session (or the operator) should settle before S7b/S7c code; S7a (schemas) is unblocked and buildable now.