napkinstack 0.17.0__tar.gz → 0.18.0__tar.gz

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

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

{napkinstack-0.17.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.17.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.17.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.17.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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.17.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.17.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.17.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), the project across its cycles, "
-         "and who holds what", lambda a: plan.run(a.root) | plan.show(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.17.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.17.0 → napkinstack-0.18.0}/src/napkinstack/fitness/plan.py

@@ -19,6 +19,9 @@ Rules:
   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. `nstack plan` then says the project
 across its cycles (`project`), a display that never fails.
@@ -514,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] = []
 
@@ -549,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.17.0 → napkinstack-0.18.0}/src/napkinstack/hold.py

@@ -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 "")
@@ -504,7 +517,7 @@ def show(root: Path) -> int:
             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.17.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.17.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.17.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