baldart 4.68.0 → 4.68.2

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.68.2] - 2026-06-24
+
+**A change's OWN documentation now closes before merge — no more "post-merge, non-blocking" doc follow-ups for what the change itself touched.** Observed on a real `mayo` FEAT-0055 run that merged with two deferred doc items: a full-sync of the `/products` screen doc (the exact route it changed, beyond a stub) and a `must_rule` clarification on `PageLayout.md` (the component it modified). Both are *own-docs* — documenting what you just shipped — yet `/new` permitted deferring them (the DS Decision Matrix routed "needs judgement" to a follow-up, and Phase 6b force-marks cards DONE regardless). Leaving the doc of the thing you just changed stale at merge is the drift entry door the Post-Intervention philosophy exists to close.
+
+**PATCH** — tightens the deferral classification of an existing gate; no new config key, no new agent/skill. Deliberately NOT a blanket "all docs block merge" (that regresses the follow-up mechanism by coupling ready code to genuinely-separate design decisions) — only *own-docs* block; adjacent/cross-cutting docs still defer to a tracked follow-up.
+
+### Changed
+
+- **New SSOT § "Documentation Closure"** in `agents/workflows.md` (twin of the AC Scope Closure Discipline, STRICTER) — a change's OWN docs must be SYNCED in the same PR before merge, no follow-up escape, a stub is not synced. "Own-docs" is **deterministic** (not the agent's discretion to relabel as adjacent): (1) the spec of any modified primitive, (2) the screen/route doc for a touched route, (3) the card's declared `documentation_impact`/`canonical_docs`. Anything outside those three is adjacent and still deferrable.
+- **`design-system-protocol.md` Decision Matrix tightened** — a spec update that DOCUMENTS the behaviour THIS change introduced (a new/changed `must_rule`/prop/variant/slot/a11y hook) is **inline-BLOCKING, not deferrable**; only a genuinely SEPARATE design decision (a new variant's full semantics, breaking-change migration design, an unresolved a11y trade-off) remains the deferrable case.
+- **`doc-reviewer` Own-Documentation Closure gate** — own-doc obligations are `synced` or a **BLOCKER** (`DOC_OWN_STUB` for a stub-only own-route doc, `DS_COMPONENT_STALE` for a modified-primitive spec), emitted as `BLOCKER` (never a `LOW`/`MED` note, never a silent "deferred"). Flows through the existing pre-merge severity gate (an unresolved BLOCKER blocks the merge — `final-review.md`) and the `doc` domain-override (never inline-bypassed). Shared agent + shared `new-final-review.js` → enforced in BOTH `/new` and `new2` with no separate wiring.
+
+## [4.68.1] - 2026-06-24
+
+**`/design-system-init` now actually ACTIVATES the closed-set gate it just populated — found on the first real `mayo` upgrade run.** The v4.68.0 upgrade correctly derived + confirmed the closed-set data (the two-header `page-header` family + a `range-slider` pair landed in the component HEADs with `canonical_for`/`selection_closed: true`), but `baldart ds-gate` stayed `no-policy` and never enforced. Root cause: step 6's serializer bundle merged "deterministic (step 3) + agentic (step 4)" but NOT the step-4b/4c selection-policy fields, so `emitSelectionPolicy` ran over components without `canonical_for` and generated an EMPTY `INDEX.md § "Selection Policy"` block (the HEADs got the fields via a side path; the gate reads the INDEX block). Data present, gate dormant.
+
+**PATCH** — corrects the bootstrap write/verify flow; no schema/API change.
+
+### Fixed
+
+- **Selection-policy fields flow into the `--index` bundle** (`design-system-init/SKILL.md` step 6 + workflow step 5) — the serializer bundle MUST carry `canonical_for`/`use_when`/`selection_closed` for ALL components so `emitSelectionPolicy` generates the populated `INDEX.md § "Selection Policy"` block. Building the bundle from `extract-manifest` only / pre-4c agentic JSON leaves the block empty.
+- **New BLOCKING verification step 6b/5b** — when any closure was confirmed, the skill now asserts `INDEX.md` contains `## Selection Policy` AND `baldart ds-gate` no longer reports `no-policy` (the gate reads the COMMITTED baseline, so the INDEX block must be committed) before declaring the closed-set bootstrapped. Closes the "data in HEADs but gate dormant" gap that would otherwise ship silently.
+
 ## [4.68.0] - 2026-06-24
 
 **Closed-Set Selection Policy — the third semantic layer that makes the "third header" structurally impossible.** Found on real `mayo` PRDs: every PRD ignored the two existing canonical headers (`SectionHeader` depth-0, `DrilldownHeader` depth-1+) and wrote new ones, requiring an expensive consolidation epic (`FEAT-0045` + an ADR) and leaving `Header.tsx` deprecated-but-live in 3 call-sites. Root cause (confirmed by a BALDART trace + 40-source 2026 research): the registry has a token layer and a component layer, but **no layer asserts the *boundary* of a category** — so adding a third header violated no rule, only an undiscovered convention. The registry-first cascade was advisory at generation-time + reactive at review-time; nothing prevented the duplicate at build-time. The 2026 market confirms the gap: no vendor (Figma Code Connect, Storybook MCP, shadcn) hard-gates the reuse decision, and no deterministic tool detects a semantically-equivalent rewrite — but BALDART already ships the machine-readable manifest signature, so it is "one manifest-signature-diff away".

package/VERSION

@@ -1 +1 @@
-4.68.0
+4.68.2

package/framework/.claude/agents/doc-reviewer.md

@@ -246,7 +246,33 @@ Run this before any general audit:
 7. Write missing docs directly. Prefer extending existing reference docs over creating new files unless the feature is large enough to justify a standalone document. For type-specific checklists, read `.claude/skills/doc-reviewer-support/references/doc-checklists.md` **if it exists**; otherwise apply the doc-type rules and invariant table above and the `doc-writing-for-rag` skill's templates.
 8. Update indexes when new docs are added.
 9. Assess Obsidian/wiki sync need (section H) — **OPTIONAL, only when `features.has_wiki_overlay: true` in `baldart.config.yml`**. If the flag is absent or false, skip section H with a one-line "no wiki overlay" note. When the flag is true, read `.claude/skills/doc-reviewer-support/references/obsidian-integration.md` for trigger conditions **if it exists**; otherwise assess on first principles (new cross-cutting concept, renamed canonical, deprecated doc) and note the need without dispatching any sync agent here.
-10. Report what was checked, added, fixed, and deferred.
+10. Report what was checked, added, fixed, and deferred — but see the Own-Documentation Closure gate below: an own-doc may NOT appear in the "deferred" bucket.
+
+### Own-Documentation Closure (BLOCKING — own-docs close in this PR, no defer)
+
+Per `agents/workflows.md § Documentation Closure`, the documentation of **what
+this change itself touched** must be SYNCED in this diff before merge — it is NOT
+deferrable to a follow-up, and a STUB is not synced. Build the own-doc obligation
+list deterministically from the diff + card (do not relabel an own-doc as
+"adjacent" to defer it):
+
+1. **Modified-primitive spec** — every component whose source changed → its
+   `components/<Name>.md` reflects the shipped behaviour (the `must_rules` / props /
+   slots the change introduced). A stale/stub spec is `DS_COMPONENT_STALE`.
+2. **Touched route/screen doc** — the diff changed a route/page → the screen/route
+   doc for THAT route is synced (not just stubbed). A stub-only doc for a route you
+   changed is `DOC_OWN_STUB` (the screens/README "stub but full-sync deferred"
+   pattern — not allowed for an own-route).
+3. **Declared `documentation_impact` / `canonical_docs`** — every doc the card named
+   as in-scope is synced.
+
+Each obligation is `synced` or it is a **BLOCKER** finding (`DOC_OWN_STUB` /
+`DS_COMPONENT_STALE`) — emit it as `BLOCKER` in section F/G, never as a `LOW`/`MED`
+note and never silently in a "deferred" list. In WRITE mode you fix it yourself
+(you are fully responsible for feature docs — `## Constraints`); you do NOT defer
+an own-doc to another agent or a later card. Only **adjacent** docs (a broader
+rewrite, a genuinely separate design decision, areas the change only grazed) may be
+reported as a tracked follow-up.
 
 ## Audit Process (general documentation review)
 1. **Map**: Build tree of all docs with purpose annotations.

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -158,8 +158,17 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    Reconciliation gate: auto where confident, ask where it is the user's call.
 5. **Bootstrap the DTCG token SSOT.** See § Token SSOT bootstrap below.
 6. **Write the files — DETERMINISTICALLY (the HEAD is NEVER model-authored).**
-   Merge the deterministic JSON (step 3) with the agentic JSON (step 4) per
-   component into a bundle and run the serializer:
+   Merge the deterministic JSON (step 3) with the agentic JSON (step 4) **and the
+   selection-policy fields from steps 4b/4c** (`canonical_for` / `use_when` /
+   `selection_closed`) per component into a bundle and run the serializer. The
+   bundle MUST carry the selection-policy fields — they are what
+   `emitSelectionPolicy` reads to GENERATE the `INDEX.md § "Selection Policy"`
+   block. Omitting them (e.g. building the bundle from `extract-manifest` only, or
+   from the pre-4c agentic JSON) writes the closed-set fields to the HEADs via a
+   side path but leaves the INDEX block EMPTY, so `baldart ds-gate` stays
+   `no-policy` and the gate never activates. On UPGRADE, the `--index` bundle MUST
+   include ALL components (not only the changed ones) so the regenerated router +
+   policy block are complete. Run the serializer:
    ```
    node .framework/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs \
      --bundle <bundle.json> --out-dir ${paths.design_system}/components \
@@ -186,6 +195,18 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    - `tokens-reference.md` — **generated** human view of `.tokens.json` (or pure
      narrative). Not a third source of values.
    - `patterns/.gitkeep` — empty dir for future pattern docs.
+6b. **VERIFY the Selection Policy activated (BLOCKING when any closure was confirmed).**
+   If step 4c confirmed any `selection_closed: true`, then after the write:
+   - `grep -q '## Selection Policy' ${paths.design_system}/INDEX.md` MUST succeed —
+     the generated block lists the closed families. If it is ABSENT, the bundle
+     dropped the selection-policy fields (step 6): rebuild the `--index` bundle
+     INCLUDING `canonical_for`/`selection_closed` for ALL components and re-run.
+   - `npx baldart ds-gate --json` MUST NOT report `"reason":"no-policy"`. If it
+     still does, the committed INDEX lacks the block — the gate reads the COMMITTED
+     baseline, so the INDEX (with the policy block) must be committed for the gate
+     to enforce. Surface this in the next-steps so the user commits it.
+   Do NOT declare the closed-set bootstrapped until both pass — otherwise the data
+   is in the HEADs but the gate is dormant (the exact gap this check closes).
 7. **Update config.** Set `features.has_design_system: true`,
    `paths.design_system: <target>`, and (when tokens bootstrapped)
    `paths.design_tokens` + `design_tokens.outputs`. Use the same YAML write path
@@ -225,11 +246,19 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 4. **Token SSOT bootstrap** — § Token SSOT bootstrap (derive `.tokens.json`,
    set outputs, `baldart tokens build`, round-trip verify).
 
-5. **Write files DETERMINISTICALLY** — merge deterministic+agentic field data per
-   component and run `scripts/serialize-spec.mjs` (emits valid-YAML HEADs +
-   thin INDEX router, self-validates, fails closed). Never hand-write the HEAD.
-   Then the generated tokens-reference + `patterns/.gitkeep`. UPGRADE salvages
-   agentic values from existing (even malformed) HEADs before re-serializing.
+5. **Write files DETERMINISTICALLY** — merge deterministic+agentic+selection-policy
+   field data per component (the bundle MUST carry `canonical_for`/`use_when`/
+   `selection_closed` so the serializer GENERATES the `INDEX.md § Selection Policy`
+   block) and run `scripts/serialize-spec.mjs --index` over ALL components (emits
+   valid-YAML HEADs + thin INDEX router + policy block, self-validates, fails
+   closed). Never hand-write the HEAD. Then the generated tokens-reference +
+   `patterns/.gitkeep`. UPGRADE salvages agentic values from existing (even
+   malformed) HEADs before re-serializing.
+
+5b. **Verify the Selection Policy activated** (§ What This Skill Does step 6b) —
+   when any closure was confirmed: `INDEX.md` MUST contain `## Selection Policy`
+   AND `baldart ds-gate` MUST NOT report `no-policy` (commit the INDEX — the gate
+   reads the committed baseline). Don't declare done until both pass.
 
 6. **Persist config** — `features.has_design_system: true`, `paths.design_system`,
    and (if tokens bootstrapped) `paths.design_tokens` + `design_tokens.outputs`.

package/framework/agents/design-system-protocol.md

@@ -600,7 +600,8 @@ For each item in the diff that touched a visual surface, run these 4 checks:
 | Situation | Action |
 |---|---|
 | Spec / token update is trivial (variant added, prop renamed, token value tweaked) | Apply inline — same commit as the code change |
-| Spec / token update requires design judgement (new variant semantics, breaking change, accessibility decision) | Open a follow-up card; **document the gap explicitly** in the change description; flag for `code-reviewer` |
+| Spec update DOCUMENTS the behaviour THIS change introduced (a new/changed `must_rule`, prop, variant, slot, a11y hook the diff added) | **Apply inline — BLOCKING, not deferrable.** This is an *own-doc* (`agents/workflows.md § Documentation Closure`): documenting what you just shipped is part of the change, never a follow-up. A stub is not synced. |
+| Spec / token update requires a genuinely SEPARATE design decision (a new variant's full semantics needing its own design pass, a breaking change needing migration design, an unresolved accessibility trade-off) — beyond documenting this change | Open a follow-up card; **document the gap explicitly** in the change description; flag for `code-reviewer`. This is the ONLY deferrable case. |
 | Reused undocumented primitive that is broadly useful | Add INDEX entry inline; if a full spec needs design work, scaffold a stub spec marked `status: needs-review` |
 | Reused undocumented primitive that is surface-specific | Add INDEX entry with `scope: local` and a 2-line note explaining why no full spec is needed |
 | Introduced a primitive that **duplicates** an existing registry entry | **Stop**. This is the failure mode the cascade exists to prevent. Revert and reuse the existing primitive, or escalate to refactor the existing primitive if the new requirement is legitimately broader |

package/framework/agents/workflows.md

@@ -61,6 +61,38 @@ When a card's `acceptance_criteria` cannot be fully implemented as written, the
 
 Any deferral travels through an explicit `AskUserQuestion` with the AC text quoted verbatim, one question per AC. For orchestrator skills (`/new`, `/prd`) this discipline is enforced in the per-card AC-closure gate before commit. Auto Mode's "bias toward proceeding" applies to routine decisions, NOT to scope reduction — silent deferral of a numbered AC is a violation even in Auto Mode.
 
+### Documentation Closure (own-docs close before merge — no defer)
+
+The same discipline applies to the **documentation of what the change itself
+touched** — and is STRICTER than ACs: a change's OWN docs must be reconciled
+**in the same PR, before merge**. They may NOT be deferred to a post-merge
+follow-up, and a STUB is not "synced". Leaving the doc of the thing you just
+changed stale at merge is the drift entry door the Post-Intervention philosophy
+exists to close ("reconcile at source, not next Monday").
+
+**"Own docs" is deterministic** (derivable from the diff + card — not the agent's
+discretion to relabel as "adjacent"):
+
+1. **Modified-primitive spec** — any component whose source changed in the diff →
+   its `${paths.design_system}/components/<Name>.md` (incl. the `must_rules` /
+   behaviour the change introduced). This is `DS_COMPONENT_STALE` and is already
+   blocking; it is **not** deferrable as "needs design judgement" when it merely
+   documents what this change did (see `agents/design-system-protocol.md`
+   Decision Matrix).
+2. **Touched route/screen doc** — if the diff changes a route/page, the screen/route
+   doc for THAT route (`${paths.references_dir}/ui/…` / `docs/design/screens/…`).
+3. **Declared `documentation_impact` / `canonical_docs`** — the docs the card itself
+   named as in-scope.
+
+Each own-doc obligation is `synced` (the doc reflects the shipped change, in this
+diff) or it BLOCKS the merge. There is no `deferred` state for an own-doc and no
+follow-up-card escape — the only resolutions are *sync it now* or an explicit
+`[USER-APPROVED DEFERRAL]` recorded via `AskUserQuestion` (interactive) / surfaced
+as a blocker (autonomous). **Adjacent / cross-cutting docs** — a broader rewrite, a
+genuinely separate design decision, docs for areas the change only grazed — are
+NOT own-docs: those legitimately defer to a tracked follow-up card. The boundary is
+the three deterministic categories above; anything outside them is adjacent.
+
 ### Coder authority (no defer)
 
 Coder agents report `done | failed` at card level. Per-requirement signals (`done | not_implemented`) are inputs to the orchestrator's AC-Closure Gate, never terminal verdicts. Coders have NO authority to declare an AC `deferred`, `out of scope`, `covered by X`, `partial`, `blocked`, or any equivalent. Only the user, via the gate's `AskUserQuestion`, can approve a deferral. Inventing constraints — `time budget`, `context budget`, `context pressure as override`, or any phrase not enumerated in a phase's documented Gate table — to skip phases or defer ACs is a protocol violation. The same rule applies to orchestrator agents (sequential and team-mode L0/L1/L2/L3): they relay coder signals into the gate; they do not aggregate, summarize, or pre-filter deferrals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.68.0",
+  "version": "4.68.2",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"