napkinstack 0.16.0__tar.gz → 0.17.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.16.0
+Version: 0.17.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.17.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.17.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.17.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.17.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.17.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.17.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.17.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.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.16.0"
+version = "0.17.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.17.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.16.0"
+version = "0.17.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.17.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.17.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 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")

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

@@ -12,14 +12,16 @@ 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
 
-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 +60,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 +79,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 +110,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 +204,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 +373,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 +402,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 +426,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 +474,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 +487,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 +502,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)
@@ -352,7 +536,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 — "

{napkinstack-0.16.0 → napkinstack-0.17.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)
@@ -500,7 +500,7 @@ 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")

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

@@ -393,7 +393,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":