napkinstack 0.16.0__tar.gz → 0.18.0__tar.gz

{napkinstack-0.16.0 → napkinstack-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.16.0
+Version: 0.18.0
 Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
 License-Expression: MIT
 License-File: LICENSE
@@ -20,7 +20,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.16.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.18.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -84,8 +84,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.16.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.16.0"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.18.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.18.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -111,7 +111,7 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
 | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
-| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures |
+| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures; then the project across its cycles, and who holds what |
 | `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
 | `nstack pr-scope` | One PR = one module, review budget |
 | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |

{napkinstack-0.16.0 → napkinstack-0.18.0}/README.md

@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.16.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.18.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.16.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.16.0"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.18.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.18.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -96,7 +96,7 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
 | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
-| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures |
+| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures; then the project across its cycles, and who holds what |
 | `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
 | `nstack pr-scope` | One PR = one module, review budget |
 | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |

{napkinstack-0.16.0 → napkinstack-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.16.0"
+version = "0.18.0"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.16.0 → napkinstack-0.18.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.16.0"
+version = "0.18.0"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/attest.py

@@ -46,6 +46,7 @@ class Step:
 class Check:
     name: str  # the CI job's name
     steps: tuple[Step, ...]
+    kept: bool = False  # reads only the tree and the base: a pass on the same commit, base and engine stands (#275)
 
 
 # The project's CI, job by job, as a workstation runs it (skeleton/.github/workflows/). A job or a
@@ -69,7 +70,7 @@ CHECKS: tuple[Check, ...] = (
              'nstack pr-check --root . --base "$NSTACK_BASE" --body-file "$NSTACK_BODY"'),)),
     Check("Module checks", (
         Step("bash .nstack/check-modules.sh", "Every changed module",
-             'BASE="$NSTACK_BASE" bash .nstack/check-modules.sh'),)),
+             'BASE="$NSTACK_BASE" bash .nstack/check-modules.sh'),), kept=True),
 )
 
 
@@ -88,6 +89,23 @@ def capped(text: str) -> str:
             + data[-half:].decode("utf-8", "ignore"))
 
 
+def unplaced(value, root: Path):
+    """What a record keeps, said nowhere on the machine that attested: the checkout's root as
+    `<root>`, the home folder as `~` (#277). The notes are pushed, and public with the repository;
+    a path names a person and their folders. Strings inside lists and mappings too."""
+    if isinstance(value, str):
+        for folder, said in ((root.resolve(), "<root>"), (root.absolute(), "<root>"),
+                             (Path.home().resolve(), "~"), (Path.home(), "~")):
+            if str(folder) not in ("", "/"):  # a whole folder only: never a neighbour, never inside a longer path
+                value = re.sub(r"(?<![\w.-])" + re.escape(str(folder)) + r"(?=$|[/\s'\"`)\]}>:,;])", said, value)
+        return value
+    if isinstance(value, list):
+        return [unplaced(item, root) for item in value]
+    if isinstance(value, dict):
+        return {key: unplaced(item, root) for key, item in value.items()}
+    return value
+
+
 def latest(root: Path, commit: str) -> dict | None:
     """The record of a commit: the latest run its note holds, or None."""
     shown = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False)
@@ -207,7 +225,31 @@ def why(output: str) -> list[str]:
     return said or [line for line in lines if line.strip()][-REASON:]
 
 
-def run(root: Path, base: str, body_file: Path | None, labels: str | None, accept_identity: bool = False) -> int:
+# An engine whose code a string names: published, a forge's commit, or a checkout's own commit.
+NAMED = re.compile(r".* \(commit [0-9a-f]{7,}\)|.*@[0-9a-f]{7,}|a local checkout at (?!an unknown commit)\S+(?<!-dirty)")
+
+
+def _kept(previous: dict | None, check: Check, engine: str, origin: str | None, base_commit: str | None,
+          who: str, said: str | None = None) -> dict | None:
+    """The check as the commit's record last passed it, when what it reads is the same: the commit,
+    the base commit, the engine — published, or one whose commit names its code — and the person who
+    ran it. A sheet filled in between changes the description, which this check never reads (#275).
+    Not compared: what the tree's ignored files, the environment or the tools outside it hold."""
+    said = origin if said is None else said  # the origin as the record wrote it, its paths unplaced (D162)
+    if not check.kept or previous is None or base_commit is None or not (origin is None or NAMED.fullmatch(origin)):
+        return None
+    if (previous.get("engine"), previous.get("origin"), previous.get("published"), previous.get("base_commit"),
+            previous.get("by")) != (engine, said, origin is None, base_commit, who):
+        return None
+    checks = previous.get("checks") if isinstance(previous.get("checks"), list) else []
+    found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
+    if not found or found.get("passed") is not True:
+        return None
+    return {**found, "kept_from": found.get("kept_from") or previous.get("at")}
+
+
+def run(root: Path, base: str, body_file: Path | None, labels: str | None, accept_identity: bool = False,
+        again: bool = False) -> int:
     print(provenance.judged_by(root), flush=True)
     who, address = _identity(root)
     remote = _remote(root)
@@ -233,6 +275,8 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
         return 1
     commit = _git(root, "rev-parse", "HEAD").stdout.strip()
     engine, origin = provenance.engine()
+    base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).stdout.strip() or None
+    previous = None if again else latest(root, commit)
     # The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147).
     env = dict(os.environ, PR_LABELS=os.environ.get("PR_LABELS", "") if labels is None else labels)
     # The engine that runs this command runs the checks: its folder first on the path.
