prodc 0.4.0__tar.gz → 0.4.2__tar.gz

{prodc-0.4.0 → prodc-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.4.0
+Version: 0.4.2
 Summary: Product management as code: roles, flows, and features traced to evidence.
 Project-URL: Homepage, https://gitlab.com/jorgeecardona/prodc
 Project-URL: Repository, https://gitlab.com/jorgeecardona/prodc

{prodc-0.4.0 → prodc-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.4.0"
+version = "0.4.2"
 description = "Product management as code: roles, flows, and features traced to evidence."
 readme = "README.md"
 requires-python = ">=3.12"

{prodc-0.4.0 → prodc-0.4.2}/src/prodc/cli/render.py

@@ -382,7 +382,10 @@ def render_show(
     else:
         lines.append("  sources: (none — opinion)")
     if need.children:
-        lines.append(f"  children: {', '.join(need.children)}")
+        rendered = ", ".join(
+            c.id if c.step is None else f"{c.id}@{c.step}" for c in need.children
+        )
+        lines.append(f"  children: {rendered}")
     if need.contradicts:
         lines.append(f"  contradicts: {', '.join(need.contradicts)}")
     if need.seam:

{prodc-0.4.0 → prodc-0.4.2}/src/prodc/cli/serialize.py

@@ -160,7 +160,7 @@ def show_json(r: NeedResult, decisions: list[Decision] | None = None) -> str:
                 for s in need.sources
             ],
             "proofs": list(need.proofs),
-            "children": list(need.children),
+            "children": [{"id": c.id, "step": c.step} for c in need.children],
             "seam": list(need.seam),
         }
     )

{prodc-0.4.0 → prodc-0.4.2}/src/prodc/loader.py

@@ -8,6 +8,7 @@ IDs are globally unique (children reference ids across files), so a duplicate is
 from __future__ import annotations
 
 import datetime
+import re
 from collections.abc import Callable
 from dataclasses import dataclass, field, replace
 from pathlib import Path
@@ -20,6 +21,7 @@ from .model import (
     Answer,
     Attestation,
     AttestationKind,
+    Child,
     Decision,
     Goal,
     Model,
@@ -202,6 +204,21 @@ def _source(raw: object, where: str) -> Source:
     )
 
 
