baldart 4.21.1 → 4.22.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.1] - 2026-06-09
+
+**Epic-parent closure at end of `/new` + `/new2`.** When the last child of an epic is implemented, the epic/parent card now gets marked `DONE` automatically instead of being left stuck at `TODO`. The Phase 6b post-merge reconciliation gate only ever touched the **batch cards** (the children); the epic/parent card (`group.is_epic: true`) is excluded from the batch by the epic guard, so it never got reconciled — final-review only *reported* "all children done" without writing the epic's own status. **PATCH** (strengthens the existing Phase 6b reconciliation gate; no new agent/skill/command/config key — `/new2` inherits it because its merge agent follows `merge-cleanup.md` as SSOT).
+
+### Changed
+
+- **`framework/.claude/skills/new/references/merge-cleanup.md`** — Phase 6b gains **step 5e (Epic-parent closure)**: for each distinct `group.parent` of the batch (plus any epic card in the batch itself), if **every** child is `DONE` (checked across the whole backlog, not just the batch subset), force-update the epic card to `status: DONE` + `completed_date` + note, folded into the same reconciliation commit. Leaves the epic untouched if any child is still open. The step-6 tracker block now records `Epics closed: …`.
+- **`framework/.claude/skills/new/references/final-review.md`** — the "all cards in the epic are DONE" Next-Steps message now states the epic card itself is marked `DONE` (by Phase 6b step 5e), with a note that a still-`TODO` epic under all-DONE children is a Phase 6b failure to flag.
+- **`framework/.claude/workflows/new2.js`** — the merge agent's deterministic policies gain an explicit **EPIC CLOSURE** rule (all-children-DONE gate, distinct from the F-029 forced-DONE prohibition since the epic is a tracker), `MERGE_SCHEMA` gains `epicsClosed[]`, and a new `epic-closure` ledger entry records which epics were closed.
+
+## [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).

package/VERSION

@@ -1 +1 @@
-4.21.1
+4.22.1

package/framework/.claude/skills/new/references/final-review.md

@@ -303,10 +303,16 @@ deterministic script outside this orchestrator's context window.
    ```
    ## Prossimi Passi
 
-   Tutte le card dell'epic **FEAT-XXXX** sono state completate.
+   Tutte le card dell'epic **FEAT-XXXX** sono state completate, e la card epic stessa è
+   stata marcata `DONE` (chiusura automatica in Phase 6b, step 5e).
    Pronto per il deploy: `/deploy` o `git push origin <trunk branch>` (il `git.trunk_branch` configurato)
    ```
 
+   > Nota: la chiusura della card epic è eseguita dal gate Phase 6b (epic-parent closure),
+   > non da questo step di reporting — qui la si riporta soltanto. Se l'epic risultasse
+   > ancora `TODO`/`IN_PROGRESS` mentre tutti i figli sono `DONE`, è un fallimento di
+   > Phase 6b step 5e da segnalare in `## Issues & Flags`.
+
 5. **Proceed to Phase 7** (production readiness checklist).
 
 ---

package/framework/.claude/skills/new/references/merge-cleanup.md

@@ -74,12 +74,39 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
       - If doc-freshness requires ssot-registry.md → update its `last_verified_from_code` date, stage it, and retry.
       - If COMMIT_LOCK → re-run step 5a and retry.
       - Do NOT retry more than 2 times. Log the failure and move on.
+5e. **Epic-parent closure (MANDATORY — the epic card is NOT in the batch)**: the batch
+   implements children; the epic/parent card (`group.is_epic: true`, id usually ending
+   `-00` / filename `*-epic.yml` / `review_profile: skip`) is never implemented and is
+   excluded from the per-card loop in step 2 — so it stays at its old status (almost
+   always `TODO`) even when its **last** child just went DONE. Close it here, deterministically:
+
+   For each **distinct parent epic** referenced by the batch — the set of `group.parent`
+   values across the batch cards, PLUS any card in the batch that is itself an epic
+   (`group.is_epic: true`) — do:
+   a. Read the epic parent card `${paths.backlog_dir}/<EPIC-ID>.yml`. If `status: DONE`
+      already → skip (idempotent).
+   b. Check that **every** child is DONE (not just the batch's subset — children
+      implemented in earlier sessions count too):
+      ```bash
+      # Lists children of <EPIC-ID> that are NOT yet DONE. Empty output ⇒ all DONE.
+      grep -l "parent: <EPIC-ID>" ${paths.backlog_dir}/*.yml | xargs grep -L "status: DONE"
+      ```
+   c. **Only if** that command prints nothing (all children DONE) → force-update the epic
+      parent: set `status: DONE`, add `completed_date: <today>`, add note
+      `"Marked DONE by epic-closure gate (Phase 6b) — all children DONE"`. Stage it and
+      **fold into the SAME reconciliation commit** as step 5 (or, if step 5 didn't run
+      because all children were already DONE, make a dedicated
+      `[BATCH] Close epic <EPIC-ID> — all children DONE` commit, honoring the same
+      COMMIT_LOCK / doc-freshness precautions as step 5a–5d).
+   d. **If any child is still open** → leave the epic untouched: it is genuinely still in
+      progress, and step-4b's "Card rimanenti nell'epic" table already reports the gap.
 6. **Update tracker** with reconciliation results:
    ```
    ## Phase 6b — Status Reconciliation
    Cards checked: N
    Already DONE: M
    Force-updated to DONE: K [list card IDs]
+   Epics closed: J [list epic IDs] (or "none — children still open" / "n/a — no epic in batch")
    Reconciliation commit: <hash> (or "not needed")
    ```
 7. **HALT condition**: if a card cannot be updated (e.g., file read error, YAML parse error), log it in `## Issues & Flags` and continue with the remaining cards. Report the failure in the final summary.

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/.claude/workflows/new2.js

