baldart 4.68.1 → 4.68.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.

package/VERSION

@@ -1 +1 @@
-4.68.1
+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/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.1",
+  "version": "4.68.2",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"