Feed back from gramps-testbed-v2: complete iterate carry-forward, Success-criterion mandate, no-id path

Three template-bound deltas still instance-ahead after the v0.9.0 catch-up (issue #7).

1. Complete the iterate carry-forward (was partial: §9 field + record(delta=) only).
   - signoff.iteration_delta(): read the §9 "Iteration delta" back ([ \t]-anchored so
     an empty field can't run past the line).
   - leaves.signoff_decision() now reads the token from line 1; new signoff_rationale()
     reads the human's "why / what to change" written below it.
   - flow._apply_decision flattens that rationale and records it into §9 (delta=).
   - driver._carry_forward_into_brief(): before the iterate clear, append an
     "## Iteration N — carry-forward" block (the §9 rationale + the failing gates,
     gating and advisory) to brief.md, so the rebuild's Do isn't blind. Adapted to the
     template's clear model (no archive dir). signoff.md / builder.md prose to match.

2. Do builds to the brief's Success criterion, not a proxy (#22): _build_prompt +
   builder.md.jinja mandate the real end result, proven red→green — a green mechanical
   check on something adjacent is not "done".

3. First-class "no tracker id yet" path (replaces the magic #0000): publish --no-issue
   (pending_id) relaxes a failing T4 to a flag instead of aborting, records the bundle
   id_pending, and the publisher omits the trailer rather than inventing a placeholder.
   cli/publish/leaves/publisher.md/pdca.toml wired; the trade-off (it relaxes all of T4,
   not just the trailer) is a deliberate flagged escape hatch for human follow-up.

Tests: test_carry_forward.py (decision file token+rationale, §9 delta read-back,
carry-forward block, build-prompt mandate); test_publish_slice no-issue T4 relaxation.
Full suite 64 green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: eduralph

template/.claude/agents/builder.md.jinja

@@ -24,6 +24,15 @@ You implement the contribution the brief specs. Read `brief.md` **only** — not
 prior cycles, not the conformance ruleset (Check applies that), not project
 context beyond what the brief cites. Narrow input is deliberate.
 
+**Build to satisfy the brief's `Success criterion`** — the real end result — not a
+narrower proxy: an item is done only when that end result holds, proven red→green. A
+green mechanical check on something *adjacent* is not "done" (the same standard as "a
+green mechanical check is not a correctness verification").
+
+**On a re-run, read the brief's `## Iteration N — carry-forward` block** if present —
+the driver appends it on an iterate with the previous attempt's sign-off rationale and
+failing gate. Address it; do **not** re-submit the rejected approach unchanged.
+
 ## Output — three files, in lockstep
 
 - `patch.diff` — the change.

template/.claude/agents/publisher.md.jinja

@@ -37,7 +37,10 @@ not push, branch, or open a PR yourself.**
    - reference any other commit by its **full hash**;
    - the **last line** is the issue trailer the project configures
      (`[tracker].issue_trailer`, e.g. `Fixes #<id>`) — the T4 gate enforces it. If you
-     add a `Co-Authored-By:` line, place it **above** the trailer.
+     add a `Co-Authored-By:` line, place it **above** the trailer. **If no tracker id is
+     assigned yet** (the bundle id is not a real tracker number), OMIT the trailer rather
+     than invent a placeholder like `#0000` — `pdca publish --no-issue` relaxes T4 to a
+     flag and records the contribution `id_pending` for the human to fill the id in.
 
 2. **`pr-description.md`** — the PR body (see `templates/pr-description.md.tpl`): the
    sections **Root cause / Fix / Verified against / Test**, citing `path:lines` on the

template/.claude/agents/signoff.md.jinja

@@ -33,16 +33,22 @@ and especially **§6 NEEDS-HUMAN** — the items only a human can clear.
    pointer, not a write-up: a full **process delta** is recorded at the Act beat (in
    the act-log / upstream), not stored in the summary.
 3. Once the human has decided the disposition, write the agreed token — exactly
-   one of `accept`, `iterate-do`, `iterate-plan` — into a file named
-   **`signoff-decision`** in the bundle directory. That is your decision output of record.
+   one of `accept`, `iterate-do`, `iterate-plan` — as the **first line** of a file
+   named **`signoff-decision`** in the bundle directory. That is your decision output
+   of record. **On an `iterate-do` / `iterate-plan`, add the human's rationale on the
+   lines *below* the token** — the *why rejected / what to change next*. The driver
+   folds it into the brief's carry-forward so the next attempt isn't blind; without
+   it, the rebuild reads an unchanged brief and repeats the rejected approach. Keep it
+   to the actionable insight; do not restate the whole review.
 
 ## Boundaries — write exactly three things, reset nothing
 
 **You write exactly three things, nothing else:** (a) `- [ ]` → `- [x]` in §6 of
 `SUMMARY.md`, only with the human's explicit OK; (b) **append-only** bullets under
 **§10 Act candidates** of `SUMMARY.md`, dictated by the human (append a new line —
-never edit or delete an existing §10 line); and (c) the `signoff-decision` token
-file. That is the complete list. §10 is the one append channel you have because it
+never edit or delete an existing §10 line); and (c) the `signoff-decision` file (the
+token on line 1, plus the iterate rationale on the lines below it). That is the
+complete list. §10 is the one append channel you have because it
 is non-binding "hints for the next Act review" and has no effect on disposition;
 everything that *is* the decision record stays off-limits. **Never delete or modify
 any other part of any bundle file** — not `SUMMARY.md` §9 / §1–§8, not `patch.diff`,

template/pdca.toml.jinja

@@ -20,6 +20,8 @@ issue_id_example = "{{ issue_id_example }}"
 # Trailer linking a commit/PR to the issue ({id} = the bug id). Trackers differ
 # (GitHub/Mantis "Fixes #{id}", Jira "Fixes PROJ-{id}"); "" enforces none. The
 # publish step's commit-msg ends with this; the T4 gate (if any) checks it.
+# No tracker id yet? Use `pdca publish --no-issue`: it omits the trailer, relaxes
+# T4 to a flag, and records the bundle `id_pending` (no magic "#0000" placeholder).
 issue_trailer = "Fixes #{id}"
 # Optional default tracker export the Plan leaf reads the issue row from when `flow`
 # runs without --from-csv (it reads ONLY that issue's row, not a repo scan):

template/src/pdca_harness/cli.py

@@ -83,6 +83,8 @@ def main(argv: list[str] | None = None) -> int:
     p_publish.add_argument("issue_id")
     p_publish.add_argument("--dry-run", action="store_true", help="print the git/gh commands without running them")
     p_publish.add_argument("--no-pr", action="store_true", help="push the branch but don't open the draft PR")
+    p_publish.add_argument("--no-issue", action="store_true",
+                           help="no tracker id yet: relax T4 to a flag, record id_pending (vs a magic #0000)")
     p_publish.add_argument("--by", default="", help="who published (recorded in publish.json)")
 
     args = parser.parse_args(argv)
@@ -110,7 +112,7 @@ def main(argv: list[str] | None = None) -> int:
         return _signoff(cfg, args)
     if args.cmd == "publish":
         return publish.publish(cfg, args.issue_id, dry_run=args.dry_run,
-                               open_pr=not args.no_pr, by=args.by)
+                               open_pr=not args.no_pr, by=args.by, pending_id=args.no_issue)
     return 2
 
 

template/src/pdca_harness/driver.py

@@ -10,10 +10,11 @@
 
 from __future__ import annotations
 
+import json
 import sys
 from pathlib import Path
 
-from . import assemble, brief, gates, leaves, state
+from . import assemble, brief, gates, leaves, signoff, state
 from .config import Config
 
 
@@ -52,9 +53,11 @@ def advance(d: Path, cfg: Config) -> None:
         assemble.assemble_summary(d, cfg)  # pure code → SUMMARY.md §1–8
     elif s == state.ITERATE_DO:
         _say(f"→ {d.name}: iterate-to-Do — clearing downstream, rebuilding…")
-        _clear_downstream_of_brief(d)  # re-run Do against the same brief
+        _carry_forward_into_brief(d)  # persist the WHY before the clear wipes it
+        _clear_downstream_of_brief(d)  # re-run Do against the (now annotated) brief
     elif s == state.ITERATE_PLAN:
         _say(f"→ {d.name}: iterate-to-Plan — versioning brief…")
+        _carry_forward_into_brief(d)  # annotate the brief before it is versioned
         _version_brief_and_clear(d)  # preserve brief.vN.md; human re-authors
     # UNPLANNED / AWAITING_SIGNOFF / COMPLETE: nothing for the driver to do.
 
@@ -97,3 +100,57 @@ def _next_brief_version(d: Path) -> int:
     existing = [p.stem for p in d.glob("brief.v*.md")]
     nums = [int(s.split("brief.v")[1]) for s in existing if s.split("brief.v")[1].isdigit()]
     return (max(nums) + 1) if nums else 1
+
+
+# ----------------------------------------------------------------------------
+# Iterate carry-forward — persist the WHY into the one input the next beat reads.
+# ----------------------------------------------------------------------------
+def _carry_forward_into_brief(d: Path) -> None:
+    """Fold the previous iteration's insight into ``brief.md`` BEFORE the clear wipes
+    SUMMARY/check-*, so the next attempt isn't blind. On iterate-do the annotated
+    brief stays in place (the rebuild reads it); on iterate-plan it is versioned to
+    ``brief.vN.md`` with the re-authoring context attached.
+
+    Captures whatever is available — the §9 sign-off rationale AND the failing gates
+    (gating *and* advisory, since an iterate is often driven by an advisory red), so
+    an iterate with no recorded rationale still carries context. Best-effort: it must
+    never break the transition, so any failure is swallowed.
+    """
+    brief_path = d / "brief.md"
+    if not brief_path.exists():
+        return
+    try:
+        delta = signoff.iteration_delta(d / "SUMMARY.md")
+        fails = _failing_gate_lines(d / "check-gates.json")
+        if not delta and not fails:
+            return
+        n = brief_path.read_text(encoding="utf-8").count("## Iteration ") + 1
+        out = [f"\n## Iteration {n} — carry-forward (from the previous attempt)\n"]
+        if delta:
+            out.append(f"- Sign-off rationale: {delta}\n")
+        for f in fails:
+            out.append(f"- Failing gate: {f}\n")
+        out.append("- Address the above; do NOT re-attempt the rejected approach "
+                   "unchanged. Satisfy the brief's Success criterion (the end result).\n")
+        with brief_path.open("a", encoding="utf-8") as fh:
+            fh.write("".join(out))
+    except Exception:  # noqa: BLE001 — carry-forward is advisory; never break the iterate
+        pass
+
+
+def _failing_gate_lines(gates_json: Path) -> list[str]:
+    """``"check — evidence"`` for each failing row in ``check-gates.json`` — gating AND
+    advisory, since an iterate is often driven by an advisory red. Best-effort."""
+    if not gates_json.exists():
+        return []
+    try:
+        data = json.loads(gates_json.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return []
+    out: list[str] = []
+    for r in data.get("rows", []):
+        if r.get("result") == "fail":
+            ev = r.get("path_line") or r.get("oracle") or ""
+            tag = "" if r.get("gating") else " (advisory)"
+            out.append(f"{r.get('check', '?')}{tag} — {ev}".strip(" —"))
+    return out

template/src/pdca_harness/flow.py

@@ -96,7 +96,12 @@ def _apply_decision(
     if action == "accept" and signoff.open_needs_human(d / "SUMMARY.md"):
         print(f"flow: {d.name} — cannot accept, §6 NEEDS-HUMAN still open (C6)", file=sys.stderr)
         return "blocked"
-    signoff.record(d / "SUMMARY.md", action=action, by=by or cfg.author or "unknown", date=today)
+    # The iterate rationale ("why rejected / what to change") rides §9 → the driver
+    # folds it into the brief's carry-forward so the next iteration isn't blind.
+    # §9's "Iteration delta" is a single line, so flatten a multi-line rationale.
+    rationale = " ".join(leaves.signoff_rationale(d).split())
+    signoff.record(d / "SUMMARY.md", action=action, by=by or cfg.author or "unknown",
+                   date=today, delta=rationale)
     (d / leaves.SIGNOFF_DECISION).unlink(missing_ok=True)
     if apply_now:
         driver.run_issue(d, cfg)  # apply the transition: COMPLETE | ITERATE_* → re-loop

template/src/pdca_harness/leaves.py

@@ -227,7 +227,12 @@ def do_build(d: Path, cfg: Config) -> None:
 
 def _build_prompt(d: Path) -> str:
     return (
-        f"You are the Do builder. Read {d}/brief.md. Produce, in the bundle directory "
+        f"You are the Do builder. Read {d}/brief.md. Build to satisfy its **Success "
+        "criterion** (the real end result), not a narrower proxy — an item is done only "
+        "when that end result holds, proven red→green; a green mechanical check on "
+        "something adjacent is not done. If brief.md carries an '## Iteration N — "
+        "carry-forward' block, address it (the previous attempt's rationale + failing "
+        "gate) and do NOT repeat the rejected approach. Produce, in the bundle directory "
         f"{d}: (1) patch.diff — a unified diff against the brief's target branch; "
         "(2) the test file the brief names, red before the fix and green after; "
         "(3) build-notes.md — your rationale (withheld from the reviewer). Cite "
@@ -455,14 +460,31 @@ def _signoff_batch_prompt(bundles: list[Path]) -> str:
 
 
 def signoff_decision(d: Path) -> str:
-    """The token the sign-off leaf wrote, or "" if absent/invalid."""
+    """The decision token (first line of ``signoff-decision``), or "" if absent/invalid.
+
+    The file is ``<token>`` optionally followed by a free-text **rationale** on the
+    remaining lines (read by :func:`signoff_rationale`) — the human's "why iterate /
+    what to change" the driver carries forward into the brief on an iterate."""
     p = d / SIGNOFF_DECISION
     if not p.exists():
         return ""
-    token = p.read_text(encoding="utf-8").strip()
+    lines = p.read_text(encoding="utf-8").splitlines()
+    token = lines[0].strip() if lines else ""
     return token if token in VALID_DECISIONS else ""
 
 
+def signoff_rationale(d: Path) -> str:
+    """The iterate rationale the sign-off leaf wrote below the token, or "" if none.
+
+    Lines after the first of ``signoff-decision`` — the actionable insight ("why this
+    Do attempt was rejected / what to change next") that the flow records into §9 and
+    the driver folds into the brief's carry-forward so the next iteration isn't blind."""
+    p = d / SIGNOFF_DECISION
+    if not p.exists():
+        return ""
+    return "\n".join(p.read_text(encoding="utf-8").splitlines()[1:]).strip()
+
+
 # ----------------------------------------------------------------------------
 # Leaf 4 — Act (act, interactive): review frozen cycles, suggest deltas if sensible.
 # ----------------------------------------------------------------------------
@@ -511,7 +533,11 @@ def _publish_prompt(d: Path, cfg: Config) -> str:
     trailer = cfg.issue_trailer.format(id=issue_id) if cfg.issue_trailer else ""
     trailer_line = (
         f"The LAST line of commit-msg.txt is the issue trailer `{trailer}` (the T4 gate "
-        "enforces it); a Co-Authored-By line, if any, goes ABOVE it. " if trailer else ""
+        "enforces it); a Co-Authored-By line, if any, goes ABOVE it. If no tracker id is "
+        "assigned yet (the bundle id is not a real tracker number), OMIT the trailer "
+        "entirely rather than invent a placeholder — `pdca publish --no-issue` records "
+        "the contribution as id_pending for the human to fill the id in later. "
+        if trailer else ""
     )
     return (
         "You are the Publish leaf — the closing work of Check. The fix for issue "

template/src/pdca_harness/publish.py

@@ -47,12 +47,20 @@ def publish(
     by: str = "",
     today: str | None = None,
     skip_if_no_target: bool = False,
+    pending_id: bool = False,
 ) -> int:
     """Contribute an accepted bundle's fix as a draft PR. Return a process code.
 
     ``skip_if_no_target`` (set by the flow): a bundle whose brief names no upstream
     ``Repo + branch target`` is a non-contributing cycle (e.g. an internal fix) —
     warn and return 0 rather than erroring, so it doesn't fail the continuous flow.
+
+    ``pending_id`` (``--no-issue``): the first-class "no tracker id yet" path. A
+    project may need to contribute before a tracker number is assigned; rather than a
+    magic ``Fixes #0000`` placeholder, declare it here. The T4 contribution gate is
+    then **relaxed to a flag** instead of a hard block, and the bundle is recorded
+    ``id_pending`` so the human adds the real id and re-gates T4 before marking the PR
+    ready. The publisher leaf omits the trailer (no invented id) in this case.
     """
     d = cfg.bundle(issue_id)
     today = today or datetime.date.today().isoformat()
@@ -84,11 +92,20 @@ def publish(
         print(f"publish: {COMMIT_MSG} / {PR_BODY} still missing — aborting", file=sys.stderr)
         return 1
 
-    # T4 contribution gate — the artifacts MUST pass before anything is pushed.
+    # T4 contribution gate — the artifacts MUST pass before anything is pushed,
+    # UNLESS pending_id (--no-issue): then a T4 failure is relaxed to a flag, since the
+    # one thing legitimately missing is the not-yet-assigned tracker id. The bundle is
+    # recorded id_pending so the human adds the id and re-gates T4 before ready.
     if not _t4_passes(cfg, d):
-        print(f"publish: T4 contribution gate FAILED on {COMMIT_MSG} / {PR_BODY} — "
-              "fix them and retry", file=sys.stderr)
-        return 1
+        if pending_id:
+            print(f"publish: T4 contribution gate not satisfied on {COMMIT_MSG} / "
+                  f"{PR_BODY} — proceeding in --no-issue (pending-id) mode; the "
+                  "contribution is FLAGGED. Add the tracker id and re-run T4 before "
+                  "marking the PR ready.", file=sys.stderr)
+        else:
+            print(f"publish: T4 contribution gate FAILED on {COMMIT_MSG} / {PR_BODY} — "
+                  "fix them and retry", file=sys.stderr)
+            return 1
 
     branch = _branch_name(cfg, d, slug)
     summary_line = (d / COMMIT_MSG).read_text(encoding="utf-8").splitlines()[0]
@@ -155,6 +172,7 @@ def publish(
     (d / "publish.json").write_text(json.dumps({
         "branch": branch, "pr_url": pr_url, "base": base, "repo": repo_spec,
         "by": by or _signoff_by(d) or cfg.author or "unknown", "date": today,
+        "id_pending": pending_id,
     }, indent=2) + "\n", encoding="utf-8")
 
     # A requested-but-failed PR is a partial run, not a success — the branch is
@@ -166,6 +184,9 @@ def publish(
     print(f"\nDraft PR prepared on {repo_spec} ({branch} → {base}).")
     if pr_url:
         print(f"  {pr_url}\n  watch CI:  gh pr checks {pr_url} --watch")
+    if pending_id:
+        print("  ⚠ id_pending: contributed without a tracker id — add the trailer "
+              "(Fixes #N) and re-run T4 before marking the PR ready.")
     print("  STOP: review CI, then mark it ready / merge yourself — the human's step.")
     return 0
 

template/src/pdca_harness/signoff.py

@@ -24,6 +24,9 @@
 }
 
 _OUTCOME_RE = re.compile(r"^- Outcome:\s*(.*?)\s*$", re.MULTILINE)
+# Anchored with [ \t] (NOT \s) so an empty field stops at the line end instead of
+# running past the newline into the next line.
+_DELTA_RE = re.compile(r"^- Iteration delta \(if iterating\):[ \t]*(.*?)[ \t]*$", re.MULTILINE)
 
 
 def outcome_token(summary_path: Path) -> str:
@@ -47,6 +50,18 @@ def is_set(summary_path: Path) -> bool:
     return outcome_token(summary_path) in VALID_OUTCOMES
 
 
+def iteration_delta(summary_path: Path) -> str:
+    """The §9 'Iteration delta (if iterating)' value, or "" if unset/absent.
+
+    The human's rationale for an iterate ("why rejected / what to change"), which the
+    driver folds into the brief's carry-forward so the next iteration isn't blind."""
+    if not summary_path.exists():
+        return ""
+    section = _section(summary_path.read_text(encoding="utf-8"), "9. Check sign-off")
+    m = _DELTA_RE.search(section)
+    return (m.group(1).strip() if m else "")
+
+
 def open_needs_human(summary_path: Path) -> list[str]:
     """Unchecked ``- [ ]`` items under §6 NEEDS-HUMAN (must be empty before accept)."""
     section = _section(summary_path.read_text(encoding="utf-8"), "6. NEEDS-HUMAN")