+def _child(raw: object, where: str) -> Child:
+    """Parse one flow edge: a bare id string, or a ``{id, step}`` mapping (#90).
+
+    A bare ``US-050`` stays valid (``Child("US-050")`` with no step), so existing flows load
+    unchanged; a mapping adds the optional ``step`` the edge plays in the journey.
+    """
+    if isinstance(raw, str):
+        return Child(id=raw)
+    tbl = _as_mapping(raw, where)
+    return Child(
+        id=_as_str(tbl.get("id"), f"{where}.id"),
+        step=_opt_str(tbl.get("step"), f"{where}.step"),
+    )
+
+
 def _need(
     raw: object,
     where: str,
@@ -242,7 +259,7 @@ def _need(
         for i, p in enumerate(_as_list(tbl.get("proofs"), f"{where}.proofs"))
     )
     children = tuple(
-        _as_str(c, f"{where}.children[{i}]")
+        _child(c, f"{where}.children[{i}]")
         for i, c in enumerate(_as_list(tbl.get("children"), f"{where}.children"))
     )
     seam = tuple(
@@ -383,13 +400,44 @@ class _Loaded:
     decisions: list[Decision] = field(default_factory=list[Decision])
 
 
+def yaml_error_message(where: str, text: str, exc: yaml.YAMLError) -> str:
+    """Turn a raw PyYAML parse error into a prodc message naming the file, line and nearest need (#84).
+
+    PyYAML points at ``"<unicode string>", line N`` with no file or need id; on a 200-line board that
+    leaves the author hunting by hand. We name the file and line, scan back to the nearest ``id:`` so
+    the offending need is identified, and — for the common ``": "``-in-prose case — spell out the fix.
+    """
+    mark = getattr(exc, "problem_mark", None)
+    problem = getattr(exc, "problem", None) or "invalid YAML"
+    if mark is None:
+        return f"{where}: invalid YAML: {exc}"
+    lines = text.splitlines()
+    loc = f"{where}: line {mark.line + 1}"
+    nid: str | None = None
+    for j in range(min(mark.line, len(lines) - 1), -1, -1):
+        m = re.match(r"^\s*-?\s*id:\s*(\S+)", lines[j])
+        if m:
+            nid = m.group(1).strip("\"'")
+            break
+    if nid is not None:
+        loc += f" (need {nid!r})"
+    msg = f"{loc}: {problem}"
+    if "mapping values are not allowed here" in problem:
+        msg += (
+            " — a ': ' in an unquoted claim/text reads as a nested mapping; "
+            "quote the value in single quotes or rephrase"
+        )
+    return msg
+
+
 def _load_file(path: Path, seen: dict[str, dict[str, Path]]) -> _Loaded:
     """Parse one prodc file for every noun list it carries (``needs:``/``goals:``/``principles:``/…)."""
     where = path.name
+    text = path.read_text(encoding="utf-8")
     try:
-        doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+        doc = yaml.safe_load(text)
     except yaml.YAMLError as exc:
-        raise LoaderError(f"{where}: invalid YAML: {exc}") from exc
+        raise LoaderError(yaml_error_message(where, text, exc)) from exc
     out = _Loaded()
     if doc is None:
         return out
@@ -532,9 +580,9 @@ def _check_children(needs: list[Need]) -> None:
     """Every id in a need's ``children`` must name a known need."""
     known = {n.id for n in needs}
     for need in needs:
-        for cid in need.children:
-            if cid not in known:
-                raise LoaderError(f"need {need.id!r}: child {cid!r} is not a known need id")
+        for c in need.children:
+            if c.id not in known:
+                raise LoaderError(f"need {need.id!r}: child {c.id!r} is not a known need id")
 
 
 def _check_withdrawal_of(needs: list[Need]) -> None:

{prodc-0.4.0 → prodc-0.4.2}/src/prodc/model.py

@@ -257,6 +257,21 @@ class Withdrawal:
     of: str | None = None  # id of the need this one duplicates (required when kind is duplicate)
 
 
+@dataclass(frozen=True)
+class Child:
+    """One edge of a flow: the sub-need and, optionally, the ``step`` it plays in the journey (#90).
+
+    A flow's ``children`` are ordered, and a use case ("job") is just a flow with a ``role`` set and
+    a ``step`` on each edge (locate / execute / conclude). The step annotates the *edge*, not the
+    sub-need — the same need can be the ``execute`` step of one flow and the ``locate`` of another —
+    so it lives here, not on :class:`Need`. A bare ``US-050`` in YAML loads as ``Child("US-050")``
+    with no step, so every existing flow keeps working unchanged.
+    """
+
+    id: str
+    step: str | None = None
+
+
 @dataclass(frozen=True)
 class Need:
     """What a named person wants, with its provenance and its proofs."""
@@ -269,7 +284,7 @@ class Need:
     must: bool = False
     sources: tuple[Source, ...] = ()
     proofs: tuple[str, ...] = ()  # locators, "<adapter>:<payload>" (leaf needs)
-    children: tuple[str, ...] = ()  # ids of sub-needs (a flow is a Need with children)
+    children: tuple[Child, ...] = ()  # ordered sub-need edges (a flow is a Need with children)
     seam: tuple[str, ...] = ()  # end-to-end proof locators for a flow's between-steps behaviour
     client: str | None = None  # which client this instance is for; None = shared baseline
     variant_of: str | None = None  # id of the baseline need this specialises; None = standalone

{prodc-0.4.0 → prodc-0.4.2}/src/prodc/status.py

@@ -293,11 +293,11 @@ class Resolver:
         warnings: list[str] = []
         child_states: list[NeedState] = []
         declared = False
-        for cid in need.children:
-            if cid not in self._by_id:
-                warnings.append(f"unknown child id '{cid}'")
+        for c in need.children:
+            if c.id not in self._by_id:
+                warnings.append(f"unknown child id '{c.id}'")
                 continue
-            cr = self.resolve(cid)
+            cr = self.resolve(c.id)
             child_states.append(cr.state)
             declared = declared or cr.declared
         delivered = sum(1 for s in child_states if s is NeedState.DELIVERED)
@@ -806,7 +806,7 @@ def handoffs(needs: list[Need]) -> list[Handoff]:
     for flow in needs:
         if not flow.children:
             continue
-        steps = [by_id[c] for c in flow.children if c in by_id]
+        steps = [by_id[c.id] for c in flow.children if c.id in by_id]
         for a, b in pairwise(steps):
             if a.role and b.role and a.role != b.role:
                 out.append(Handoff(flow, a, b, a.role, b.role))
@@ -844,7 +844,7 @@ def flow_orphan_warnings(needs: list[Need]) -> set[str]:
         return set()
     in_a_flow: set[str] = set()
     for flow in flows:
-        in_a_flow.update(flow.children)
+        in_a_flow.update(c.id for c in flow.children)
     return {n.id for n in needs if not n.children and n.id not in in_a_flow}
 
 

{prodc-0.4.0 → prodc-0.4.2}/src/prodc/writer.py

@@ -14,6 +14,7 @@ import datetime
 import difflib
 import hashlib
 import re
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
@@ -24,7 +25,7 @@ from .config import Config
 
 if TYPE_CHECKING:
     from .model import Source
-from .loader import LoaderError, load
+from .loader import LoaderError, load, yaml_error_message
 
 # Fields an agent may `set` on a need. Unknown keys are silently ignored by the loader, so the
 # write path allowlists instead — a typo'd key is an error here, not junk written to disk.
@@ -106,23 +107,24 @@ def _need_block_span(lines: list[str], need_id: str) -> tuple[int, int, int] | N
     return _block_span(lines, "needs", need_id)
 
 
-def _block_span(lines: list[str], key: str, item_id: str) -> tuple[int, int, int] | None:
-    """Line span [start, end) and item indent of the top-level ``key:`` list item ``item_id``.
+def _scan_list(lines: list[str], key: str) -> tuple[list[tuple[int, str | None]], int, int] | None:
+    """Scan the top-level ``key:`` list; returns ``(item_starts, region_end, item_indent)`` or None.
 
-    Line-based and deliberately conservative: it understands the common prodc layout (a
+    ``item_starts`` is ``(start_line, id)`` per list item, ``region_end`` is the line index just
+    past the list (before trailing blanks/comments are trimmed), and ``item_indent`` is the ``- ``
+    indent. Line-based and deliberately conservative: it understands the common prodc layout (a
     top-level list key — ``needs:``, ``principles:`` — whose items are ``- `` at a fixed indent) and
-    returns None for anything it is not sure about, so the caller can fall back to a full
-    re-dump. Trailing blank and comment lines are left out of the span, so a comment that
-    introduces the *next* item is never swallowed.
+    returns None for anything it is not sure about, so the caller can fall back to a full re-dump.
+    The single scanner behind both the edit splice (:func:`_block_span`) and the append (#85).
     """
     key_line = re.compile(rf"^{re.escape(key)}:\s*(#.*)?$")
-    needs_at = next((i for i, ln in enumerate(lines) if key_line.match(ln)), None)
-    if needs_at is None:
+    key_at = next((i for i, ln in enumerate(lines) if key_line.match(ln)), None)
+    if key_at is None:
         return None
     item_re = None
     item_indent = -1
-    i = needs_at + 1
-    spans: list[tuple[int, int, int, str | None]] = []  # start, end, indent, id
+    i = key_at + 1
+    starts: list[tuple[int, str | None]] = []
     while i < len(lines):
         line = lines[i]
         stripped = line.strip()
@@ -133,19 +135,33 @@ def _block_span(lines: list[str], key: str, item_id: str) -> tuple[int, int, int
         m = re.match(r"^(\s*)-\s", line)
         if item_re is None:
             if m is None:
-                return None  # first non-blank line under needs: isn't a list item — unknown shape
+                return None  # first non-blank line under the key isn't a list item — unknown shape
             item_indent = len(m.group(1))
             item_re = re.compile(rf"^\s{{{item_indent}}}-\s")
         if indent < item_indent and m is None:
-            break  # dedented past the list — end of needs:
+            break  # dedented past the list — end of the key's region
         if item_re.match(line):
-            spans.append((i, i, item_indent, _item_id(lines, i, item_indent)))
+            starts.append((i, _item_id(lines, i, item_indent)))
         elif indent <= item_indent and m is None:
             break
         i += 1
-    # close each span at the start of the next item (or `i`, the end of the list region)
-    bounds = [s[0] for s in spans] + [i]
-    for idx, (start, _e, indent, iid) in enumerate(spans):
+    return starts, i, item_indent
+
+
+def _block_span(lines: list[str], key: str, item_id: str) -> tuple[int, int, int] | None:
+    """Line span [start, end) and item indent of the top-level ``key:`` list item ``item_id``.
+
+    Trailing blank and comment lines are left out of the span, so a comment that introduces the
+    *next* item is never swallowed. None when the key is absent, the shape is unrecognised, or no
+    item carries ``item_id`` — the caller then falls back to a full re-dump.
+    """
+    scanned = _scan_list(lines, key)
+    if scanned is None:
+        return None
+    starts, region_end, item_indent = scanned
+    # close each span at the start of the next item (or `region_end`, the end of the list region)
+    bounds = [s[0] for s in starts] + [region_end]
+    for idx, (start, iid) in enumerate(starts):
         if iid != item_id:
             continue
         end = bounds[idx + 1]
@@ -153,7 +169,7 @@ def _block_span(lines: list[str], key: str, item_id: str) -> tuple[int, int, int
             lines[end - 1].strip() == "" or lines[end - 1].strip().startswith("#")
         ):
             end -= 1
-        return start, end, indent
+        return start, end, item_indent
     return None
 
 
@@ -234,6 +250,48 @@ def _render_item_edit(old_text: str, doc: dict[str, object], key: str, item_id:
     return "".join(lines[:start]) + block + "".join(lines[end:])
 
 
+def _render_item_append(old_text: str, doc: dict[str, object], key: str, item_id: str) -> str:
+    """Append the new ``key:`` list item ``item_id`` to ``old_text``, every comment intact (#85).
+
+    The insert mirror of :func:`_render_item_edit`: dump only the new item and splice it in after
+    the last existing item of the list, so the header, the other items, and their comments stay
+    byte-for-byte. Falls back to a full re-dump when the file has no recognised ``key:`` list to
+    append to (a brand-new file or key, where there are no in-list comments to lose); the reload
+    gate in :func:`_validated` guards correctness either way.
+    """
+    lines = old_text.splitlines(keepends=True)
+    scanned = _scan_list(lines, key)
+    items = doc.get(key)
+    if scanned is None or not isinstance(items, list):
+        return _dump(doc)
+    starts, region_end, item_indent = scanned
+    if not starts:  # the key exists but holds no recognised item — re-dump rather than guess indent
+        return _dump(doc)
+    item = next(
+        (
+            cast("dict[str, object]", n)
+            for n in cast("list[object]", items)
+            if isinstance(n, dict) and cast("dict[str, object]", n).get("id") == item_id
+        ),
+        None,
+    )
+    if item is None:
+        return _dump(doc)
+    # insert after the last item's content, before any trailing blank/comment lines of the section
+    insert_at = region_end
+    first_start = starts[0][0]
+    while insert_at - 1 >= first_start and (
+        lines[insert_at - 1].strip() == "" or lines[insert_at - 1].strip().startswith("#")
+    ):
+        insert_at -= 1
+    dumped = yaml.safe_dump([item], sort_keys=False, allow_unicode=True, default_flow_style=False)
+    pad = " " * item_indent
+    block = "".join(pad + ln if ln.strip() else ln for ln in dumped.splitlines(keepends=True))
+    if insert_at > 0 and not lines[insert_at - 1].endswith("\n"):
+        block = "\n" + block  # the item before the insert point had no trailing newline
+    return "".join(lines[:insert_at]) + block + "".join(lines[insert_at:])
+
+
 def _render_delete(old_text: str, doc: dict[str, object], need_id: str) -> str:
     """Re-render after removing a need, excising only its block to keep every other comment (#60).
 
@@ -255,7 +313,7 @@ def _read_doc(path: Path) -> tuple[dict[str, object], str]:
     try:
         doc = yaml.safe_load(text)
     except yaml.YAMLError as exc:
-        raise WriteError(f"{path.name}: invalid YAML: {exc}") from exc
+        raise WriteError(yaml_error_message(path.name, text, exc)) from exc
     if doc is None:
         doc = {}
     if not isinstance(doc, dict):
@@ -270,6 +328,14 @@ def _need_list(doc: dict[str, object], path: Path) -> list[object]:
     return cast("list[object]", raw)
 
 
+def _proof_list(need: dict[str, object], path: Path) -> list[object]:
+    """A fresh copy of a need's ``proofs`` list, erroring if the field is present but not a list."""
+    current = need.get("proofs", [])
+    if not isinstance(current, list):
+        raise WriteError(f"{path.name}: 'proofs' is not a list")
+    return list(cast("list[object]", current))
+
+
 def _config_files(config: Config) -> list[Path]:
     seen: set[Path] = set()
     out: list[Path] = []
@@ -299,6 +365,19 @@ def _coerce(value: str) -> object:
         return value
 
 
+def _child_item(raw: str) -> object:
+    """Parse a ``children+=`` value into a flow edge: ``id`` stays a bare string, ``id@step`` a map.
+
+    Mirrors the loader's dual shape (#90): ``children+=US-050`` appends the bare id (unstepped),
+    ``children+=US-052@execute`` appends ``{id: US-052, step: execute}``. A bare id keeps the file's
+    existing plain-string style; the ``@`` suffix mirrors the ``need:A@yes`` proof-locator idiom.
+    """
+    head, sep, step = raw.partition("@")
+    if not sep:
+        return raw
+    return {"id": head.strip(), "step": step.strip()}
+
+
 def _apply_assignment(need: dict[str, object], assignment: str, path: Path) -> None:
     if "+=" in assignment:
         key, _, raw = assignment.partition("+=")
@@ -311,7 +390,7 @@ def _apply_assignment(need: dict[str, object], assignment: str, path: Path) -> N
         if not isinstance(current, list):
             raise WriteError(f"{path.name}: {key!r} is not a list")
         items = cast("list[object]", current)
-        items.append(raw.strip())
+        items.append(_child_item(raw.strip()) if key == "children" else raw.strip())
         need[key] = items
         return
     key, sep, raw = assignment.partition("=")
@@ -364,21 +443,46 @@ def _validated(config: Config, path: Path, old_text: str, new_text: str, dry_run
     return Edit(path=path, old_text=old_text, new_text=new_text)
 
 
-def set_field(
-    config: Config, need_id: str, assignment: str, *, expect_sha: str | None, dry_run: bool
+def _edit_one_need(
+    config: Config,
+    need_id: str,
+    *,
+    expect_sha: str | None,
+    dry_run: bool,
+    mutate: Callable[[dict[str, object], Path], None],
 ) -> Edit:
-    """Set or list-append one field on an existing need, validated against the loader."""
+    """Run ``mutate`` on one existing need's raw mapping, comment-safe and reload-gated (#82).
+
+    The shared skeleton of every single-need writer: locate the file → read it → check the
+    optimistic lock → find the need by id → apply ``mutate`` (the only part that differs) → splice
+    just that need's block back (#53) → re-load as the schema and revert on failure (:func:`_validated`).
+    ``mutate`` receives the need's mapping and the file path (for field-level errors) and edits the
+    mapping in place; raising :class:`WriteError` from it aborts before anything is written.
+    """
     path, _ = _locate(config, need_id)
     doc, old_text = _read_doc(path)
     if expect_sha is not None and _sha256(old_text) != expect_sha:
         raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
     for raw in _need_list(doc, path):
         if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            _apply_assignment(cast("dict[str, object]", raw), assignment, path)
+            mutate(cast("dict[str, object]", raw), path)
             break
     return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
 
 
+def set_field(
+    config: Config, need_id: str, assignment: str, *, expect_sha: str | None, dry_run: bool
+) -> Edit:
+    """Set or list-append one field on an existing need, validated against the loader."""
+    return _edit_one_need(
+        config,
+        need_id,
+        expect_sha=expect_sha,
+        dry_run=dry_run,
+        mutate=lambda need, path: _apply_assignment(need, assignment, path),
+    )
+
+
 def set_importance(
     config: Config, need_id: str, level: int, when: str, *, expect_sha: str | None, dry_run: bool
 ) -> Edit:
@@ -387,17 +491,14 @@ def set_importance(
     The level is already resolved against the rubric by the caller; this just writes both fields
     together so ranking never refines on a number nobody has revisited.
     """
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            need = cast("dict[str, object]", raw)
-            need["importance"] = level
-            need["importance_set_at"] = when
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+
+    def _mutate(need: dict[str, object], _path: Path) -> None:
+        need["importance"] = level
+        need["importance_set_at"] = when
+
+    return _edit_one_need(
+        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
+    )
 
 
 def capture_source(
@@ -423,10 +524,6 @@ def capture_source(
     next load) — whose signal it is, orthogonal to the evidence tier (#52 follow-up).
     """
     kind = _canonical_kind(kind)
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
     source: dict[str, object] = {"kind": kind}
     for key, value in (
         ("who", who),
@@ -438,17 +535,18 @@ def capture_source(
     ):
         if value is not None:
             source[key] = value
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            need = cast("dict[str, object]", raw)
-            current = need.get("sources", [])
-            if not isinstance(current, list):
-                raise WriteError(f"{path.name}: 'sources' is not a list")
-            sources = cast("list[object]", current)
-            sources.append(source)
-            need["sources"] = sources
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+
+    def _mutate(need: dict[str, object], path: Path) -> None:
+        current = need.get("sources", [])
+        if not isinstance(current, list):
+            raise WriteError(f"{path.name}: 'sources' is not a list")
+        sources = cast("list[object]", current)
+        sources.append(source)
+        need["sources"] = sources
+
+    return _edit_one_need(
+        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
+    )
 
 
 def attest(
@@ -475,15 +573,13 @@ def attest(
         att["verdict"] = verdict
     if comment is not None:
         att["comment"] = comment
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            cast("dict[str, object]", raw)["attestation"] = att
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+    return _edit_one_need(
+        config,
+        need_id,
+        expect_sha=expect_sha,
+        dry_run=dry_run,
+        mutate=lambda need, _path: need.__setitem__("attestation", att),
+    )
 
 
 def withdraw(
@@ -515,15 +611,13 @@ def withdraw(
         mark["principle"] = principle
     if of is not None:
         mark["of"] = of
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            cast("dict[str, object]", raw)["withdrawn"] = mark
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+    return _edit_one_need(
+        config,
+        need_id,
+        expect_sha=expect_sha,
+        dry_run=dry_run,
+        mutate=lambda need, _path: need.__setitem__("withdrawn", mark),
+    )
 
 
 def reinstate(config: Config, need_id: str, *, expect_sha: str | None, dry_run: bool) -> Edit:
@@ -532,18 +626,15 @@ def reinstate(config: Config, need_id: str, *, expect_sha: str | None, dry_run:
     Errors if the need is not currently withdrawn — reinstating a live need is a mistake worth
     surfacing, not a silent no-op.
     """
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            need = cast("dict[str, object]", raw)
-            if "withdrawn" not in need:
-                raise WriteError(f"need {need_id!r} is not withdrawn")
-            del need["withdrawn"]
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+
+    def _mutate(need: dict[str, object], _path: Path) -> None:
+        if "withdrawn" not in need:
+            raise WriteError(f"need {need_id!r} is not withdrawn")
+        del need["withdrawn"]
+
+    return _edit_one_need(
+        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
+    )
 
 
 def _locate_decision(config: Config, decision_id: str) -> tuple[Path, dict[str, object], str]:
@@ -644,24 +735,19 @@ def accept(
     one-liner instead of a hand edit. Idempotent: re-accepting the same who/date is a no-op.
     """
     locator = f"accept:{who}@{date}"
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            need = cast("dict[str, object]", raw)
-            current = need.get("proofs", [])
-            if not isinstance(current, list):
-                raise WriteError(f"{path.name}: 'proofs' is not a list")
-            proofs = [p for p in cast("list[object]", current)]
-            if revoke:
-                proofs = [p for p in proofs if p != locator]
-            elif locator not in proofs:
+
+    def _mutate(need: dict[str, object], path: Path) -> None:
+        proofs = _proof_list(need, path)
+        if revoke:
+            need["proofs"] = [p for p in proofs if p != locator]
+        else:
+            if locator not in proofs:
                 proofs.append(locator)
             need["proofs"] = proofs
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+
+    return _edit_one_need(
+        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
+    )
 
 
 def add_proof(
@@ -673,22 +759,15 @@ def add_proof(
     batch apply can call it per need and show each need's diff. Re-adding a locator already on the
     need is a no-op, so applying the same suggestion twice does not duplicate it (#54).
     """
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            need = cast("dict[str, object]", raw)
-            current = need.get("proofs", [])
-            if not isinstance(current, list):
-                raise WriteError(f"{path.name}: 'proofs' is not a list")
-            proofs = list(cast("list[object]", current))
-            if locator not in proofs:
-                proofs.append(locator)
-            need["proofs"] = proofs
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+    def _mutate(need: dict[str, object], path: Path) -> None:
+        proofs = _proof_list(need, path)
+        if locator not in proofs:
+            proofs.append(locator)
+        need["proofs"] = proofs
+
+    return _edit_one_need(
+        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
+    )
 
 
 def relink_proof(
@@ -708,27 +787,20 @@ def relink_proof(
     old locator is not actually on the need. One reload-gated single-file splice, like
     :func:`add_proof`.
     """
-    path, _ = _locate(config, need_id)
-    doc, old_text = _read_doc(path)
-    if expect_sha is not None and _sha256(old_text) != expect_sha:
-        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
-    for raw in _need_list(doc, path):
-        if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
-            need = cast("dict[str, object]", raw)
-            current = need.get("proofs", [])
-            if not isinstance(current, list):
-                raise WriteError(f"{path.name}: 'proofs' is not a list")
-            proofs = list(cast("list[object]", current))
-            if old_locator not in proofs:
-                raise WriteError(f"{old_locator!r} is not a proof on {need_id!r}")
-            swapped = [new_locator if p == old_locator else p for p in proofs]
-            deduped: list[object] = []
-            for p in swapped:
-                if p not in deduped:
-                    deduped.append(p)
-            need["proofs"] = deduped
-            break
-    return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
+    def _mutate(need: dict[str, object], path: Path) -> None:
+        proofs = _proof_list(need, path)
+        if old_locator not in proofs:
+            raise WriteError(f"{old_locator!r} is not a proof on {need_id!r}")
+        swapped = [new_locator if p == old_locator else p for p in proofs]
+        deduped: list[object] = []
+        for p in swapped:
+            if p not in deduped:
+                deduped.append(p)
+        need["proofs"] = deduped
+
+    return _edit_one_need(
+        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
+    )
 
 
 def add_need(
@@ -748,7 +820,8 @@ def add_need(
     An agent-authored need must carry a source — and never ``primary``, which only a real user
     signal earns. ``kind`` is restricted to ``assumption`` (the agent's own guess) or ``secondary``
     (citing an existing document). A ``draft`` need is staged: it loads but is kept off the counted
-    board until promoted (#60).
+    board until promoted (#60). The need is appended with the comment-preserving splice (#85), so
+    existing needs and their comments stay byte-for-byte; a brand-new file is dumped fresh.
     """
     kind = _SOURCE_KIND_ALIASES.get(kind, kind)
     if kind not in ("assumption", "secondary"):
@@ -778,7 +851,8 @@ def add_need(
         new_need["draft"] = True
         new_need["draft_added"] = today  # stamped so a lint age-gate can fire later (#60)
     needs.append(new_need)
-    return _validated(config, target, old_text, _dump(doc), dry_run)
+    new_text = _render_item_append(old_text, doc, "needs", need_id)
+    return _validated(config, target, old_text, new_text, dry_run)
 
 
 def add_role(
@@ -793,9 +867,9 @@ def add_role(
     """Declare a new Role in ``file``'s top-level ``roles:`` list (#52 follow-up).
 
     The dedicated write-back for a role, so a roster entry is a one-liner instead of a hand
-    edit. Like :func:`add_need`, a new/edited file is re-dumped whole (comments in that file are
-    not preserved — use `set` on an existing need for a comment-safe splice); the reload gate
-    still rejects anything that does not load. A duplicate role id is refused.
+    edit. Like :func:`add_need`, the new role is appended with the comment-preserving splice (#85),
+    so an existing file's comments stay byte-for-byte and only a brand-new file is dumped fresh;
+    the reload gate still rejects anything that does not load. A duplicate role id is refused.
     """
     target = config.root / file
     if target.exists():
@@ -813,7 +887,8 @@ def add_role(
     ):
         raise WriteError(f"role {role_id!r} already exists in {target.name}")
     roles.append({"id": role_id, "text": text})
-    return _validated(config, target, old_text, _dump(doc), dry_run)
+    new_text = _render_item_append(old_text, doc, "roles", role_id)
+    return _validated(config, target, old_text, new_text, dry_run)
 
 
 def _source_dict(s: Source) -> dict[str, object]:
@@ -845,9 +920,9 @@ def add_principle(
 ) -> Edit:
     """Declare a new Principle in ``file``'s top-level ``principles:`` list, stamped ``revised_at``.
 
-    Mirrors :func:`add_role`: a new/edited file is re-dumped whole, the reload gate rejects
-    anything that does not load (including an id already declared in another file), and a
-    duplicate id in this file is refused. ``revised_at`` is stamped at creation so the first
+    Mirrors :func:`add_role`: the new principle is appended with the comment-preserving splice (#85),
+    the reload gate rejects anything that does not load (including an id already declared in another
+    file), and a duplicate id in this file is refused. ``revised_at`` is stamped at creation so the first
     revision has something to ripple against. ``sources`` carry the provenance that surfaced the
     principle — the signals (often a client) a ``--from-need`` promotion copies across, so the
     discovery history stays honest: the principle was discovered, not decreed.
@@ -872,7 +947,8 @@ def add_principle(
     if sources:
         entry["sources"] = [_source_dict(s) for s in sources]
     principles.append(entry)
-    return _validated(config, target, old_text, _dump(doc), dry_run)
+    new_text = _render_item_append(old_text, doc, "principles", principle_id)
+    return _validated(config, target, old_text, new_text, dry_run)
 
 
 def _locate_principle(config: Config, principle_id: str) -> tuple[Path, dict[str, object], str]:
@@ -934,7 +1010,7 @@ def add_decision(
 ) -> Edit:
     """Declare a new Decision (the solution chosen for ``needs``) in ``file``'s ``decisions:`` list.
 
-    Mirrors :func:`add_principle` (whole-file re-dump, reload-gated, duplicate id refused). ``needs``
+    Mirrors :func:`add_principle` (comment-preserving append #85, reload-gated, duplicate id refused). ``needs``
     is required — the loader rejects a decision that serves none, and the reload gate rejects an id
     that is not a known need. Empty optional lists are omitted so the written block stays clean.
     """
@@ -965,7 +1041,8 @@ def add_decision(
     if draft:
         entry["draft"] = True
     decisions.append(entry)
-    return _validated(config, target, old_text, _dump(doc), dry_run)
+    new_text = _render_item_append(old_text, doc, "decisions", decision_id)
+    return _validated(config, target, old_text, new_text, dry_run)
 
 
 def _snapshot(paths: list[Path]) -> dict[Path, str | None]:

{prodc-0.4.0 → prodc-0.4.2}/tests/test_loader.py

@@ -109,6 +109,26 @@ def test_flow_with_proofs_raises(tmp_path: Path) -> None:
         load_needs(cfg)
 
 
+def test_children_load_as_bare_id_or_stepped_mapping(tmp_path: Path) -> None:
+    # #90: a flow's children take either a bare id (unstepped) or a {id, step} mapping, mixed.
+    cfg = _config(
+        tmp_path,
+        (
+            "a.yaml",
+            "needs:\n"
+            "  - id: F-1\n"
+            "    text: a flow\n"
+            "    children:\n"
+            "      - C-1\n"
+            "      - {id: C-2, step: execute}\n"
+            "  - id: C-1\n    text: one\n"
+            "  - id: C-2\n    text: two\n",
+        ),
+    )
+    flow = next(n for n in load_needs(cfg) if n.id == "F-1")
+    assert [(c.id, c.step) for c in flow.children] == [("C-1", None), ("C-2", "execute")]
+
+
 def test_variant_scope_shared_baseline_across_clients(tmp_path: Path) -> None:
     cfg = _config(
         tmp_path,
@@ -366,3 +386,24 @@ def test_seam_only_on_flows(tmp_path: Path) -> None:
     cfg = _config(tmp_path, ("a.yaml", "needs:\n  - id: N-1\n    text: t\n    seam: [web:x#y]\n"))
     with pytest.raises(LoaderError, match="'seam' is for a flow"):
         load_needs(cfg)
+
+
+def test_unquoted_colon_in_claim_names_the_need_and_the_fix(tmp_path: Path) -> None:
+    # #84: a ': ' in an unquoted prose claim must give a field-level error, not a raw YAML trace.
+    cfg = _config(
+        tmp_path,
+        (
+            "a.yaml",
+            "needs:\n"
+            "  - id: N-5\n"
+            "    text: original\n"
+            "    claim: clear BOTH conditions with margin: (1) a and (2) b\n",
+        ),
+    )
+    with pytest.raises(LoaderError) as exc:
+        load_needs(cfg)
+    msg = str(exc.value)
+    assert "a.yaml" in msg
+    assert "N-5" in msg  # the offending need, not just a line/column
+    assert "line 4" in msg
+    assert "quote the value" in msg  # the actionable hint

{prodc-0.4.0 → prodc-0.4.2}/tests/test_models.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass, replace
 from musil import Action, Model, check, explore, reaches
 
 from prodc.adapters import Adapter, ProofResult
-from prodc.model import Decision, Need, NeedState, ProofState, Withdrawal, board_needs
+from prodc.model import Child, Decision, Need, NeedState, ProofState, Withdrawal, board_needs
 from prodc.status import Resolver, active_decisions
 
 
@@ -141,7 +141,7 @@ def flow_state(f: Flow) -> NeedState:
     """The NeedState prodc's real aggregate gives this set of children + seam."""
     children = [_child_need(f"c{i}", s) for i, s in enumerate(f.children)]
     seam = tuple(f"stub:{s}" for s in f.seam if s != "none")
-    flow = Need(id="flow", text="f", children=tuple(c.id for c in children), seam=seam)
+    flow = Need(id="flow", text="f", children=tuple(Child(c.id) for c in children), seam=seam)
     return Resolver([flow, *children], _ADAPTERS).resolve("flow").state
 
 

{prodc-0.4.0 → prodc-0.4.2}/tests/test_status.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from prodc.adapters import FrontmatterAdapter, ProofResult, SourceAdapter
-from prodc.model import Need, NeedState, ProofState, Source, SourceKind
+from prodc.model import Child, Need, NeedState, ProofState, Source, SourceKind
 from prodc.status import resolve
 
 
@@ -52,7 +52,7 @@ def test_flow_aggregates_two_of_three() -> None:
         Need(id="C-2", text="two", proofs=("web:2",)),
         Need(id="C-3", text="three", proofs=()),  # a HOLE
     )
-    flow = Need(id="F-1", text="a flow", children=("C-1", "C-2", "C-3"))
+    flow = Need(id="F-1", text="a flow", children=(Child("C-1"), Child("C-2"), Child("C-3")))
     results = {r.need.id: r for r in resolve([flow, *children], {"web": _delivered()})}
     flow_result = results["F-1"]
     assert flow_result.state is NeedState.PENDING  # not all delivered → pending
@@ -234,7 +234,7 @@ def test_coverage_counts_leaves_not_flow_parents() -> None:
     from prodc.status import summarize
 
     needs = [
-        Need(id="F-1", text="roast day flow", children=("L-1", "L-2")),
+        Need(id="F-1", text="roast day flow", children=(Child("L-1"), Child("L-2"))),
         Need(id="L-1", text="step one", proofs=("x:1",)),
         Need(id="L-2", text="step two", proofs=("x:1",)),
     ]
@@ -296,7 +296,7 @@ def test_flow_orphan_warning() -> None:
     from prodc.status import flow_orphan_warnings
 
     needs = [
-        Need(id="F-1", text="a flow", children=("L-1",)),
+        Need(id="F-1", text="a flow", children=(Child("L-1"),)),
         Need(id="L-1", text="in the flow"),
         Need(id="L-2", text="in no flow"),
     ]
@@ -354,7 +354,7 @@ def test_flow_seam_proof_gates_delivered() -> None:
     # all children delivered but the seam proof pending → flow is PENDING, not DELIVERED (#44)
     from prodc.adapters import Adapter
 
-    flow = Need(id="F-1", text="roast day", children=("L-1", "L-2"), seam=("web:seam#E2E",))
+    flow = Need(id="F-1", text="roast day", children=(Child("L-1"), Child("L-2")), seam=("web:seam#E2E",))
     children = [
         Need(id="L-1", text="a", proofs=("x:1",)),
         Need(id="L-2", text="b", proofs=("x:1",)),
@@ -368,14 +368,14 @@ def test_flow_seam_proof_gates_delivered() -> None:
 
 
 def test_flow_seam_green_delivers() -> None:
-    flow = Need(id="F-1", text="roast day", children=("L-1",), seam=("web:seam#E2E",))
+    flow = Need(id="F-1", text="roast day", children=(Child("L-1"),), seam=("web:seam#E2E",))
     child = Need(id="L-1", text="a", proofs=("x:1",))
     by_id = {r.need.id: r for r in resolve([flow, child], {"x": _delivered(), "web": _delivered()})}
     assert by_id["F-1"].state is NeedState.DELIVERED
 
 
 def test_flow_seam_broken_breaks_flow() -> None:
-    flow = Need(id="F-1", text="roast day", children=("L-1",), seam=("nope:x",))
+    flow = Need(id="F-1", text="roast day", children=(Child("L-1"),), seam=("nope:x",))
     child = Need(id="L-1", text="a", proofs=("x:1",))
     by_id = {r.need.id: r for r in resolve([flow, child], {"x": _delivered()})}
     assert by_id["F-1"].state is NeedState.BROKEN  # no 'nope' adapter → seam BROKEN

{prodc-0.4.0 → prodc-0.4.2}/tests/test_writer.py

@@ -275,6 +275,33 @@ def test_delete_need_removes_the_block_keeping_others(tmp_path: Path) -> None:
     assert "# keep me" in text  # header comment survives the splice
 
 
+def test_children_append_stepped_edge(tmp_path: Path) -> None:
+    # #90: `children+=id@step` appends a {id, step} edge; a bare id stays a plain string.
+    body = (
+        "needs:\n"
+        "  - id: F-1\n    text: a flow\n    children: [N-2]\n"
+        "  - id: N-2\n    text: step two\n    proofs: ['x:1']\n"
+        "  - id: N-3\n    text: step three\n    proofs: ['x:2']\n"
+    )
+    cfg = _proj(tmp_path, body)
+    set_field(cfg, "F-1", "children+=N-3@conclude", expect_sha=None, dry_run=False)
+    flow = next(n for n in load(cfg).needs if n.id == "F-1")
+    assert [(c.id, c.step) for c in flow.children] == [("N-2", None), ("N-3", "conclude")]
+
+
+def test_children_append_bare_id(tmp_path: Path) -> None:
+    body = (
+        "needs:\n"
+        "  - id: F-1\n    text: a flow\n    children: [N-2]\n"
+        "  - id: N-2\n    text: step two\n    proofs: ['x:1']\n"
+        "  - id: N-3\n    text: step three\n    proofs: ['x:2']\n"
+    )
+    cfg = _proj(tmp_path, body)
+    set_field(cfg, "F-1", "children+=N-3", expect_sha=None, dry_run=False)
+    flow = next(n for n in load(cfg).needs if n.id == "F-1")
+    assert [(c.id, c.step) for c in flow.children] == [("N-2", None), ("N-3", None)]
+
+
 def test_delete_need_unknown_id_rejected(tmp_path: Path) -> None:
     cfg = _proj(tmp_path, "needs:\n  - id: N-1\n    text: t\n")
     with pytest.raises(WriteError, match="no need 'N-9'"):

{prodc-0.4.0 → prodc-0.4.2}/tests/test_writer_comments.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from prodc.config import Config
-from prodc.writer import accept, capture_source, set_field
+from prodc.writer import accept, add_need, capture_source, set_field
 
 _TOML = """
 [prodc]
@@ -111,3 +111,48 @@ def test_inline_list_file_falls_back_but_still_edits(tmp_path: Path) -> None:
     set_field(cfg, "N-1", "text=edited via fallback", expect_sha=None, dry_run=False)
     out = _read(tmp_path)
     assert "edited via fallback" in out
+
+
+def test_add_appends_and_preserves_comments(tmp_path: Path) -> None:
+    # #85: `add` must splice the new need in, not re-dump the whole file and drop every comment.
+    cfg = _project(tmp_path)
+    add_need(
+        cfg,
+        "N-3",
+        "a freshly added need",
+        who="agent",
+        kind="assumption",
+        file="needs/a.yaml",
+        expect_sha=None,
+        dry_run=False,
+    )
+    out = _read(tmp_path)
+    # every authored comment survives
+    assert "# Provenance contract: interview quotes are VERBATIM" in out
+    assert "# ids are minted in the N-16xx range." in out
+    assert "# this comment introduces the second need" in out
+    # the existing needs are untouched and the 2-space item indent is matched, not reflowed
+    assert "  - id: N-1\n" in out
+    assert "    text: second need stays untouched" in out
+    assert "  - id: N-3\n" in out
+    assert "a freshly added need" in out
+    # the new need lands after N-2, not before it
+    assert out.index("id: N-3") > out.index("id: N-2")
+
+
+def test_add_into_new_file_dumps_fresh(tmp_path: Path) -> None:
+    # No existing list to append to: fall back to a whole-file dump, which must still load.
+    cfg = _project(tmp_path)
+    add_need(
+        cfg,
+        "N-9",
+        "a need in a brand-new file",
+        who="agent",
+        kind="assumption",
+        file="needs/b.yaml",
+        expect_sha=None,
+        dry_run=False,
+    )
+    out = (tmp_path / "needs" / "b.yaml").read_text(encoding="utf-8")
+    assert "id: N-9" in out
+    assert "a need in a brand-new file" in out