@@ -247,6 +291,12 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
         env.update(NSTACK_BASE=base, NSTACK_BODY=str(Path(body).resolve()), NSTACK_TMP=tmp,
                    NSTACK_ATTESTING=commit)
         for check in CHECKS:
+            kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root))
+            if kept is not None:
+                results.append(kept)
+                print(f"ok   [attest] {check.name}: kept from the record of {kept['kept_from']} — same commit, base "
+                      "and engine (nstack attest --again runs it)", flush=True)
+                continue
             steps = []
             for step in check.steps:
                 done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env,
@@ -263,12 +313,15 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
                     print("\n".join(f"       {line}" for line in why(step["output"])), flush=True)
     record = {"record": RECORD, "commit": commit,
               "at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="microseconds"),
-              "engine": engine, "published": origin is None, "by": who, "session": _session(root, commit),
-              "base": base, "checks": results, "evidence": evidence_of(root, commit)}
+              "engine": engine, "origin": origin, "published": origin is None, "by": who, "session": _session(root, commit),
+              "base": base, "base_commit": base_commit, "checks": results,
+              # The audits of the run the module checks come from: kept with them, never read again (#275).
+              "evidence": (previous.get("evidence") if isinstance(previous.get("evidence"), list) else [])
+              if previous and any(r.get("kept_from") for r in results) else evidence_of(root, commit)}
     remote = fetch(root)
     before = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False)
     lines = (before.stdout.rstrip("\n") + "\n" if before.returncode == 0 and before.stdout.strip() else "")
-    lines += json.dumps(record, separators=(",", ":"), ensure_ascii=False) + "\n"
+    lines += json.dumps(unplaced(record, root), separators=(",", ":"), ensure_ascii=False) + "\n"
     subprocess.run(["git", "notes", f"--ref={NOTES}", "add", "--force", "--file=-", commit], cwd=root,
                    input=lines, text=True, capture_output=True, check=True)
     passed = sum(1 for result in results if result["passed"])

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/board.py

@@ -80,7 +80,7 @@ def desired(root: Path, holders: dict[str, str] | None = None, pulls: dict[str,
     for path in plan.cycle_files(root):
         data = plan.read_front_matter(path)[0]
         found = NUMBER.match(path.stem)
-        if data and data.get("status") in SHOWN and found:
+        if data and plan.one_of(data.get("status"), SHOWN) and found:
             cycles.setdefault(found[1], []).append((path, data))
     said = [f"cycle {number} not shown: {len(files)} cycle files carry its number "
             f"({', '.join(path.name for path, _ in files)})" for number, files in cycles.items() if len(files) > 1]

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/cli.py

@@ -100,8 +100,8 @@ def build_parser() -> argparse.ArgumentParser:
          lambda a: manifests.run(a.root))
     _add(sub, "boundaries", "declared graph against real graph, release artefacts included (B1-B9)",
          lambda a: boundaries.run(a.root))
-    _add(sub, "plan", "the discovery, the charter and the cycles (C1-C8), and who holds what",
-         lambda a: plan.run(a.root) | hold.show(a.root))
+    _add(sub, "plan", "the discovery, the charter and the cycles (C1-C8), the decisions due at a closure "
+         "(C10), the project across its cycles, and who holds what", lambda a: plan.run(a.root) | plan.show(a.root) | hold.show(a.root))
     sk = _add(sub, "skills", "generates or checks the skills (S1-S4)",
               lambda a: skills.run(a.root, check_only=a.check))
     sk.add_argument("--check", action="store_true", help="check without writing")
@@ -175,12 +175,14 @@ def build_parser() -> argparse.ArgumentParser:
     ld.add_argument("--span", default="HEAD~1..HEAD",
                     help="the commits to read, BEFORE..AFTER (default: the last commit)")
     at = _add(sub, "attest", "runs the CI's checks here and records the run on the commit, in git",
-              lambda a: attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity))
+              lambda a: attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity, a.again))
     at.add_argument("--base", default="origin/main")
     at.add_argument("--body-file", type=Path, help="the pull request's description, for its checks")
     at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS)")
     at.add_argument("--accept-identity", action="store_true",
                     help="record under an identity the project's history does not show yet — a first record of yours")
+    at.add_argument("--again", action="store_true",
+                    help="runs every check, even the module checks this commit's record passed with the same base and engine")
     cl = _add(sub, "claim", "takes a ready deliverable for a session, before its first change; "
                             "the shared remote refuses a second taker",
               lambda a: hold.claim(a.root, a.deliverable, a.session, a.person, a.take_over))

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/evidence.py

@@ -9,6 +9,8 @@ version that brings the audit only reports; the project's next minor version jud
 
 from __future__ import annotations
 
+import contextlib
+import datetime
 import json
 import os
 import re
@@ -16,6 +18,7 @@ import select
 import signal
 import subprocess
 import sys
+import tempfile
 import time
 from pathlib import Path
 
@@ -262,6 +265,53 @@ def prepare(root: Path, module: Path) -> Path | str:
     return folder
 
 