@@ -163,6 +163,7 @@ const MERGE_SCHEMA = {
     mergeTs: { type: 'string' },
     reconciliation: { type: 'string' },
     forcedDone: { type: 'array', items: { type: 'string' }, description: 'MUST be empty — false-DONE is forbidden (F-029)' },
+    epicsClosed: { type: 'array', items: { type: 'string' }, description: 'Epic/parent cards marked DONE by Phase 6b step 5e (all children DONE) — NOT a forcedDone violation' },
     uncommittedLeft: { type: 'boolean', description: 'true if dirty code was left (NOT committed) + reported (F-030)' },
     note: { type: 'string' },
   },
@@ -634,6 +635,7 @@ if (!committed.length) {
         `• G24 → auto-merge via merge_strategy.\n` +
         `• F-030 HARD RULE: NEVER \`git add\`/commit code that did not pass the per-card gates. If the worktree is dirty with uncommitted code → DO NOT commit it; leave it, set uncommittedLeft:true, and report. NO "safety commit". Security/migration code is NEVER swept in.\n` +
         `• F-029 HARD RULE: Phase 6b reconciliation marks a card DONE ONLY if it has a real commit in ${TRUNK}..HEAD AND its gates are green. NEVER force a non-implemented card to DONE. Return forcedDone:[] (must be empty).\n` +
+        `• EPIC CLOSURE (Phase 6b step 5e): the epic/parent card (group.is_epic:true) is NOT in the batch and stays TODO unless closed here. For each distinct group.parent of the batch cards (and any epic card in the batch itself): if EVERY child of that epic — \`grep -l "parent: <EPIC-ID>" backlog/*.yml | xargs grep -L "status: DONE"\` prints nothing — set the epic card status:DONE + completed_date + note "epic-closure gate — all children DONE" and fold into the reconciliation commit. If any child is still open → leave the epic untouched. This is NOT a forcedDone violation (the epic is a tracker, gated on all-children-DONE, not on its own commit). Return epicsClosed:[<EPIC-IDs marked DONE>].\n` +
         `• G19 sync-deferred → HEAD==${TRUNK} ff-pull, else leave+report. G20 → leave+report. G21 post-batch dirty → partition-ignore framework artifacts; leave the rest + report (do NOT commit). G22 divergence → behind: ff-pull; ahead/both: leave+report; NEVER reset --hard/force-push. G23 stash restore conflict → leave intact + report.\n\n` +
         `Return: { merged, mergeCommit, mergeTs, reconciliation, forcedDone:[], uncommittedLeft, note }`,
       { label: 'merge', phase: 'Merge', agentType: 'general-purpose', schema: MERGE_SCHEMA }
@@ -641,6 +643,7 @@ if (!committed.length) {
   } catch (e) { if (e && e.transientExhausted) noteDegraded('outage'); mergeResult = null }
   if (mergeResult && (mergeResult.forcedDone || []).length) { noteDegraded('false_done'); ledger(firstCard, 'F029-guard', 'VIOLATION', `forcedDone: ${mergeResult.forcedDone.join(' ')}`) }
   if (mergeResult && mergeResult.uncommittedLeft) ledger(firstCard, 'F030-guard', 'LEFT-UNCOMMITTED', 'dirty code left (not swept) + reported')
+  if (mergeResult && (mergeResult.epicsClosed || []).length) ledger(firstCard, 'epic-closure', 'CLOSED', `epics marked DONE (all children DONE): ${mergeResult.epicsClosed.join(' ')}`)
   ledger(firstCard, 'G24-merge', (mergeResult && mergeResult.merged) ? 'MERGED' : 'INCOMPLETE', (mergeResult && (mergeResult.mergeCommit || mergeResult.note)) || '')
   if (mergeResult && mergeResult.reconciliation) ledger(firstCard, 'G19-23-reconcile', 'AUTO', mergeResult.reconciliation)
 }

package/package.json

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