baldart 4.21.0 → 4.22.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.22.0] - 2026-06-09
+
+**`/prd` Obsidian back-reference.** When a PRD is kicked off from an Obsidian note (the documental starting point), the same note now receives, at the end of the run, an idempotent snippet indexing how the feature was developed and where it landed — PRD path, epic + card IDs, branch, merge commit/PR, and the PRD's Canonical Sources — so the user can later query the note ("come è stata sviluppata la feature X, dov'è finita"). **MINOR** (additive capability on the `prd` skill; no new `baldart.config.yml` key — the note path is runtime-detected and state-persisted, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/.claude/skills/prd/references/validation-phase.md`** — new **Step 7.6 — Obsidian back-reference** (runs after the merge, when the canonical paths/IDs/SHA are final). Writes a marker-delimited section (`<!-- BALDART:prd:<slug> START/END -->`) holding a fenced `yaml` payload + human-readable links back into the spec note. **Idempotent** (re-runs / `/prd-add` replace the block in place), **non-blocking** (no note, unresolved vault path, or unwritable file → skip with a log line). The note lives in the user's vault, outside the worktree and outside git — a plain filesystem write, never staged.
+
+### Changed
+
+- **`framework/.claude/skills/prd/references/discovery-phase.md`** — Step 1 point 2 Obsidian detection broadened beyond `[[wikilink]]` to also accept `obsidian://open?…` URIs and pasted `.md` paths, and now resolves + persists the note's **absolute `path:`** (vault root from `paths.obsidian_vault` / memory / one-time ask) so Step 7.6 can write back without re-deriving.
+- **`framework/.claude/skills/prd/assets/state-template.md`** — new structured `## Obsidian Spec Note` section (`wikilink:` / `path:` / `status:`).
+- **`framework/.claude/skills/prd/SKILL.md`** — new **HARD RULE 19** (Obsidian back-reference) + Step 7.6 row in the flow table.
+- **`framework/.claude/skills/prd/references/prd-writing-phase.md`** — Canonical Sources row now reads the structured `wikilink:` field and cross-links Step 7.6.
+
+## [4.21.1] - 2026-06-09
+
+**Nightly reconciliation of the canonical API registries (errors.md / schemas.md).** Makes the nightly `doc-review` run explicitly keep `${paths.api_errors}` and `${paths.api_schemas}` in sync with the day's code changes, instead of relying on the generic doc↔code drift step. **PATCH** (strengthens existing routine/agent behaviour; no new agent/skill/command/config key).
+
+### Changed
+
+- **`framework/routines/doc-review.routine.yml`** — new step 3b: when `features.has_api_docs: true`, reconcile the canonical `errors.md` (stable error codes added/renamed/removed → apply or flag `DOC_GAP`) and `schemas.md` (Zod/TS shape changes → update or flag `SCHEMA_DRIFT`) against the last-24h commits. Skips silently when the paths are unset.
+- **`framework/.claude/agents/doc-reviewer.md`** — new "Canonical API registries — reconciliation (nightly-owned)" section: the agent now explicitly OWNS the code→doc direction for the two registries (the `doc-writing-for-rag` skill owns the doc-authoring direction). Ties together the existing `SCHEMA_DRIFT` + error-code checks.
+
 ## [4.21.0] - 2026-06-09
 
 **Code knowledge graph layer (Graphify) + Karpathy wiki rebind + nightly doc-alignment command.** Introduce [Graphify](https://github.com/safishamsi/graphify) as the new retrieval engine replacing the removed RAG (v4.20.0): a single language-agnostic tool (tree-sitter, 28 langs, local/offline, native Leiden communities; pip `graphifyy`, CLI `graphify` + `graphify-mcp`). Opt-in, runtime-detected, silent fallback to LSP→Grep→Git. **MINOR** (additive; new agent + 2 skills + 1 routine + 1 protocol module; new config key `features.has_code_graph` + `graph.*` propagated end-to-end per the schema-change rule).

package/VERSION

@@ -1 +1 @@
-4.21.0
+4.22.0

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

@@ -409,6 +409,21 @@ Beyond route existence, also check schema diffs:
 - For new fields in a documented payload: NEEDS_UPDATE.
 - For removed fields still in doc: ORPHAN_FIELD.
 
+## Canonical API registries — reconciliation (nightly-owned)
+
+When `features.has_api_docs: true`, you OWN keeping the two canonical registries in
+sync with code on the nightly `doc-review` run (and on any API-doc rewrite):
+- **`${paths.api_errors}`** (errors.md) — the single registry of stable error codes.
+  A code added / renamed / removed in the code → apply it to the right domain
+  section (trivial fix) or flag `DOC_GAP`. Endpoint docs link to the **domain
+  anchor**; they must never duplicate the table.
+- **`${paths.api_schemas}`** (schemas.md) — the documented projection of the
+  Zod/TS shapes (Zod-in-code stays the SSOT). A shape change → update the table or
+  flag `SCHEMA_DRIFT`.
+Skip silently when either path is unset. This is the code→doc direction that keeps
+the registries authoritative; the `doc-writing-for-rag` skill handles the
+doc-authoring (APPEND, no duplication) direction.
+
 ## Endpoint Count Reconciliation
 
 Applies **when the project uses file-system route handlers** (e.g. Next.js App Router `route.ts`). Adapt the commands to the project's actual API layout — the paths below are the common Next.js convention, not a hardcoded assumption. The convention: SSOT count in `api/index.md` = sum of HTTP method exports (a handler exporting GET + POST counts as 2 endpoints).

package/framework/.claude/skills/prd/SKILL.md

@@ -49,6 +49,7 @@ message. You ask questions, wait for answers, and iterate.
 | 5 | Backlog Cards | [backlog-phase.md](references/backlog-phase.md) |
 | 6 | Quality Audit | [validation-phase.md](references/validation-phase.md) |
 | 7 | Resolution, Commit & Merge | [validation-phase.md](references/validation-phase.md) |
+| 7.6 | Obsidian back-reference (only if a spec note was given) | [validation-phase.md](references/validation-phase.md) |
 
 **Before starting each phase, read the corresponding reference file.**
 
@@ -233,6 +234,21 @@ message. You ask questions, wait for answers, and iterate.
     transcripts for REAL per-role token + wall-clock cost. The token itself is NOT part
     of the feature description — strip it before recording the user's verbatim feature
     text in `## Feature Description`.
+19. **Obsidian back-reference (MANDATORY when a spec note was given).** If the user
+    kicked off the PRD from an Obsidian note (any of: `[[Note]]` wikilink,
+    `obsidian://open?…` URI, or a pasted `.md` path), Step 1 detection persists it in
+    the state file `## Obsidian Spec Note` (`wikilink:` + absolute `path:` + `status:`).
+    At the END of the run — **after** the merge (validation-phase Step 7, item 9) so the
+    paths/IDs/SHA are final — Step 7.6 writes an **idempotent** snippet back into that
+    note: a marker-delimited section (`<!-- BALDART:prd:<slug> START/END -->`) holding a
+    fenced `yaml` block with the feature slug, PRD path, epic + card IDs, branch, merge
+    commit/PR, and the PRD's Canonical Sources as `resources:`. This makes the original
+    note the durable index the user can later query ("come è stata sviluppata la feature
+    X, dov'è finita"). The note lives in the user's **vault, outside the worktree and
+    outside git** — it is a plain filesystem write, never staged/committed. The step is
+    **NON-BLOCKING**: no spec note, unresolved vault path, or an unwritable note all skip
+    it with a log line, never aborting the PRD. See discovery-phase.md Step 1 point 2 and
+    validation-phase.md Step 7.6.
 
 ---
 

package/framework/.claude/skills/prd/assets/state-template.md

@@ -12,6 +12,15 @@ stats_enabled: {{true if invoked with -stats/--stats, else false}}
 - created_at: {{ISO-8601 UTC}}
 - merge_commit: (pending — populated by validation-phase Step 7 after mw-docs)
 
+## Obsidian Spec Note
+
+<!-- Populated by discovery-phase.md Step 1 point 2 ONLY when the user passed an
+     Obsidian note as the documental starting point. When no note was given, leave
+     status: none and the Step 7.6 back-reference is skipped. -->
+wikilink: none        # [[Note Name]] form — feeds PRD Canonical Sources row
+path: none            # absolute fs path of the note — target of the Step 7.6 writeback
+status: none          # none | detected | back-reference-written
+
 ## Feature Description
 {{user's description verbatim}}
 

package/framework/.claude/skills/prd/references/discovery-phase.md

@@ -59,12 +59,31 @@ this is a fresh session (no existing state file).
 
 1. Derive `<slug>`: kebab-case, lowercase, max 40 chars, no special chars.
    Example: "Nutritional info on menu" -> `menu-nutritional-info`
-2. **Obsidian spec detection:** scan the user's message for Obsidian note references:
-   - Wikilink pattern: `[[Note Name]]` or `[[Note Name|Alias]]`
-   - If found: extract the note name and save it in the state file under
-     `## Obsidian Spec Note: [[Note Name]]`. This will be added to Canonical Sources in the PRD.
-   - Read the note content from the vault path in memory (`reference_obsidian_vault.md`)
-     to pre-populate discovery dimensions where possible — treat it as a user-provided spec.
+2. **Obsidian spec detection (and back-reference setup):** scan the user's message
+   for a reference to an Obsidian note used as the documental starting point. Accept
+   any of these forms:
+   - Wikilink: `[[Note Name]]` or `[[Note Name|Alias]]`.
+   - `obsidian://open?vault=<Vault>&file=<rel/path/Note>` URI (URL-decode `file`).
+   - A filesystem path to a `.md` file the user pastes ("la nota è in `…/Vault/…/Note.md`").
+
+   If found, populate the `## Obsidian Spec Note` section of the state file with:
+   - `wikilink:` — the `[[Note Name]]` form (for the PRD Canonical Sources row, see
+     prd-writing-phase.md Step 4 point 2).
+   - `path:` — the **absolute** filesystem path of the note. Resolve it now so the
+     end-of-run back-reference (validation-phase Step 7.6) can write to it without
+     re-deriving:
+     - URI/full path given → use it directly (URL-decode + join `vault`+`file`).
+     - Only a bare wikilink given → you need the vault root to resolve it. Use the
+       vault path recorded in memory (`reference_obsidian_vault.md`) if present; else
+       **ASK the user once** for the vault root (or the note's full path) and persist
+       their answer in this state section. Do NOT assume a default. If the user
+       declines, set `path: none` — detection still works for pre-population, but the
+       Step 7.6 writeback is skipped (logged, never fatal).
+   - `status: detected`.
+
+   Then read the note content (from `path:`) to pre-populate discovery dimensions
+   where possible — treat it as a user-provided spec. This same note becomes the
+   target of the back-reference snippet at the end of the run (HARD RULE 19).
 3. **Create the docs worktree (MANDATORY — HARD RULE 17)** — invoke the
    `worktree-manager` skill in programmatic docs mode BEFORE any file write:
 

package/framework/.claude/skills/prd/references/prd-writing-phase.md

@@ -7,10 +7,12 @@ Mark task 3 as `in_progress`.
 ## Write PRD
 
 1. Create directory `${paths.prd_dir}/<slug>/` if it doesn't exist.
-2. **Obsidian spec note (if present):** if the state file contains `## Obsidian Spec Note`,
-   add a row to the Canonical Sources table in the PRD:
+2. **Obsidian spec note (if present):** if the state file `## Obsidian Spec Note`
+   section has `status: detected`, add a row to the Canonical Sources table in the PRD
+   using its `wikilink:` value:
    `| Obsidian spec | [[Note Name]] |`
-   This preserves traceability from the user's original spec note to the final PRD.
+   This preserves traceability from the user's original spec note to the final PRD, and
+   the same note receives the end-of-run back-reference snippet (validation-phase Step 7.6).
 3. **Resolve canonical sources** before writing:
    - Read `${paths.references_dir}/ssot-registry.md` to identify the macro feature and any
      existing canonical docs.

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -247,6 +247,79 @@ markers it can emit, then act:
 empty, no `[SYNC-NEEDS-DECISION]` marker is left unhandled, and the merged remote
 branch is gone (or its deletion is explicitly user-deferred).
 
+### Step 7.6 — Obsidian back-reference (NON-BLOCKING — runs only when a spec note was given)
+
+**Why this exists.** When the user kicked off the PRD from an Obsidian note (state
+file `## Obsidian Spec Note / status: detected`, see HARD RULE 19), they want that
+same note to become the durable index of *how the feature was developed and where it
+landed* — so they can later ask "come è stata sviluppata la feature X?" and get the
+PRD, cards, and merge from the note itself. This step writes a single, idempotent,
+machine-and-human readable snippet back into the note.
+
+**Runs AFTER the merge (Step 7 item 9) succeeds** — only then are the canonical paths,
+card IDs, branch, PR/SHA final. The note lives in the user's **vault, OUTSIDE the
+worktree and outside git** — so this is a plain filesystem write to the absolute
+`path:`, NOT a worktree-relative path and NOT a git-tracked artefact (do not stage it).
+
+**Skip conditions (each logged, never fatal):**
+- `## Obsidian Spec Note / status` is `none` (no note was given) → skip silently.
+- `path:` is `none` or empty (vault root never resolved at Step 1) → skip with a note.
+- The file at `path:` does not exist or is not writable → skip with a one-line warning.
+
+**Procedure:**
+
+1. Read the current content of the note at `path:`.
+2. Build the snippet, delimited by HTML-comment markers keyed on the slug so the step
+   is **idempotent** — a re-run (or a later `/prd-add`) REPLACES the block between the
+   markers in place instead of appending a duplicate. If the markers are absent, append
+   the block at the end of the note (preceded by one blank line).
+
+   ```markdown
+   <!-- BALDART:prd:<slug> START -->
+   ## 🛠 Sviluppo BALDART — <slug>
+
+   ```yaml
+   feature: <slug>
+   prd: ${paths.prd_dir}/<slug>/PRD.md
+   epic: FEAT-XXXX-00-<slug>-epic
+   cards:
+     - FEAT-XXXX-01-<sub-slug>
+     - FEAT-XXXX-02-<sub-slug>
+   resources:        # other Canonical Sources from the PRD (mockups, ADRs, ref docs, research)
+     - ${paths.prd_dir}/<slug>/design.html      # omit if no design
+     - <ssot-registry entry / ADR path / research link>
+   branch: prd/<slug>
+   merge_commit: <SHA from state ## Validation>
+   pr: <PR number, or n/a for local-push>
+   trunk_branch: <git.trunk_branch>
+   date: <ISO-8601 UTC>
+   status: planned   # planned | in-progress | done
+   ```
+
+   - **PRD:** [`${paths.prd_dir}/<slug>/PRD.md`](...) 
+   - **Cards:** FEAT-XXXX-00 (epic) · FEAT-XXXX-01 · FEAT-XXXX-02 …
+   - **Merge:** `<SHA>` su `<git.trunk_branch>`<!-- · PR #N -->
+
+   _Generato da `/prd` il <date>. Aggiorna `status:` a `done` quando la feature è in produzione._
+   <!-- BALDART:prd:<slug> END -->
+   ```
+
+   Fill the `yaml` block from the final state: `<slug>`, the real epic + child card
+   IDs created in Step 5, the merge SHA written under `## Validation` (Step 7 item 8),
+   the PR number from the `mw-docs` return (or `n/a`), and the Canonical Sources list
+   the PRD already assembled (prd-writing-phase.md Step 4 point 3) for `resources:`.
+   The inner ```` ```yaml ```` block is fenced, NOT real top-of-file frontmatter — it
+   is the queryable payload Claude reads back when asked about the feature later.
+
+3. Write the updated note back to `path:`.
+4. Set `## Obsidian Spec Note / status: back-reference-written` in the state file.
+   (The state file is already committed; this is a local marker for a possible resume —
+   do NOT re-commit just for this field.)
+
+**This step is NON-BLOCKING** — any failure (note moved, vault unmounted, permission
+denied) logs "Obsidian back-reference: SKIPPED (<reason>)" and the run completes. The
+PRD merge has already happened; the back-reference is a convenience index, never a gate.
+
 ### Final output
 
 Print final summary:
@@ -257,6 +330,7 @@ Print final summary:
 - Branch & merge strategy used
 - PR number (if `strategy = pr`) or merge SHA (if `local-push`)
 - Confirmation that the worktree was cleaned up AND the remote branch was deleted
+- Obsidian back-reference: the note path the snippet was written to (only when Step 7.6 ran; omit otherwise)
 
 **HARD RULE — no passive deferral.** The final summary MUST NOT contain a
 "your manual actions / non-blocking notes / you can do it yourself" section.

package/framework/routines/doc-review.routine.yml

@@ -19,6 +19,14 @@ prompt: |
      references. Flag drift as `DOC_DRIFT`.
   3. For each source file change that landed without a corresponding doc
      update, flag `DOC_GAP`.
+  3b. If `features.has_api_docs: true`, reconcile the CANONICAL registries
+     against the day's code changes:
+       - `${paths.api_errors}` (errors.md): a stable error code added / renamed /
+         removed in the code → apply it to the registry (trivial) or flag
+         `DOC_GAP`. Endpoint docs must link to the domain anchor, never duplicate.
+       - `${paths.api_schemas}` (schemas.md): a route's Zod/TS request/response
+         shape changed → update the matching table or flag `SCHEMA_DRIFT`.
+     Skip silently when either path is unset.
   4. If the project ships a design-system SSOT, run the standard DS drift
      checks (INDEX coverage, per-component accuracy, animations
      reconciliation, tokens reconciliation).

package/package.json

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