+HELD = "NSTACK_E2E_HELD"  # set for what the run starts: an e2e inside an e2e waits for nothing
+
+
+@contextlib.contextmanager
+def one_at_a_time(root: Path, target: str):
+    """One e2e at a time on this machine, for this user, whichever project or command starts it —
+    `nstack e2e`, or `nstack attest` through it: what an end-to-end run drives (a sound server, a
+    display, a port) is the machine's, and two runs reading it see each other's (#287). An advisory
+    lock, `flock(2)`, released by the system when the holder exits however it exits; the one that
+    waits says for whom."""
+    try:
+        import fcntl
+    except ImportError:  # no flock on this system: the runs are not kept apart
+        yield
+        return
+    if os.environ.get(HELD):
+        yield
+        return
+    folder = os.environ.get("XDG_RUNTIME_DIR")
+    path = Path(folder) / "nstack-e2e.lock" if folder else Path(tempfile.gettempdir()) / f"nstack-e2e-{os.getuid()}.lock"
+    try:  # never through a link: in a shared temporary folder, another user could have placed one
+        descriptor = os.open(path, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    except OSError as error:
+        print(f"-> {target}: not kept apart from another end-to-end run: {path} cannot be opened ({error.strerror})",
+              flush=True)
+        yield
+        return
+    with open(descriptor, "r+", encoding="utf-8") as handle:
+        try:
+            fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            handle.seek(0)
+            holder = handle.read().strip() or "another run"
+            print(f"-> {target}: waits for the end-to-end run already on this machine — {holder}", flush=True)
+            fcntl.flock(handle, fcntl.LOCK_EX)
+        handle.seek(0)
+        handle.truncate()
+        started = datetime.datetime.now().astimezone().isoformat(timespec="seconds")
+        handle.write(f"{target}, in {root.resolve()}, process {os.getpid()}, since {started}\n")
+        handle.flush()
+        try:
+            yield
+        finally:
+            handle.seek(0)
+            handle.truncate()
+
+
 def run(command: str, cwd: Path, environment: dict, folder: Path) -> tuple[int, str | None]:
     """The command, its output shown live and kept as it comes, in bytes; the process waited for,
     the pipe drained two seconds after. Returns its exit code, and what still held the pipe."""

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/fitness/plan.py

@@ -12,14 +12,19 @@ Rules:
   C3  cycle: a goal, a known status, appetite_weeks, start and end, end = start + appetite
   C4  deliverables: ids D1, D2… unique, a title, a known state, acceptance criteria once ready
   C5  at most one accepted cycle, and only under an accepted charter
-  C6  a closed or stopped cycle records its outcome and the date it ended
+  C6  a closed or stopped cycle records its outcome and the date it ended, and may record the
+      charter's success criteria it moved: each by its number, met or observing since a day
   C7  discovery: a known decision, its decider and date once decided, a challenger for a go;
       a charter follows a go
   C8  a seat is written when its moment comes: README.md holds its sentence once the
       discovery's decision is go, and none of its form's words once the charter is accepted;
       modules/README.md none of its own once a module holds more than its description
+  C10 (a warning) a closure reads the decisions whose criterion is due: an accepted record of
+      docs/pdr/ or docs/adr/ whose success criterion names a closed or stopped cycle, or a date
+      its end has reached, says so in a reading line (PDR-0020)
 
-Templates, whose file name starts with "_", are not checked.
+Templates, whose file name starts with "_", are not checked. `nstack plan` then says the project
+across its cycles (`project`), a display that never fails.
 
 Usage :  nstack plan [--root ROOT]
 Output:  0 when the charter and the cycles are valid, or absent; 1 otherwise.
@@ -58,6 +63,7 @@ CYCLE_STATUSES = {"proposed", "accepted", "closed", "stopped"}
 DELIVERABLE_STATES = {"proposed", "ready", "in-progress", "accepted", "deferred", "dropped"}
 WITHOUT_CRITERIA = {"proposed", "deferred", "dropped"}  # acceptance criteria not required yet
 OUTCOMES = {"closed": {"completed", "shipped"}, "stopped": {"reframed", "stopped"}}
+SUCCESS_STATES = {"met", "observing"}  # a criterion never recorded is not yet (PDR-0019)
 DELIVERABLE_ID = re.compile(r"D[1-9][0-9]*")
 FRONT_MATTER = re.compile(r"\A---\n(.*?)\n---\n", re.S)
 DECIDER = re.compile(rf"@?{HANDLE}")  # one person, the way GitHub names people
@@ -76,14 +82,21 @@ def check_decider(rule: str, path: Path, value, fail) -> None:
 
 
 def read_front_matter(path: Path) -> tuple[dict | None, str]:
-    """The front matter as a mapping, or None and the reason it cannot be read (C1)."""
-    match = FRONT_MATTER.match(path.read_text(encoding="utf-8"))
+    """The front matter as a mapping, or None and the reason it cannot be read (C1). A file that
+    is not UTF-8, or a date no calendar holds — YAML builds it and Python refuses it — is a reason
+    like the others, never a traceback (#268)."""
+    try:
+        match = FRONT_MATTER.match(path.read_text(encoding="utf-8"))
+    except UnicodeDecodeError as exc:
+        return None, f"not UTF-8 text: {exc.reason} at byte {exc.start}; save the file as UTF-8"
     if not match:
         return None, "no front matter: the file must start with a YAML block between two --- lines"
     try:
         data = yaml.safe_load(match[1])
     except yaml.YAMLError as exc:
         return None, f"front matter unreadable: {exc}"
+    except ValueError as exc:
+        return None, f"front matter unreadable: a date that does not exist ({exc}); dates are YYYY-MM-DD"
     if not isinstance(data, dict):
         return None, "front matter must be a YAML mapping"
     return data, ""
@@ -100,6 +113,12 @@ def as_date(value) -> datetime.date | None:
         return None
 
 
+def one_of(value, choices) -> bool:
+    """A front matter's value among the words a rule knows. A list or a mapping is none of them,
+    and never a traceback: `in` alone fails on a value it cannot hash."""
+    return isinstance(value, str) and value in choices
+
+
 def cycle_files(root: Path) -> list[Path]:
     folder = root / CYCLES
     return sorted(p for p in folder.glob("*.md") if not p.name.startswith("_")) if folder.is_dir() else []
@@ -188,6 +207,133 @@ def progress_of(path: Path, data: dict, today: datetime.date | None = None, appe
     return f"Cycle {path.stem}: " + " · ".join(said)
 
 
+LATER = re.compile(r"^## Later[ \t]*\n(.*?)(?=^## |\Z)", re.S | re.M)
+# The words the cycle form writes under *Later* (.nstack/forms/cycle.md; a test binds the two).
+LATER_FORM = "<Candidates for the next framing: what framing left out, and ideas that came up during the cycle.>"
+ITEM = re.compile(r"^(?:[-*+]|\d+[.)])\s", re.M)  # a top-level item: one candidate each
+
+
+def _cycle_said(path: Path, data: dict | None) -> str:
+    """One cycle of the project's history: its status, the date that matters for it, and its
+    deliverables as `progress_of` counts them — one figure, wherever it is said. What its own
+    rules refuse (C3, C6) is said plainly, never as a value printed raw."""
+    if data is None:
+        return "front matter unreadable (C1)"
+    status, counts = data.get("status"), progress_of(path, data, appetite=False).split(": ", 1)[1]
+    if not one_of(status, CYCLE_STATUSES):
+        return f"status unknown (C3) · {counts}"
+    if status in OUTCOMES:
+        ended = as_date(data.get("ended_on"))
+        outcome = data.get("outcome") if one_of(data.get("outcome"), OUTCOMES[status]) else "outcome unknown (C6)"
+        return f"{status} ({outcome})" + (f" on {ended}" if ended else "") + f" · {counts}"
+    key, said = ("end", "in progress, ends") if status == "accepted" else ("start", "proposed, starts")
+    date = as_date(data.get(key))
+    return (f"{said} {date}" if date else said.split(",")[0]) + f" · {counts}"
+
+
+def _later(path: Path) -> str | None:
+    """What the cycle's *Later* holds for the next framing: its candidates counted when the
+    section is a list — an item each, its wrapped lines with it —, said as prose otherwise,
+    nothing when the section is absent or still the form's."""
+    match = LATER.search(path.read_text(encoding="utf-8", errors="replace"))
+    text = " ".join(match[1].split()) if match else ""  # the form wraps its line
+    if not text or text == LATER_FORM:
+        return None
+    lines = [line for line in match[1].splitlines() if line.strip()]
+    count = len(ITEM.findall(match[1]))
+    prose = any(not ITEM.match(line) and not line[:1].isspace() for line in lines)
+    held = f"{count} candidate" + ("" if count == 1 else "s")
+    held = (f"{held} listed, and prose" if count else "candidates written as prose") if prose else held
+    return f"Later in {path.stem}, for the next framing: {held}"
+
+
+def criteria(root: Path) -> list[int] | None:
+    """The numbers of the charter's success criteria, from 1 in the order it lists them, that
+    are filled in — the template's example left among them is listed and never counted, so the
+    charter's goal can be reached without declaring it met; None when no charter can be read."""
+    path = root / CHARTER
+    data = read_front_matter(path)[0] if path.is_file() else None
+    listed = data.get("success_criteria") if data else None
+    return [n for n, c in enumerate(listed, start=1) if not unfilled(c)] if isinstance(listed, list) else None
+
+
+def _record(record) -> tuple[int, str, datetime.date | None] | None:
+    """One success record as the view reads it and C6 accepts it: a mapping, its criterion a
+    number from 1, its state known, a day when it is observed. None otherwise."""
+    if not isinstance(record, dict):
+        return None
+    number, state, since = record.get("criterion"), record.get("state"), as_date(record.get("since"))
+    if isinstance(number, bool) or not isinstance(number, int) or number < 1 or not one_of(state, SUCCESS_STATES):
+        return None
+    return None if state == "observing" and since is None else (number, state, since)
+
+
+def success(read: list[tuple[Path, dict | None]]) -> dict[int, tuple[str, datetime.date | None]]:
+    """Each criterion's state: its latest record, in the order of the cycles — a later closure
+    may record a criterion met again as observing (PDR-0019). Only closures record."""
+    states: dict[int, tuple[str, datetime.date | None]] = {}
+    for _, data in read:
+        records = data.get("success") if data and one_of(data.get("status"), OUTCOMES) else None
+        for found in map(_record, records if isinstance(records, list) else []):
+            if found:
+                states[found[0]] = found[1:]
+    return states
+
+
+def _success_said(numbers: list[int], states: dict[int, tuple[str, datetime.date | None]]) -> str:
+    """The project's own progress: the criteria met, then each one observed and since when."""
+    met = sum(1 for number in numbers if states.get(number, ("",))[0] == "met")
+    said = f"{met} of {len(numbers)} success criteri{'on' if len(numbers) == 1 else 'a'} met"
+    if numbers and met == len(numbers):
+        return said + " — the charter's goal is reached: the decider says whether the project is finished"
+    observed = [f"criterion {number} observed since {states[number][1]}"
+                for number in numbers if states.get(number, ("",))[0] == "observing"]
+    return " · ".join([said, *observed]) if observed or states else said + ", recorded at each cycle's closure"
+
+
+def project(root: Path) -> list[str]:
+    """The project across its cycles, for `nstack plan`: the charter's success criteria counted,
+    every cycle in one line, and what the latest cycle left for the next framing — read from the
+    files, never written down. Deliverables are not summed across cycles: a deliverable deferred
+    by one cycle is often framed again in the next, and a total would count it twice. Nothing
+    outside a project, or before a charter or a cycle exists."""
+    charter, cycles = root / CHARTER, cycle_files(root)
+    if stage(root) is None or (not charter.is_file() and not cycles):
+        return []
+    data = read_front_matter(charter)[0] if charter.is_file() else None
+    read = [(path, read_front_matter(path)[0]) for path in cycles]
+    if data is None:
+        head = "no charter readable" if charter.is_file() else "no charter"
+    elif data.get("status") == "accepted":
+        head = _success_said(criteria(root) or [], success(read))
+    else:
+        head = "the charter is proposed" if data.get("status") == "proposed" else "the charter's status unknown (C2)"
+    statuses = [data.get("status") if data else None for _, data in read]
+    known = ("accepted", "proposed", "closed", "stopped")
+    tally = [f"{statuses.count(s)} {s}" for s in known if statuses.count(s)]
+    other = len(statuses) - sum(statuses.count(s) for s in known)
+    tally += [f"{other} other"] if other else []
+    lines = [f"Project: {head} · {len(read)} cycle{'' if len(read) == 1 else 's'}"
+             + (f": {', '.join(tally)}" if tally else "")]
+    width = max(len(path.stem) for path in cycles) if cycles else 0
+    lines += [f"  {path.stem.ljust(width)}  {_cycle_said(path, data)}" for path, data in read]
+    # The cycle running, else the last one ended — where the next framing starts —, else the last.
+    ended = [path for path, data in read if data and one_of(data.get("status"), OUTCOMES)]
+    latest = next((path for path, data in read if data and data.get("status") == "accepted"),
+                  ended[-1] if ended else (cycles[-1] if cycles else None))
+    if latest and (later := _later(latest)):
+        lines.append(f"  {later}")
+    return lines
+
+
+def show(root: Path) -> int:
+    """`nstack plan`'s view of the project: said, never a failure of its own — a file the plan's
+    checks cannot read stops them first."""
+    if lines := project(root):
+        print("\n" + "\n".join(lines))
+    return 0
+
+
 def _left(path: Path, form: tuple[str, ...]) -> list[str]:
     """The words of `form` a seat still holds, as whole lines: a page may hold any tag."""
     lines = {line.strip() for line in path.read_text(encoding="utf-8", errors="replace").splitlines()}
@@ -230,7 +376,7 @@ def _check_charter(path: Path, fail) -> bool:
     if data is None:
         fail("C1", path, reason)
         return False
-    if data.get("status") not in CHARTER_STATUSES:
+    if not one_of(data.get("status"), CHARTER_STATUSES):
         fail("C2", path, f"status '{data.get('status')}': expected one of {sorted(CHARTER_STATUSES)}")
     check_decider("C2", path, data.get("decider"), fail)
     criteria = data.get("success_criteria")
@@ -259,11 +405,11 @@ def _check_deliverables(path: Path, deliverables, fail) -> None:
         if unfilled(item.get("title")):
             fail("C4", path, f"deliverable {where}: title missing, or still the template's")
         state = item.get("state")
-        if state not in DELIVERABLE_STATES:
+        if not one_of(state, DELIVERABLE_STATES):
             fail("C4", path, f"deliverable {where}: state '{state}', expected one of {sorted(DELIVERABLE_STATES)}")
         criteria = item.get("acceptance")
         filled = isinstance(criteria, list) and [c for c in criteria if not unfilled(c)]
-        if state in DELIVERABLE_STATES - WITHOUT_CRITERIA and not filled:
+        if one_of(state, DELIVERABLE_STATES - WITHOUT_CRITERIA) and not filled:
             # The criteria are right, and the refusal names the door the framework already had.
             # Work whose product is knowledge is a SPIKE: its criteria name what will be recorded
             # and the threshold it is read against, and a refuted result is a delivered one. The
@@ -283,7 +429,47 @@ def _check_deliverables(path: Path, deliverables, fail) -> None:
                              "proof.")
 
 
-def _check_cycle(path: Path, fail) -> str | None:
+def _check_success(path: Path, data: dict, status, numbers: list[int] | None, fail) -> None:
+    """C6: the criteria a closure moved, each by its number in the charter's list (PDR-0019)."""
+    records = data.get("success")
+    if records is None:
+        return
+    action = ("Action: name each criterion by its number in docs/project/charter.md, from 1, as met, or as "
+              "observing with since: YYYY-MM-DD, the day observation started (.nstack/playbooks/framing.md, "
+              "the end of a cycle)")
+    if not one_of(status, OUTCOMES):
+        fail("C6", path, f"success: recorded by a cycle that is {status or 'of no known status'}, not closed "
+                         "or stopped — a criterion moves at a closure, when the decider says so. Action: "
+                         "record it in the closure's pull request, with status and outcome")
+        return
+    if not isinstance(records, list):
+        fail("C6", path, f"success: a list of records, one per criterion moved. {action}")
+        return
+    seen: set[int] = set()
+    for index, record in enumerate(records, start=1):
+        where = f"success record no. {index}"
+        if not isinstance(record, dict):
+            fail("C6", path, f"{where}: expected a mapping (criterion, state, since). {action}")
+            continue
+        number, state = record.get("criterion"), record.get("state")
+        if isinstance(number, bool) or not isinstance(number, int) or number < 1:
+            fail("C6", path, f"{where}: criterion '{number}', expected a number from 1. {action}")
+        elif number in seen:
+            fail("C6", path, f"{where}: criterion {number} recorded twice in this closure — keep the one "
+                             "the decider said")
+        elif numbers is not None and number not in numbers:
+            fail("C6", path, f"{where}: criterion {number}, and the charter's filled criteria are numbered "
+                             f"{', '.join(map(str, numbers)) or 'nothing'}. If a decision changed the charter's "
+                             "list, renumber this record to match it, or remove it, with that decision")
+        if isinstance(number, int):
+            seen.add(number)
+        if not one_of(state, SUCCESS_STATES):
+            fail("C6", path, f"{where}: state '{state}', expected one of {sorted(SUCCESS_STATES)}. {action}")
+        elif state == "observing" and as_date(record.get("since")) is None:
+            fail("C6", path, f"{where}: observing since when? {action}")
+
+
+def _check_cycle(path: Path, fail, numbers: list[int] | None = None) -> str | None:
     data, reason = read_front_matter(path)
     if data is None:
         fail("C1", path, reason)
@@ -291,7 +477,7 @@ def _check_cycle(path: Path, fail) -> str | None:
     if not str(data.get("goal") or "").strip():
         fail("C3", path, "goal missing: one sentence")
     status = data.get("status")
-    if status not in CYCLE_STATUSES:
+    if not one_of(status, CYCLE_STATUSES):
         fail("C3", path, f"status '{status}': expected one of {sorted(CYCLE_STATUSES)}")
     weeks = data.get("appetite_weeks")
     if isinstance(weeks, bool) or not isinstance(weeks, int) or weeks < 1:
@@ -304,11 +490,12 @@ def _check_cycle(path: Path, fail) -> str | None:
         fail("C3", path, f"end {end}: the appetite sets it, start + {weeks} week(s) = "
                          f"{start + datetime.timedelta(weeks=weeks)}")
     _check_deliverables(path, data.get("deliverables"), fail)
-    if status in OUTCOMES:
-        if data.get("outcome") not in OUTCOMES[status]:
+    if one_of(status, OUTCOMES):
+        if not one_of(data.get("outcome"), OUTCOMES[status]):
             fail("C6", path, f"a {status} cycle records its outcome: one of {sorted(OUTCOMES[status])}")
         if as_date(data.get("ended_on")) is None:
             fail("C6", path, f"a {status} cycle records ended_on, the date it ended")
+    _check_success(path, data, status, numbers, fail)
     return status if isinstance(status, str) else None
 
 
@@ -318,7 +505,7 @@ def _check_discovery(path: Path, fail) -> str | None:
         fail("C1", path, reason)
         return None
     decision = data.get("decision")
-    if decision not in DECISIONS:
+    if not one_of(decision, DECISIONS):
         fail("C7", path, f"decision '{decision}': expected one of {sorted(DECISIONS)}")
     elif decision != "proposed":
         check_decider("C7", path, data.get("decider"), fail)
@@ -330,6 +517,63 @@ def _check_discovery(path: Path, fail) -> str | None:
     return decision if isinstance(decision, str) else None
 
 
+RECORDS = (Path("docs") / "pdr", Path("docs") / "adr")
+CRITERION = re.compile(r"^## Success criterion[^\n]*\n(.*?)(?=^## |\Z)", re.S | re.M)
+READING = re.compile(r"Read at `?(.+?)`?'s closure, (\d{4}-\d{2}-\d{2}): (?:met|missed|superseded)\b", re.I)
+DAY = re.compile(r"(?<![\d-])\d{4}-\d{2}-\d{2}(?![\d-])")
+NUMBERED = re.compile(r"\bcycle\s+0*(\d+)\b", re.I)
+HEADER = re.compile(r"^[-*\s]*\**(Status|Date)\**\s*:\**\s*(\S+)", re.M | re.I)
+
+
+def _names(text: str, stem: str) -> bool:
+    """Whether `text` names the cycle of file `stem`: by its file (`03-the-window`), or as `cycle 03`."""
+    number = re.match(r"\d+", stem)
+    return bool(re.search(rf"(?<![\w-]){re.escape(stem)}(?![\w-])", text)
+                or number and int(number[0]) in {int(n) for n in NUMBERED.findall(text)})
+
+
+def _due(root: Path, read: list[tuple[Path, dict | None]]) -> list[str]:
+    """C10: each accepted decision record whose success criterion is due at a closure and says no
+    reading of it (PDR-0020). Only the criterion section is read: a cycle named by its file or as
+    *cycle NN*, a date written YYYY-MM-DD. A named cycle is due at its closure; a date at the first
+    closure that reaches it — read once, a later date waits for a later closure, and a reading on or
+    after a date answers it, even at a cycle that stopped before it. A closure before the record's own
+    date is not one it could be read at. Said, never refused."""
+    closures = sorted(((ended, path.stem) for path, data in read
+                       if data and one_of(data.get("status"), OUTCOMES)
+                       and (ended := as_date(data.get("ended_on")))))
+    if not closures:
+        return []
+    said = []
+    for path in sorted(p for folder in RECORDS if (root / folder).is_dir()
+                       for p in (root / folder).glob("*.md")
+                       if p.is_file() and p.name != "README.md" and not p.name.startswith("_")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        header = {key.lower(): value.strip("*,.") for key, value in HEADER.findall(text.split("\n## ", 1)[0])}
+        section = CRITERION.search(text)
+        if header.get("status", "").lower() != "accepted" or not section:
+            continue
+        criterion = re.sub(r"<!--.*?-->", "", section[1], flags=re.S)
+        readings = [(name, day) for name, on in READING.findall(criterion) if (day := as_date(on))]
+        criterion = "\n".join(line for line in criterion.splitlines() if not READING.search(line))
+        since = as_date(header.get("date", ""))
+        open_ = [(ended, stem) for ended, stem in closures if since is None or ended >= since]
+        due = {closure for closure in open_ if _names(criterion, closure[1])}
+        for day in filter(None, map(as_date, DAY.findall(criterion))):
+            # A reading on or after the date has seen it pass, at whichever closure it was written.
+            reached = next((closure for closure in open_ if closure[0] >= day), None)
+            if reached and not any(on >= day for _, on in readings):
+                due.add(reached)
+        for ended, stem in sorted(due):
+            if not any(_names(name, stem) and on >= ended for name, on in readings):
+                said.append(f"[C10] {path.relative_to(root)}\n      its success criterion is due at {stem}'s "
+                            f"closure ({ended}), and holds no line saying it was read.\n      Action: read it, and "
+                            f"write in its success criterion: \"Read at {stem}'s closure, <YYYY-MM-DD>: met | "
+                            "missed | superseded\" — a missed one is the decider's to answer, by a decision of its "
+                            "own (.nstack/playbooks/framing.md, Decisions).")
+    return said
+
+
 def run(root: Path) -> int:
     failures: list[str] = []
 
@@ -352,7 +596,8 @@ def run(root: Path) -> int:
     if accepted_charter and discovery.is_file() and decision != "go":
         fail("C7", charter, f"the charter is accepted, but the discovery's decision is '{decision}': "
                             "a charter follows a go (docs/project/discovery.md)")
-    accepted = [path for path in cycles if _check_cycle(path, fail) == "accepted"]
+    numbers = criteria(root)
+    accepted = [path for path in cycles if _check_cycle(path, fail, numbers) == "accepted"]
     if len(accepted) > 1:
         names = ", ".join(path.name for path in accepted)
         fail("C5", root / CYCLES, f"{len(accepted)} accepted cycles ({names}): one cycle at a time — "
@@ -364,6 +609,8 @@ def run(root: Path) -> int:
     print(f"Plan: charter {'present' if charter.is_file() else 'absent'}, {len(cycles)} cycle(s).")
     if len(accepted) == 1 and accepted_charter:
         print(progress(root))
+    for warning in _due(root, [(path, read_front_matter(path)[0]) for path in cycles]):
+        print(f"  WARNING {warning}")
     for failure in failures:
         print(f"  FAIL {failure}")
     if failures:

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/hold.py

@@ -179,7 +179,7 @@ def _deliverable(root: Path, ident: str) -> tuple[str, str] | str:
     if ident not in items:
         return (f"{ident} is not in {path.stem}.\n      Action: name one of {', '.join(items) or 'its deliverables'}.")
     state = items[ident].get("state")
-    if state not in TAKEABLE:
+    if not plan.one_of(state, TAKEABLE):
         return (f"{ident} is '{state}': work starts on a ready deliverable (definition of ready).\n"
                 "      Action: take a ready one — nstack plan lists them.")
     return path.stem, str(items[ident].get("title") or ident)
@@ -445,12 +445,20 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
     return 0
 
 
+def _ended(root: Path, ident: str, current: str | None) -> str | None:
+    """Where a hold of an ended cycle is still open: a hold lasts its cycle (#280). Nothing it
+    guarded can be delivered any more, and a new cycle's hold is a branch of its own."""
+    for path in plan.cycle_files(root):
+        status = (plan.read_front_matter(path)[0] or {}).get("status")
+        if path.stem != current and plan.one_of(status, plan.OUTCOMES) and read(root, path.stem, ident).held:
+            return (f"{ident}'s hold ended with {path.stem} ({status}): a hold lasts its cycle, nothing to release. "
+                    f"Its branch {PREFIX}/{path.stem}/{ident} is kept, the hold's record.")
+    return None
+
+
 def release(root: Path, ident: str, session: str | None = None, person: str | None = None) -> int:
     cycle = plan.accepted_cycle(root)
-    if cycle is None:
-        print("FAIL [hold] no accepted cycle: there is no hold to release.")
-        return 1
-    stem = cycle[0].stem
+    stem = cycle[0].stem if cycle else None
     person = _person(root, person)
     if any(not value.isprintable() for value in (person, session or "")):
         print("FAIL [hold] a person or a session holds a line break or a control character.\n"
@@ -461,9 +469,14 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
     except Unreachable as error:
         print(f"FAIL [hold] the remote cannot be read.\n      {error}\n      Action: check it, then again.")
         return 1
-    current = read(root, stem, ident)
+    current = read(root, stem, ident) if stem else Hold()
     if not current.held:
-        print(f"FAIL [hold] {ident} is not held: nothing to release.")
+        ended = _ended(root, ident, stem)
+        if ended:
+            print(ended)
+            return 0
+        print(f"FAIL [hold] {ident} is not held: nothing to release." if stem else
+              "FAIL [hold] no accepted cycle: there is no hold to release.")
         return 1
     charter = plan.read_front_matter(root / plan.CHARTER)[0] if (root / plan.CHARTER).is_file() else None
     decider = str((charter or {}).get("decider") or "")
@@ -500,11 +513,11 @@ def show(root: Path) -> int:
             continue
         ident, state = str(item.get("id")), item.get("state")
         found = read(root, path.stem, ident)
-        if not found.held and state not in TAKEABLE:
+        if not found.held and not plan.one_of(state, TAKEABLE):
             continue
         if not found.held:
             lines.append(f"  {ident}  free")
-        elif state not in TAKEABLE:
+        elif not plan.one_of(state, TAKEABLE):
             lines.append(f"  {ident}  ended — {state}; was {said(found)}")
         elif time.time() >= found.worked + days * DAY:
             held, stale = held + 1, stale + 1

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/modules.py

@@ -376,6 +376,11 @@ def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | Non
                 print(f"FAIL [release] {odd.relative_to(root)} is a link or a file, not a folder of the project's own: "
                       "nothing is emptied through it.\n      Action: remove it, then release again.")
                 return 1
+            left = sorted(path.relative_to(dist).as_posix() for path in dist.rglob("*") if not path.is_dir()) if dist.is_dir() else []
+            if left:  # never silent: another target's package may be among them (#276)
+                named = ", ".join(left[:5]) + (f", and {len(left) - 5} more" if len(left) > 5 else "")
+                print(f"-> {target}: {dist.relative_to(root).as_posix()} emptied first, "
+                      f"{len(left)} file{'s' if len(left) > 1 else ''}: {named}", flush=True)
             shutil.rmtree(dist, ignore_errors=True)
             dist.mkdir(parents=True)
             environment = {**os.environ, "NSTACK_DIST": str(dist.resolve())}
@@ -383,14 +388,15 @@ def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | Non
             # Its evidence: a folder of its own, its output kept, its logs read after (ADR-0009).
             from napkinstack import evidence
 
-            folder = evidence.prepare(root, known[target])
-            if isinstance(folder, str):
-                print(f"FAIL [e2e] module '{target}': {folder}")
-                return 1
-            print(f"-> {target}: {command}", flush=True)
-            code, held = evidence.run(command, known[target], {**os.environ, "NSTACK_EVIDENCE": str(folder.resolve())},
-                                      folder)
-            passed = evidence.finish(root, target, known[target], folder, code, held)
+            with evidence.one_at_a_time(root, target):
+                folder = evidence.prepare(root, known[target])
+                if isinstance(folder, str):
+                    print(f"FAIL [e2e] module '{target}': {folder}")
+                    return 1
+                print(f"-> {target}: {command}", flush=True)
+                code, held = evidence.run(command, known[target], {**os.environ, evidence.HELD: "1",
+                                                                   "NSTACK_EVIDENCE": str(folder.resolve())}, folder)
+                passed = evidence.finish(root, target, known[target], folder, code, held)
             if code == evidence.NOT_RUN and passed:
                 print(f"-> {target}: e2e not run here: its output says why, in {folder.relative_to(root)}/output.txt.")
                 continue

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/provenance.py

@@ -62,6 +62,10 @@ def engine() -> tuple[str, str | None]:
     path = Path(url2pathname(urlparse(data.get("url", "")).path))
     commit = subprocess.run(["git", "describe", "--always", "--dirty"], cwd=path,
                             capture_output=True, text=True).stdout.strip() if path.is_dir() else ""
+    if commit and not commit.endswith("-dirty") and subprocess.run(
+            ["git", "status", "--porcelain", "--untracked-files=normal"], cwd=path,
+            capture_output=True, text=True).stdout.strip():
+        commit += "-dirty"  # a file git does not track yet runs as surely as one it does
     return version(), f"a local checkout at {commit or 'an unknown commit'}"
 
 

{napkinstack-0.16.0 → napkinstack-0.18.0}/src/napkinstack/pull_request.py

@@ -321,10 +321,13 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
             # declared, so it is re-run. One that was explored by hand costs a round: its evidence keeps the commit
             # it was produced on, and the verifier confirms at the head, naming what moved since.
             # At `critical` nothing stands in for a re-run: that is what the top value buys.
-            confirmed = row.get(CONFIRMED, "").strip().split(" ", 1)[0].strip("`").lower()
+            # Each clause of the cell starts with the commit it confirms: a later confirmation
+            # joins an earlier one after a `;`, never replacing it (#288).
+            confirmed = [clause.strip().split(" ", 1)[0].strip("`").lower()
+                         for clause in row.get(CONFIRMED, "").split(";")]
             if kind.lower() == "automated" or strict:
                 rerun.append(ident)
-            elif not (SHA.fullmatch(confirmed) and head.startswith(confirmed)):
+            elif not any(SHA.fullmatch(commit) and head.startswith(commit) for commit in confirmed):
                 unconfirmed.append(ident)
         if result == "failed":
             fail("T5", f"scenario {ident}: failed.\n      Action: fix the change, or have the decider "
@@ -346,8 +349,9 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
         fail("T4", f"scenarios explored before the head {head[:7]} and not confirmed on it: "
                    f"{', '.join(unconfirmed)}.\n      Action: re-read what changed since, then "
                    f"add the head commit in a Confirmed column: `{head[:7]} — <what moved, and why "
-                   "it leaves this scenario's result standing>`.\n      Running the whole sheet "
-                   "again is the other way, and it is not required: a confirmation is not a round "
+                   "it leaves this scenario's result standing>`, after a `;` when the cell holds an "
+                   "earlier one.\n      Running the whole sheet again is the other way, and it is not "
+                   "required: a confirmation is not a round "
                    "(.nstack/handbook/05-workflow.md §7).")
     return human_only
 
@@ -393,7 +397,7 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
     elif match[1] not in states:
         fail("K3", f"deliverable {match[1]} is not in {path.name}.\n      Action: name one of "
                    f"{', '.join(states) or 'its deliverables'}, or re-frame the cycle with the decider.")
-    elif states[match[1]] not in {"ready", "in-progress"}:
+    elif not plan.one_of(states[match[1]], {"ready", "in-progress"}):
         fail("K3", f"deliverable {match[1]} is '{states[match[1]]}': work starts on a ready "
                    "deliverable (definition of ready).")
     elif states[match[1]] == "ready":