baldart 4.26.1 → 4.27.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.27.0] - 2026-06-11
+
+**`/prd`: the Obsidian back-reference is now two-phase — the spec note is linked the moment the PRD starts, not only at merge.** The end-of-run snippet (v4.22.0) is gated on a successful merge, so a PRD that is paused or abandoned mid-flow (e.g. parked at the UI-design step, worktree never merged) left its origin note empty — even though detection already happened at Step 1. Observed in the wild: a `realtime-order-collaboration` PRD stuck at `ui-design` never wrote back, while a completed sibling PRD did. **MINOR** (additive capability on `/prd`; reuses the existing slug-keyed markers + the snippet `status:` lifecycle field; no `baldart.config.yml` key, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/.claude/skills/prd/references/obsidian-backref.md`** — new shared SSOT for the back-reference: the marker contract (`<!-- BALDART:prd:<slug> START/END -->`), the idempotent read-replace-or-append write procedure, the skip conditions (no note / `path: none` / unwritable → log, never fatal), and the two write modes. Both call sites cite it, so the snippet shape can't drift between them.
+- **Provisional write at detection (discovery-phase Step 1 point 2).** Right after the Obsidian note is detected, `/prd` writes a lightweight `status: drafting` block (slug + deterministic branch `prd/<slug>` + planned PRD path + trunk) into the note and sets state `## Obsidian Spec Note / status: provisional-written`. The note reflects "a PRD was started here" immediately.
+
+### Changed
+
+- **Final write upgrades the provisional block in place (validation-phase Step 7.6).** Same slug-keyed markers, so the post-merge full payload (epic + card IDs, merge SHA/PR, `resources:`, `status: planned`) replaces the `drafting` block — no duplicates. Step 7.6 is now a lean delegation to `obsidian-backref.md § Mode: FINAL` instead of an inlined copy of the snippet.
+- **Snippet `status:` enum tightened to `drafting | planned | done`** (was `planned | in-progress | done`) — a clean ladder: PRD in stesura → mergiato/pianificato → in produzione.
+- **State `## Obsidian Spec Note / status` enum** gains `provisional-written`: `none → detected → provisional-written → back-reference-written`.
+- **Coupling fix:** `prd-writing-phase.md` Step 4 point 2 now adds the PRD Canonical Sources row when the note status is anything other than `none` (was hard-coded to `== detected`), so the provisional-write status change doesn't suppress the traceability row.
+- **`SKILL.md` HARD RULE 19** rewritten for the two-phase lifecycle; flow-table gains a `1.2` row and annotates `7.6` as the FINAL upgrade.
+
 ## [4.26.1] - 2026-06-11
 
 **`new2`: specialization integrity — a full audit of every agent spawn; no role mixing anywhere.** User principle: code is written ONLY by `coder`, UI only by `ui-expert`, each agent does one thing. The audit of all 16 spawn sites found two genuine violations and three under-specified plumbing roles. **PATCH** (role-integrity fixes on the EXPERIMENTAL `new2` surface; no config key, no change to `/new`).

package/VERSION

@@ -1 +1 @@
-4.26.1
+4.27.0

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

@@ -38,6 +38,7 @@ message. You ask questions, wait for answers, and iterate.
 |------|-------|-----------|
 | 0 | Context Recovery | [discovery-phase.md](references/discovery-phase.md) |
 | 1 | Kickoff | [discovery-phase.md](references/discovery-phase.md) |
+| 1.2 | Obsidian provisional back-reference (only if a spec note was given) | [discovery-phase.md](references/discovery-phase.md) + [obsidian-backref.md](references/obsidian-backref.md) |
 | 1.6 | Mockup Intake | [discovery-phase.md](references/discovery-phase.md) |
 | 2 | Discovery Question Loop (+ Codex completeness cross-check at exit, v4.19.0) | [discovery-phase.md](references/discovery-phase.md) |
 | 2→CR | Change Request (auto/manual) | the canonical **`prd-add` skill** ([../prd-add/SKILL.md](../prd-add/SKILL.md)) — worktree-aware (`references/prd-add-phase.md` is a redirect stub, not the implementation) |
@@ -49,7 +50,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) |
+| 7.6 | Obsidian back-reference — FINAL (upgrades the 1.2 provisional block; only if a spec note was given) | [validation-phase.md](references/validation-phase.md) + [obsidian-backref.md](references/obsidian-backref.md) |
 
 **Before starting each phase, read the corresponding reference file.**
 
@@ -234,21 +235,28 @@ 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.
+19. **Obsidian back-reference (MANDATORY when a spec note was given — TWO-PHASE since
+    v4.27.0).** If the user kicked off the PRD from an Obsidian note (any of: `[[Note]]`
+    wikilink, `obsidian://open?…` URI, or a pasted `.md` path), the same note becomes the
+    durable index the user can later query ("come è stata sviluppata la feature X, dov'è
+    finita"). It is written in two phases against ONE slug-keyed marker block
+    (`<!-- BALDART:prd:<slug> START/END -->`), so the second write replaces the first in
+    place (idempotent, no duplicates):
+    - **Provisional** — at Step 1 detection (discovery-phase Step 1 point 2): a lightweight
+      `status: drafting` block with slug + branch `prd/<slug>` + planned PRD path. So the
+      note reflects "a PRD was started here" **immediately**, even if the run is later
+      paused or abandoned before merge.
+    - **Final** — at the END of the run, **after** the merge (validation-phase Step 7 item
+      9) so paths/IDs/SHA are final (Step 7.6): the full payload — feature slug, PRD path,
+      epic + card IDs, branch, merge commit/PR, Canonical Sources as `resources:`,
+      `status: planned`.
+
+    The note lives in the user's **vault, outside the worktree and outside git** — a plain
+    filesystem write, never staged/committed. Both writes are **NON-BLOCKING**: no spec
+    note, unresolved vault path, or an unwritable note all skip with a log line, never
+    aborting the PRD. SSOT for the marker contract + write procedure + both modes:
+    [obsidian-backref.md](references/obsidian-backref.md). See also discovery-phase.md Step
+    1 point 2 and validation-phase.md Step 7.6.
 
 ---
 

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

@@ -16,10 +16,12 @@ stats_enabled: {{true if invoked with -stats/--stats, else false}}
 
 <!-- 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. -->
+     status: none and both back-reference writes are 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
+path: none            # absolute fs path of the note — target of the back-reference writeback
+status: none          # none | detected | provisional-written | back-reference-written
+                      # detected → provisional snippet written at Step 1.2 (provisional-written)
+                      # → upgraded to the full payload at Step 7.6 (back-reference-written)
 
 ## Feature Description
 {{user's description verbatim}}

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

@@ -84,6 +84,17 @@ this is a fresh session (no existing state file).
    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).
+
+   **Provisional back-reference (NON-BLOCKING — v4.27.0).** Immediately after detection,
+   write a *provisional* snippet into the note so it reflects "a PRD was started here" even
+   if this session is later paused or abandoned before merge (the FINAL snippet at
+   validation-phase Step 7.6 is gated on a successful merge and would otherwise never run
+   for an incomplete PRD). Follow [obsidian-backref.md](obsidian-backref.md) **§ Mode:
+   PROVISIONAL** — the marker block is keyed on `<slug>`, so the FINAL write later replaces
+   it in place (no duplicates). All skip conditions in that module apply (no note / `path:
+   none` / unwritable → log and continue, never fatal). On success the module sets
+   `## Obsidian Spec Note / status: provisional-written`. The branch is the deterministic
+   `prd/<slug>` that `nw-docs` creates in the next point.
 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/obsidian-backref.md

@@ -0,0 +1,120 @@
+# Obsidian Back-Reference (shared SSOT)
+
+Single source of truth for the **idempotent back-reference snippet** that `/prd` writes
+into the user's Obsidian spec note. Two phases call this module; both target the SAME
+marker block keyed on the slug, so the later write **replaces the earlier one in place** —
+the note never accumulates duplicates.
+
+| Phase | Caller | Mode | Trigger |
+|---|---|---|---|
+| Provisional | `discovery-phase.md` Step 1 point 2 | `PROVISIONAL` | right after the note is detected — the PRD has only just started |
+| Final | `validation-phase.md` Step 7.6 | `FINAL` | after the merge succeeds — paths, card IDs, branch, SHA are now final |
+
+**Why two phases (v4.27.0).** A PRD can be paused or abandoned mid-flow (e.g. parked at the
+UI-design step, worktree never merged). The FINAL write is gated on a successful merge, so
+without a provisional write the note would stay empty for every incomplete PRD — even
+though detection already happened at Step 1. The provisional write makes the note reflect
+"a PRD was started here" immediately; the FINAL write upgrades it to the full,
+queryable payload once the run completes.
+
+## Marker contract
+
+The block is delimited by HTML-comment markers keyed on `<slug>`:
+
+```
+<!-- BALDART:prd:<slug> START -->
+…block…
+<!-- BALDART:prd:<slug> END -->
+```
+
+**Write procedure (identical for both modes):**
+1. Read the current note content at the absolute `path:` from state `## Obsidian Spec Note`.
+2. If both markers are present → REPLACE everything between them (inclusive) with the new block.
+3. If markers are absent → APPEND the new block at the end of the note, preceded by one blank line.
+4. Write the note back to `path:`.
+
+The note lives in the user's **vault, outside the worktree and outside git** — it is a
+plain filesystem write to the absolute `path:`, NEVER staged or committed.
+
+## Skip conditions (each logged, NEVER fatal — both phases)
+
+- `## Obsidian Spec Note / status` is `none` (no note was given) → skip silently.
+- `path:` is `none`/empty (vault root never resolved at Step 1) → skip with a one-line note.
+- The file at `path:` does not exist or is not writable → skip with a one-line warning.
+
+The back-reference is a convenience index, never a gate. Any failure logs
+`"Obsidian back-reference: SKIPPED (<reason>)"` and the run continues.
+
+## Mode: PROVISIONAL — `discovery-phase.md` Step 1 point 2
+
+**Known here:** `<slug>`, the deterministic branch `prd/<slug>` (the name `worktree-manager
+nw-docs` always uses), the planned PRD path, `git.trunk_branch`, the detection timestamp.
+**Not yet known:** epic/card IDs (Step 5), the merge SHA/PR (Step 7), the full Canonical
+Sources list (Step 4). Write the lighter block:
+
+````markdown
+<!-- BALDART:prd:<slug> START -->
+## 🛠 Sviluppo BALDART — <slug>
+
+```yaml
+feature: <slug>
+prd: ${paths.prd_dir}/<slug>/PRD.md   # path pianificato — il file viene scritto a Step 4
+branch: prd/<slug>
+trunk_branch: <git.trunk_branch>
+started: <ISO-8601 UTC>
+status: drafting   # drafting | planned | done
+```
+
+- **Stato:** PRD in stesura sul branch `prd/<slug>`. Lo snippet verrà completato al merge.
+
+_Avviato da `/prd` il <date>. Questo blocco si aggiorna automaticamente con card, merge e sorgenti canoniche quando il PRD viene mergiato._
+<!-- BALDART:prd:<slug> END -->
+````
+
+After the write, set `## Obsidian Spec Note / status: provisional-written` in the state file.
+
+## Mode: FINAL — `validation-phase.md` Step 7.6
+
+Runs AFTER the merge (Step 7 item 9). All identifiers are final. Write the full block,
+REPLACING the provisional one in place:
+
+````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   # drafting | planned | 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` 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 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.
+
+After the write, 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.)

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

@@ -8,8 +8,9 @@ Mark task 3 as `in_progress`.
 
 1. Create directory `${paths.prd_dir}/<slug>/` if it doesn't exist.
 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:
+   section has `status` other than `none` (i.e. `detected`, `provisional-written`, or
+   `back-reference-written` — a note was given), 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, and
    the same note receives the end-of-run back-reference snippet (validation-phase Step 7.6).

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

@@ -249,76 +249,32 @@ 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.
+**Why this exists.** When the user kicked off the PRD from an Obsidian note (state file
+`## Obsidian Spec Note / status` is not `none`, 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.
 
-**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 -->
+This is the **FINAL** write of the two-phase back-reference (the provisional write already
+happened at discovery-phase Step 1 point 2, status `provisional-written`). It **upgrades
+the provisional block in place** — same slug-keyed markers — replacing the lightweight
+"PRD in stesura" block with the full, queryable payload.
 
-   _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.
+**Runs AFTER the merge (Step 7 item 9) succeeds** — only then are the canonical paths,
+card IDs, branch, PR/SHA final.
 
-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.)
+**Procedure:** follow [obsidian-backref.md](obsidian-backref.md) **§ Mode: FINAL** — it is
+the SSOT for the marker contract, the idempotent read-replace-or-append write procedure,
+the full snippet template, the skip conditions (no note / `path: none` / unwritable → log
+and continue, never fatal), and the final state update to
+`## Obsidian Spec Note / status: back-reference-written`. Fill the `yaml` from the final
+state: the real epic + child card IDs (Step 5), the merge SHA under `## Validation` (Step 7
+item 8), the PR number from the `mw-docs` return (or `n/a`), and the Canonical Sources the
+PRD assembled (prd-writing-phase.md Step 4 point 3) for `resources:`.
 
 **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.
+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
 

package/package.json

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