napkinstack 0.29.1__tar.gz → 0.31.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {napkinstack-0.29.1 → napkinstack-0.31.0}/PKG-INFO +6 -6
  2. {napkinstack-0.29.1 → napkinstack-0.31.0}/README.md +5 -5
  3. {napkinstack-0.29.1 → napkinstack-0.31.0}/pyproject.toml +1 -1
  4. {napkinstack-0.29.1 → napkinstack-0.31.0}/pyproject.toml.orig +1 -1
  5. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/attest.py +116 -6
  6. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/board.py +39 -4
  7. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/cli.py +8 -5
  8. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/doctor.py +50 -3
  9. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/evidence.py +34 -3
  10. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/manifests.py +6 -1
  11. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/plan.py +20 -8
  12. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/modules.py +14 -6
  13. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/project.py +49 -0
  14. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/pull_request.py +181 -14
  15. {napkinstack-0.29.1 → napkinstack-0.31.0}/LICENSE +0 -0
  16. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/__init__.py +0 -0
  17. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/__main__.py +0 -0
  18. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/agent.py +0 -0
  19. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/assurance.py +0 -0
  20. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/compat.py +0 -0
  21. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/discovery.py +0 -0
  22. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/__init__.py +0 -0
  23. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/boundaries.py +0 -0
  24. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/hygiene.py +0 -0
  25. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/fitness/pr_scope.py +0 -0
  26. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/hold.py +0 -0
  27. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/landed.py +0 -0
  28. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/owners.py +0 -0
  29. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/provenance.py +0 -0
  30. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/settings.py +0 -0
  31. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/skills.py +0 -0
  32. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {napkinstack-0.29.1 → napkinstack-0.31.0}/src/napkinstack/templates/module/tests/.gitkeep +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: napkinstack
3
- Version: 0.29.1
3
+ Version: 0.31.0
4
4
  Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
5
5
  License-Expression: MIT
6
6
  License-File: LICENSE
@@ -22,7 +22,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
22
22
  the project, which then receives new versions on demand; no application stack is imposed.
23
23
  Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
24
24
 
25
- > **Status: v0.29.1, published** on [PyPI](https://pypi.org/project/napkinstack/).
25
+ > **Status: v0.31.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
26
26
  > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
27
27
  > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
28
28
 
@@ -86,8 +86,8 @@ To try it without installing anything, or to install it from this repository ins
86
86
  registry — always pinned to a release tag:
87
87
 
88
88
  ```bash
89
- uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.29.1" nstack init my-project
90
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.29.1"
89
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.31.0" nstack init my-project
90
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.31.0"
91
91
  ```
92
92
 
93
93
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -117,12 +117,12 @@ Each project then pins its version and changes it through `nstack update`.
117
117
  | `nstack claim <deliverable or '#issue'> [--take-over]`; `nstack unclaim …` | Takes a ready deliverable — or an issue no cycle plans — for a session before its first change, on a branch of its own the shared remote refuses to a second taker; gives it back ([ADR-0007](docs/adr/0007-hold-a-deliverable-on-a-branch-of-its-own.md)) |
118
118
  | `nstack deliver <deliverable> --held [N=]#PR` | Records that a merged deliverable is delivered, criterion by criterion, with no pull request; refused with no merge of it; `--write-states` writes the states at a closure ([PDR-0022](docs/pdr/0022-agents-deliver-alone-a-person-is-asked-only-where-it-matters.md)) |
119
119
  | `nstack agent add <name>`; `nstack agent run <name> -- <command>`; `nstack agent status` | Gives an agent its own GitHub App and a clone that commits as it and runs the project's hooks — `add` is a person's, two clicks at the forge; starts the agent there without the person's credentials, says what it keeps of them, gives Claude Code settings of its own; `status` tells an agent who it is, a person this project's agents (`--all`: every project's) ([ADR-0004](docs/adr/0004-give-agents-their-own-github-identity.md)) |
120
- | `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)) |
120
+ | `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)); a dry run also previews what a proposed cycle's acceptance would create |
121
121
  | `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
122
122
  | `nstack pr-scope` | One PR = one module, review budget |
123
123
  | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
124
124
  | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
125
- | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
125
+ | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
126
126
  | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
127
127
  | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
128
128
  | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
5
5
  the project, which then receives new versions on demand; no application stack is imposed.
6
6
  Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
7
7
 
8
- > **Status: v0.29.1, published** on [PyPI](https://pypi.org/project/napkinstack/).
8
+ > **Status: v0.31.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
9
9
  > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
10
10
  > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
11
11
 
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
69
69
  registry — always pinned to a release tag:
70
70
 
71
71
  ```bash
72
- uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.29.1" nstack init my-project
73
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.29.1"
72
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.31.0" nstack init my-project
73
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.31.0"
74
74
  ```
75
75
 
76
76
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -100,12 +100,12 @@ Each project then pins its version and changes it through `nstack update`.
100
100
  | `nstack claim <deliverable or '#issue'> [--take-over]`; `nstack unclaim …` | Takes a ready deliverable — or an issue no cycle plans — for a session before its first change, on a branch of its own the shared remote refuses to a second taker; gives it back ([ADR-0007](docs/adr/0007-hold-a-deliverable-on-a-branch-of-its-own.md)) |
101
101
  | `nstack deliver <deliverable> --held [N=]#PR` | Records that a merged deliverable is delivered, criterion by criterion, with no pull request; refused with no merge of it; `--write-states` writes the states at a closure ([PDR-0022](docs/pdr/0022-agents-deliver-alone-a-person-is-asked-only-where-it-matters.md)) |
102
102
  | `nstack agent add <name>`; `nstack agent run <name> -- <command>`; `nstack agent status` | Gives an agent its own GitHub App and a clone that commits as it and runs the project's hooks — `add` is a person's, two clicks at the forge; starts the agent there without the person's credentials, says what it keeps of them, gives Claude Code settings of its own; `status` tells an agent who it is, a person this project's agents (`--all`: every project's) ([ADR-0004](docs/adr/0004-give-agents-their-own-github-identity.md)) |
103
- | `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)) |
103
+ | `nstack board [--dry-run]` | Shows the cycles and their deliverables on the forge, one way: milestones and issues ([ADR-0008](docs/adr/0008-show-the-plan-as-milestones-and-issues-applied-by-ci.md)); a dry run also previews what a proposed cycle's acceptance would create |
104
104
  | `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
105
105
  | `nstack pr-scope` | One PR = one module, review budget |
106
106
  | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
107
107
  | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
108
- | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
108
+ | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
109
109
  | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
110
110
  | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
111
111
  | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.29.1"
3
+ version = "0.31.0"
4
4
  description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.29.1"
3
+ version = "0.31.0"
4
4
  description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -7,7 +7,10 @@ test — on a clean tree at a commit, and appends the run to that commit's note
7
7
  `refs/notes/nstack/checks`, one JSON line per run. The note travels with the branch's remote
8
8
  and is merged line by line; the latest line for a commit is its record. On GitHub, with a token
9
9
  that may write statuses, the run is also shown as `nstack / local checks` — a name no CI job
10
- has. A ruleset that requires that name gates the merge on the record, and the forge's pull
10
+ has. A passed `Module checks` is kept, not run again, while the digest of what it reads is
11
+ unchanged — the modules it runs and those they consume from or assemble, the files outside the
12
+ modules, `contracts/` and `platform/` included, the engine and the person — for 7 days and 20 commits of the default branch at most (ADR-0006,
13
+ D223). A ruleset that requires that name gates the merge on the record, and the forge's pull
11
14
  request run leaves the record to it (D221): notes start no run, a status is an event.
12
15
  A record is *attested*, never *checked*: it makes a claim traceable, not true.
13
16
 
@@ -293,6 +296,93 @@ def why(output: str) -> list[str]:
293
296
  NAMED = re.compile(r".* \(commit [0-9a-f]{7,}\)|.*@[0-9a-f]{7,}|a local checkout at (?!an unknown commit)\S+(?<!-dirty)")
294
297
 
295
298
 
299
+ FRESH_DAYS = 7 # a check kept by its inputs, at most this old (ADR-0006, D223)
300
+ FRESH_COMMITS = 20 # and the default branch moved by at most this many commits since its run
301
+
302
+
303
+ SHARED_MODULES = ("contracts", "platform") # read by every module: counted as shared files (D223)
304
+
305
+
306
+ def inputs(root: Path, base: str, identity: str = "") -> str | None:
307
+ """The digest of what `Module checks` reads at HEAD (ADR-0006 decision 2, D223): the folders of
308
+ the modules it runs, of those they consume from or assemble, every tracked path outside the
309
+ module folders — `contracts/` and `platform/` included, which every module reads — and who runs
310
+ it with which engine; git's ids, never hashed by hand. None when it cannot be told: no key."""
311
+ import yaml
312
+
313
+ from napkinstack import modules
314
+
315
+ ran = modules.listing(root, base, with_contract_sides=True)
316
+ every = {module["name"]: module["folder"] for module in modules.listing(root) or []}
317
+ if ran is None:
318
+ return None
319
+ folders = {module["folder"] for module in ran}
320
+ for module in ran:
321
+ try:
322
+ data = yaml.safe_load((root / module["folder"] / "MANIFEST.yaml").read_text(encoding="utf-8")) or {}
323
+ except (OSError, yaml.YAMLError):
324
+ return None
325
+ consumes = data.get("consumes") if isinstance(data, dict) else None
326
+ assembles = data.get("assembles") if isinstance(data, dict) else None
327
+ named = [entry.get("module") for entry in consumes if isinstance(entry, dict) and entry.get("module")] \
328
+ if isinstance(consumes, list) else []
329
+ named += [name for name in assembles if isinstance(name, str)] if isinstance(assembles, list) else []
330
+ for name in named:
331
+ if name not in every:
332
+ return None # a dependency the project does not hold: what it reads is unknown
333
+ folders.add(every[name])
334
+ lines = [f"ran {' '.join(sorted(module['name'] for module in ran))}", f"identity {identity}"]
335
+ for folder in sorted(folders):
336
+ tree = _git(root, "rev-parse", "--verify", "--quiet", f"HEAD:{folder}", check=False).stdout.strip()
337
+ if not tree:
338
+ return None
339
+ lines.append(f"{folder} {tree}")
340
+ inside = tuple(f"{folder}/" for folder in every.values() if folder.split("/", 1)[0] not in SHARED_MODULES)
341
+ listed = _git(root, "ls-tree", "-r", "--full-tree", "HEAD", check=False)
342
+ if listed.returncode:
343
+ return None
344
+ lines += [line for line in listed.stdout.splitlines() if not line.split("\t", 1)[-1].startswith(inside)]
345
+ return hashlib.sha256("\n".join(lines).encode("utf-8", "surrogateescape")).hexdigest()
346
+
347
+
348
+ def _fresh(root: Path, at: str, run_base: str | None, base_commit: str | None) -> bool:
349
+ """Whether a run kept by its inputs is recent enough (ADR-0006, D223)."""
350
+ try:
351
+ when = datetime.datetime.fromisoformat(at)
352
+ except (TypeError, ValueError):
353
+ return False
354
+ now = datetime.datetime.now(datetime.timezone.utc)
355
+ if when.tzinfo is None or now - when > datetime.timedelta(days=FRESH_DAYS) or when - now > datetime.timedelta(minutes=5):
356
+ return False # too old, or from a clock ahead: never fresh for longer than the bound
357
+ if not run_base or not base_commit:
358
+ return False
359
+ moved = _git(root, "rev-list", "--count", f"{run_base}..{base_commit}", check=False)
360
+ return moved.returncode == 0 and int(moved.stdout.strip() or 0) <= FRESH_COMMITS
361
+
362
+
363
+ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine: str, origin: str | None,
364
+ base_commit: str | None, who: str, said: str | None) -> dict | None:
365
+ """The check as a passed run on this branch's history left it, when what it reads is the same
366
+ — the digest of its inputs, whatever the commit — and the run is fresh (ADR-0006, D223)."""
367
+ if digest is None or not check.kept or base_commit is None or not (origin is None or NAMED.fullmatch(origin)):
368
+ return None
369
+ for commit in _git(root, "rev-list", f"{base_commit}..HEAD", check=False).stdout.split():
370
+ record = latest(root, commit)
371
+ if record is None or (record.get("engine"), record.get("origin"), record.get("published"),
372
+ record.get("by")) != (engine, said, origin is None, who):
373
+ continue
374
+ checks = record.get("checks") if isinstance(record.get("checks"), list) else []
375
+ found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
376
+ if not found or found.get("passed") is not True or found.get("inputs") != digest:
377
+ continue
378
+ first = str(found.get("kept_from") or record.get("at", ""))
379
+ run_base = found.get("kept_base") or record.get("base_commit")
380
+ if not _fresh(root, first, run_base, base_commit):
381
+ continue
382
+ return {**found, "kept_from": first, "kept_commit": found.get("kept_commit") or commit, "kept_base": run_base}
383
+ return None
384
+
385
+
296
386
  def _kept(previous: dict | None, check: Check, engine: str, origin: str | None, base_commit: str | None,
297
387
  who: str, said: str | None = None) -> dict | None:
298
388
  """The check as the commit's record last passed it, when what it reads is the same: the commit,
@@ -307,8 +397,8 @@ def _kept(previous: dict | None, check: Check, engine: str, origin: str | None,
307
397
  return None
308
398
  checks = previous.get("checks") if isinstance(previous.get("checks"), list) else []
309
399
  found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
310
- if not found or found.get("passed") is not True:
311
- return None
400
+ if not found or found.get("passed") is not True or found.get("kept_commit"):
401
+ return None # kept by its inputs from another commit: its freshness is _by_inputs' to judge (D223)
312
402
  return {**found, "kept_from": found.get("kept_from") or previous.get("at")}
313
403
 
314
404
 
@@ -355,8 +445,16 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
355
445
  engine, origin = provenance.engine()
356
446
  base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).stdout.strip() or None
357
447
  previous = None if again else latest(root, commit)
358
- # The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147).
359
- env = dict(os.environ, PR_LABELS=os.environ.get("PR_LABELS", "") if labels is None else labels)
448
+ # The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147) — and the
449
+ # pull request's own when the forge answers, a label it does not carry refused (#368).
450
+ from napkinstack.pull_request import labels_for
451
+
452
+ judged, labels_from, refused = labels_for(root, commit, os.environ.get("PR_LABELS", "") if labels is None else labels)
453
+ if refused:
454
+ print(f"FAIL [attest] {refused}")
455
+ return 1
456
+ print(f"Labels: {', '.join(sorted(judged)) or 'none'} — {labels_from}", flush=True)
457
+ env = dict(os.environ, PR_LABELS=",".join(sorted(judged)))
360
458
  # The engine that runs this command runs the checks: its folder first on the path.
361
459
  env["PATH"] = os.pathsep.join([str(Path(sys.argv[0]).resolve().parent), env.get("PATH", "")])
362
460
  results = []
@@ -369,6 +467,8 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
369
467
  # without asking for the record this run is making (A1, A2) — found rehearsing v0.10.0.
370
468
  env.update(NSTACK_BASE=base, NSTACK_BODY=str(Path(body).resolve()), NSTACK_TMP=tmp,
371
469
  NSTACK_ATTESTING=commit)
470
+ digest = inputs(root, base, json.dumps([engine, unplaced(origin, root), origin is None, who]))
471
+ env["NSTACK_INPUTS"] = digest or "" # the head's, for pr-check's T4 while this record is made (D223)
372
472
  for check in CHECKS:
373
473
  kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root))
374
474
  if kept is not None:
@@ -376,6 +476,14 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
376
476
  print(f"ok [attest] {check.name}: kept from the record of {kept['kept_from']} — same commit, base "
377
477
  "and engine (nstack attest --again runs it)", flush=True)
378
478
  continue
479
+ kept = None if again else _by_inputs(root, base, digest, check, engine, origin, base_commit, who,
480
+ unplaced(origin, root))
481
+ if kept is not None:
482
+ results.append(kept)
483
+ print(f"ok [attest] {check.name}: kept from the run on {kept['kept_commit'][:7]} at {kept['kept_from']} — "
484
+ f"same inputs ({digest[:12]}), within {FRESH_DAYS} days and {FRESH_COMMITS} commits of the "
485
+ "default branch (nstack attest --again runs it)", flush=True)
486
+ continue
379
487
  steps = []
380
488
  for step in check.steps:
381
489
  done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env,
@@ -384,7 +492,8 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
384
492
  "output": capped(done.stdout),
385
493
  "sha256": hashlib.sha256(done.stdout.encode("utf-8", "replace")).hexdigest()})
386
494
  passed = all(step["exit"] == 0 for step in steps)
387
- results.append({"name": check.name, "passed": passed, "steps": steps})
495
+ results.append({"name": check.name, "passed": passed, "steps": steps,
496
+ **({"inputs": digest} if check.kept and digest else {})})
388
497
  failed = "; ".join(f"{s['label']} exited {s['exit']}" for s in steps if s["exit"])
389
498
  print(f"FAIL [attest] {check.name}: {failed}" if failed else f"ok [attest] {check.name}", flush=True)
390
499
  for step in steps:
@@ -395,6 +504,7 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
395
504
  "engine": engine, "origin": origin, "published": origin is None, "by": who, "session": _session(root, commit),
396
505
  "base": base, "base_commit": base_commit, "checks": results,
397
506
  "sheet": sheet_of(body_text),
507
+ "labels": {"names": sorted(judged), "from": labels_from},
398
508
  # The audits of the run the module checks come from: kept with them, never read again (#275).
399
509
  "evidence": (previous.get("evidence") if isinstance(previous.get("evidence"), list) else [])
400
510
  if previous and any(r.get("kept_from") for r in results) else evidence_of(root, commit)}
@@ -2,7 +2,8 @@
2
2
  The plan shown on the forge, one way (PDR-0016, ADR-0008).
3
3
 
4
4
  The cycle files are the plan; this command shows them on GitHub — a milestone per accepted,
5
- closed or stopped cycle, an issue per deliverable — and keeps the display equal to them. Its own
5
+ closed or stopped cycle, an issue per deliverable — and keeps the display equal to them. A dry
6
+ run also previews what a proposed cycle's acceptance would create, and makes none of it. Its own
6
7
  objects carry a marker in their body; an object without one is never touched. What the forge
7
8
  holds decides nothing but whether the display must be rewritten.
8
9
 
@@ -72,7 +73,8 @@ def _reason(state: str) -> str:
72
73
 
73
74
 
74
75
  def desired(root: Path, holders: dict[str, str] | None = None, pulls: dict[str, list[int]] | None = None,
75
- today: datetime.date | None = None, delivered: set[str] | None = None) -> tuple[list[Shown], list[str]]:
76
+ today: datetime.date | None = None, delivered: set[str] | None = None,
77
+ statuses: set[str] = SHOWN) -> tuple[list[Shown], list[str]]:
76
78
  """The display the cycle files call for, and what cannot be shown and why. `holders`:
77
79
  deliverable identifier to the hold's person; `pulls`: identifier to the pull requests whose
78
80
  description names it."""
@@ -81,7 +83,7 @@ def desired(root: Path, holders: dict[str, str] | None = None, pulls: dict[str,
81
83
  for path in plan.cycle_files(root):
82
84
  data = plan.read_front_matter(path)[0]
83
85
  found = NUMBER.match(path.stem)
84
- if data and plan.one_of(data.get("status"), SHOWN) and found:
86
+ if data and plan.one_of(data.get("status"), statuses) and found:
85
87
  cycles.setdefault(found[1], []).append((path, data))
86
88
  said = [f"cycle {number} not shown: {len(files)} cycle files carry its number "
87
89
  f"({', '.join(path.name for path, _ in files)})" for number, files in cycles.items() if len(files) > 1]
@@ -99,7 +101,7 @@ def desired(root: Path, holders: dict[str, str] | None = None, pulls: dict[str,
99
101
  continue
100
102
  path, data = files[0]
101
103
  relative = path.relative_to(root).as_posix()
102
- closed = data.get("status") != "accepted"
104
+ closed = data.get("status") not in ("accepted", "proposed") # proposed: only ever previewed
103
105
  text = path.read_text(encoding="utf-8", errors="replace")
104
106
  front = plan.FRONT_MATTER.match(text)
105
107
  heading = HEADING.search(text[front.end():] if front else text)
@@ -206,6 +208,8 @@ def _clean(text) -> str:
206
208
  def run(root: Path, dry_run: bool = False, today: datetime.date | None = None) -> int:
207
209
  from napkinstack import hold
208
210
 
211
+ if dry_run:
212
+ _preview(root, today)
209
213
  first, said = desired(root, today=today)
210
214
  if not first:
211
215
  _tell(said, "Plan on the forge: nothing to show — no accepted, closed or stopped cycle")
@@ -240,6 +244,37 @@ def run(root: Path, dry_run: bool = False, today: datetime.date | None = None) -
240
244
  return 0
241
245
 
242
246
 
247
+ def _preview(root: Path, today: datetime.date | None) -> None:
248
+ """What a proposed cycle's acceptance would create, said on a dry run and never made (#372): the
249
+ decider reviews the breakdown as the board will show it, before the acceptance decides it."""
250
+ numbers, idents = set(), set()
251
+ for path in plan.cycle_files(root):
252
+ data = plan.read_front_matter(path)[0]
253
+ found = NUMBER.match(path.stem)
254
+ if data and data.get("status") == "proposed" and found:
255
+ numbers.add(found[1])
256
+ items = data.get("deliverables")
257
+ idents |= {str(item["id"]) for item in items if isinstance(item, dict) and item.get("id")} \
258
+ if isinstance(items, list) else set()
259
+ if not numbers:
260
+ return
261
+ # Read beside the cycles already shown: what their acceptance would collide with is said too.
262
+ every, said = desired(root, today=today, statuses=SHOWN | {"proposed"})
263
+ for number in sorted(numbers):
264
+ cycle = next((item for item in every if item.kind == "cycle" and item.key == number), None)
265
+ if cycle is None:
266
+ continue
267
+ print(f"On acceptance of cycle {number} — previewed, nothing made:\n"
268
+ f" milestone {cycle.title}, ends {cycle.due or 'with no end date'}")
269
+ for item in every:
270
+ if item.kind == "deliverable" and item.cycle == number:
271
+ state = item.labels[-1].removeprefix("state: ") if item.labels else ""
272
+ print(f" issue {item.title} — {state}" + (", shown closed" if item.state == "closed" else ""))
273
+ for line in said:
274
+ if any(re.search(rf"\b{re.escape(key)}\b", line) for key in numbers | idents):
275
+ print(f" NOTE on acceptance: {line}")
276
+
277
+
243
278
  def _tell(lines: list[str], head: str) -> None:
244
279
  """Said in the output; in GitHub Actions, also in the job's summary, and what was not shown as
245
280
  a warning a person sees on the run."""
@@ -121,7 +121,7 @@ def build_parser() -> argparse.ArgumentParser:
121
121
  lambda a: modules.create(a.root, a.name, a.owner, a.criticality, a.user_facing))
122
122
  nm.add_argument("name", help="module name, kebab-case")
123
123
  nm.add_argument("owner", help="GitHub team, organisation/team, or a user when the project has "
124
- "no organisation")
124
+ "no organisation — on GitHub, never an organisation's name alone")
125
125
  nm.add_argument("criticality", choices=list(assurance.CRITICALITIES),
126
126
  help="what a failure of this module costs — prototype: nothing, it is "
127
127
  "thrown away and nothing depends on it · standard: real code, no "
@@ -169,7 +169,8 @@ def build_parser() -> argparse.ArgumentParser:
169
169
  lambda a: pull_request.run(a.root, a.base, a.body_file, a.labels))
170
170
  pc.add_argument("--base", default="origin/main")
171
171
  pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
172
- pc.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS)")
172
+ pc.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
173
+ "token and one open pull request at the head, its own are read")
173
174
  ld = _add(sub, "landed", "what reached this branch outside a pull request, recorded (W1)",
174
175
  lambda a: landed.run(a.root, a.span, landed.from_environment(a.root)))
175
176
  ld.add_argument("--span", default="HEAD~1..HEAD",
@@ -178,7 +179,8 @@ def build_parser() -> argparse.ArgumentParser:
178
179
  lambda a: attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity, a.again))
179
180
  at.add_argument("--base", default="origin/main")
180
181
  at.add_argument("--body-file", type=Path, help="the pull request's description, for its checks")
181
- at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS)")
182
+ at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
183
+ "token and one open pull request at the head, its own are read")
182
184
  at.add_argument("--accept-identity", action="store_true",
183
185
  help="record under an identity the project's history does not show yet — a first record of yours")
184
186
  at.add_argument("--again", action="store_true",
@@ -207,7 +209,7 @@ def build_parser() -> argparse.ArgumentParser:
207
209
  dl.add_argument("--write-states", action="store_true", help="at a closure: writes the records' states in the cycle file, for its one pull request")
208
210
  bd = _add(sub, "board", "shows the cycles and their deliverables on the forge, one way: milestones and issues",
209
211
  lambda a: board.run(a.root, a.dry_run))
210
- bd.add_argument("--dry-run", action="store_true", help="say what would change, change nothing")
212
+ bd.add_argument("--dry-run", action="store_true", help="say what would change, change nothing — and preview what a proposed cycle's acceptance would create")
211
213
  ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent",
212
214
  lambda a: discovery.run(a.root, a.idea))
213
215
  ds.add_argument("idea", type=Path, help="the idea, a .md or .txt file")
@@ -250,7 +252,8 @@ def build_parser() -> argparse.ArgumentParser:
250
252
  ini.add_argument("--repository", help="the repository's path at another forge, group/name or "
251
253
  "group/subgroup/name (asked when absent)")
252
254
  ini.add_argument("--owner-team", help="owner of the foundation: organisation/team, or a user "
253
- "when the project has no organisation (asked when absent)")
255
+ "when the project has no organisation — on GitHub, never an "
256
+ "organisation's name alone (asked when absent)")
254
257
  ini.add_argument("--source", help="template: URL or path (default: the NapkinStack repository)")
255
258
  ini.add_argument("--ref", help="skeleton version: a tag vX.Y.Z, or a commit (default: the one of nstack)")
256
259
  ini.set_defaults(func=_init)
@@ -12,7 +12,8 @@ either: whether its default branch holds that commit (GITHUB_API_URL, otherwise
12
12
  https://api.github.com). No answer leaves L1 as it is.
13
13
 
14
14
  GitHub is read with a token supplied by a human (GH_TOKEN, otherwise GITHUB_TOKEN):
15
- fine-grained, limited to the repository, Administration: read permission (Actions: read for N2). Without a token,
15
+ fine-grained, limited to the repository, Administration: read permission (Actions: read for N2,
16
+ Contents: read for L10 on a private repository). Without a token,
16
17
  or when the API refuses a read, the setting is "not verified", never compliant. No write.
17
18
 
18
19
  Rules:
@@ -35,6 +36,10 @@ Rules:
35
36
  L9 the `forge` answer is the one the project's files were written for — never changed by
36
37
  hand, which Copier would misread; `nstack update --forge` changes it. A remote on another
37
38
  known public forge is said, never judged: a mirror is a choice
39
+ L10 on GitHub, every owner the code owners file names is one GitHub knows, read from GitHub's
40
+ own validation of the default branch's file (#382): an organisation by its bare name, a
41
+ deleted user or a team without access is no owner. Unread — a private repository and a token
42
+ without Contents: read — it is said, never counted
38
43
  N1 information, never a gap (D91): a published version newer than the project's, read from
39
44
  the registry — the one place a project learns of it. Elsewhere, only `nstack update` asks
40
45
  it, whether the version it lays is published yet (D201)
@@ -59,6 +64,7 @@ Output: 0 when everything is verified and compliant; 1 when a setting is missin
59
64
  from __future__ import annotations
60
65
 
61
66
  import fnmatch
67
+ import http.client
62
68
  import json
63
69
  import os
64
70
  import re
@@ -79,6 +85,7 @@ from napkinstack.project import ANSWERS
79
85
  OK, GAP, UNKNOWN, NOT_APPLICABLE = "OK", "FAIL", "NOT VERIFIED", "NOT APPLICABLE"
80
86
  SOURCES = "SOURCES" # a contributor's checkout holding the project's version: said, not a gap (D136)
81
87
  OUT_OF_REACH = "OUT OF REACH" # the plan forbids it: a state, not a fault (PDR-0006)
88
+ NOT_READ = "NOT READ" # an optional read that did not answer: said, never counted (L10)
82
89
  # The settings that make the forge refuse a merge. A repository is guarded when they are
83
90
  # all in force; the others matter and none of them stops a merge.
84
91
  BLOCKING = ("G1", "G2", "G3", "G4", "G12", "G13", "G21")
@@ -390,6 +397,40 @@ def _default_owner(root: Path) -> tuple[str, str]:
390
397
  "its first rule: the code owner review then covers every path (.nstack/handbook/07-governance.md §7).")
391
398
 
392
399
 
400
+ SHOWN_ERRORS = 5 # lines of GitHub's validation said one by one; the rest counted
401
+
402
+
403
+ def _owners_known(repo: str) -> tuple[str, str]:
404
+ """L10: the ownership file as GitHub validates it on the default branch (#382). An owner GitHub
405
+ does not know — an organisation by its bare name, a deleted user, a team without access — is
406
+ no owner: the paths it names have none. GitHub's own reading, not a second one: no syntax check
407
+ tells a user from an organisation. Unread, it is said and counted neither as a gap nor as
408
+ not verified: the token doctor asks for reads settings, not contents."""
409
+ api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/")
410
+ token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
411
+ headers = {"Accept": "application/vnd.github+json", "X-GitHub-Api-Version": API_VERSION,
412
+ "User-Agent": f"nstack/{__version__}"}
413
+ if token:
414
+ headers["Authorization"] = f"Bearer {token}"
415
+ request = urllib.request.Request(f"{api}/repos/{repo}/codeowners/errors", headers=headers)
416
+ try:
417
+ with urllib.request.urlopen(request, timeout=10) as response:
418
+ errors = json.load(response)["errors"]
419
+ lines = [f"line {error['line']}: {error['kind']} — {str(error['source']).strip()}" for error in errors]
420
+ except (OSError, ValueError, KeyError, TypeError, http.client.HTTPException) as error:
421
+ said = f"HTTP {error.code}" if isinstance(error, urllib.error.HTTPError) else type(error).__name__
422
+ return NOT_READ, (f"Reason: GitHub's validation of the file did not answer ({said}): no file on the "
423
+ "default branch, or a private repository out of the token's reach.\nTo read it: a "
424
+ "token that may also read the repository's contents (Contents: read).")
425
+ if not lines:
426
+ return OK, ""
427
+ more = f"\n…and {len(lines) - SHOWN_ERRORS} more" if len(lines) > SHOWN_ERRORS else ""
428
+ return GAP, ("GitHub reads no valid owner on these lines of the default branch's file:\n"
429
+ + "\n".join(lines[:SHOWN_ERRORS]) + more
430
+ + "\nAction: name a user, or a team written organisation/team, with write access to the "
431
+ "repository — never an organisation by its name (.nstack/handbook/07-governance.md §7).")
432
+
433
+
393
434
  def _kept_for_a_human(root: Path, shown: str, text: str) -> tuple[str, str]:
394
435
  """L6 on `approval: agent`: no default owner, and every path a human must approve ends on a
395
436
  rule with an owner (`owners.py`; in CI, rule M13)."""
@@ -522,14 +563,18 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
522
563
  if answers.get("approval") == "agent" else "CODEOWNERS starts with a default owner",
523
564
  *_default_owner(root)))
524
565
 
566
+ from napkinstack.project import forge, remote_forge, written_for
567
+
568
+ if forge(root) == "github":
569
+ results.append(("L10", "Every owner CODEOWNERS names is one GitHub knows",
570
+ *_owners_known(str(answers.get("github_repo") or ""))))
571
+
525
572
  source = str(answers.get("_src_path") or "")
526
573
  local = not REMOTE.match(source)
527
574
  results.append(("L7", "Template source reachable by anyone", GAP if local else OK,
528
575
  f"The project was generated from '{source}', a path on one machine: nobody else can "
529
576
  "update it.\nAction: nstack update, from the published source." if local else ""))
530
577
 
531
- from napkinstack.project import forge, remote_forge, written_for
532
-
533
578
  name = forge(root)
534
579
  written, remote = written_for(root), remote_forge(root)
535
580
  if written is not None:
@@ -798,6 +843,8 @@ def run(root: Path) -> int:
798
843
  suffix = f", {skipped} not applicable" if skipped else ""
799
844
  if not gaps and not unknown:
800
845
  reach = f"; {out_of_reach} setting(s) out of reach on this plan" if out_of_reach else ""
846
+ unread = [rule for rule, _, status, _ in results if status == NOT_READ]
847
+ reach += f"; {', '.join(unread)} not read" if unread else ""
801
848
  print(f"\nnstack doctor: compliant{suffix}{reach}.")
802
849
  return 0
803
850
  print(f"\nnstack doctor: {gaps} gap(s), {unknown} not verified{suffix}.\nWorkflows inform; "
@@ -266,15 +266,34 @@ def prepare(root: Path, module: Path) -> Path | str:
266
266
 
267
267
 
268
268
  HELD = "NSTACK_E2E_HELD" # set for what the run starts: an e2e inside an e2e waits for nothing
269
+ WAIT_SAID_EVERY = 60.0 # seconds between two lines of a run that waits: a long wait is never read as a hang (#402)
270
+
271
+
272
+ def sealed(manifest: Path) -> bool:
273
+ """Whether the module declares its end-to-end run sealed, `evidence.sealed: true` (#402): its own
274
+ session, devices, ports, the files it writes and its processes, and timings that hold whatever the load
275
+ (#419) — nothing another run shares."""
276
+ try:
277
+ data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
278
+ except (OSError, yaml.YAMLError):
279
+ return False
280
+ section = data.get("evidence") if isinstance(data, dict) else None
281
+ return isinstance(section, dict) and section.get("sealed") is True
269
282
 
270
283
 
271
284
  @contextlib.contextmanager
272
- def one_at_a_time(root: Path, target: str):
285
+ def one_at_a_time(root: Path, target: str, is_sealed: bool = False):
273
286
  """One e2e at a time on this machine, for this user, whichever project or command starts it —
274
287
  `nstack e2e`, or `nstack attest` through it: what an end-to-end run drives (a sound server, a
275
288
  display, a port) is the machine's, and two runs reading it see each other's (#287). An advisory
276
289
  lock, `flock(2)`, released by the system when the holder exits however it exits; the one that
277
- waits says for whom."""
290
+ waits says for whom, and again every WAIT_SAID_EVERY seconds. A sealed run shares nothing of the
291
+ machine's: it neither waits nor holds the lock (#402)."""
292
+ if is_sealed:
293
+ print(f"-> {target}: sealed (evidence.sealed): runs beside any other end-to-end run on this machine",
294
+ flush=True)
295
+ yield
296
+ return
278
297
  try:
279
298
  import fcntl
280
299
  except ImportError: # no flock on this system: the runs are not kept apart
@@ -299,7 +318,19 @@ def one_at_a_time(root: Path, target: str):
299
318
  handle.seek(0)
300
319
  holder = handle.read().strip() or "another run"
301
320
  print(f"-> {target}: waits for the end-to-end run already on this machine — {holder}", flush=True)
302
- fcntl.flock(handle, fcntl.LOCK_EX)
321
+ began = said = time.monotonic()
322
+ while True:
323
+ try:
324
+ fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
325
+ break
326
+ except BlockingIOError:
327
+ time.sleep(min(1.0, WAIT_SAID_EVERY / 3))
328
+ if time.monotonic() - said >= WAIT_SAID_EVERY:
329
+ said = time.monotonic()
330
+ handle.seek(0)
331
+ holder = handle.read().strip() or holder
332
+ print(f"-> {target}: still waits for the end-to-end run already on this machine, "
333
+ f"{int(said - began) // 60} min {int(said - began) % 60} s so far — {holder}", flush=True)
303
334
  handle.seek(0)
304
335
  handle.truncate()
305
336
  started = datetime.datetime.now().astimezone().isoformat(timespec="seconds")
@@ -385,7 +385,7 @@ def declared_evidence(manifests: list[Path], root: Path) -> None:
385
385
  continue # absent, or not a mapping: M2 says it
386
386
  name, at = manifest.parent.name, f"{manifest.relative_to(root).as_posix()}:{line_of(text, 'evidence')}"
387
387
  action = " Action: evidence.provoked — a list of {pattern, level: warning|error, scenario} (.nstack/playbooks/tests.md)."
388
- for key in sorted(set(section) - {"provoked", "levels"}):
388
+ for key in sorted(set(section) - {"provoked", "levels", "sealed"}):
389
389
  fail(name, "M12", f"evidence has an unknown key '{key}': it declares nothing.\n{action}", at)
390
390
  provoked = section.get("provoked", [])
391
391
  if not isinstance(provoked, list):
@@ -410,6 +410,11 @@ def declared_evidence(manifests: list[Path], root: Path) -> None:
410
410
  fail(name, "M12", f"level {item['level']!r}: warning or error.\n{action}", at)
411
411
  if not isinstance(item["scenario"], str) or not item["scenario"].strip():
412
412
  fail(name, "M12", f"the declaration of {item['pattern']!r} names no scenario: say which provokes it.\n{action}", at)
413
+ if "sealed" in section and not isinstance(section["sealed"], bool):
414
+ fail(name, "M12", "evidence.sealed must be true or false: true when the module's end-to-end run shares "
415
+ "nothing with another run — session, devices, ports, files it writes, processes — and "
416
+ "passes whatever the machine's load.\n Action: evidence.sealed: true or false, or no key: the run then waits "
417
+ "its turn (.nstack/playbooks/tests.md).", at)
413
418
  if "levels" in section and not isinstance(section["levels"], str):
414
419
  fail(name, "M12", "evidence.levels must be text, a regular expression.\n"
415
420
  " Action: an expression whose group named level captures the line's level word.", at)
@@ -9,7 +9,7 @@ Rules:
9
9
  C1 front matter readable: a YAML mapping at the top of the file
10
10
  C2 charter: status proposed or accepted, a decider who is one named person, at least
11
11
  one success criterion
12
- C3 cycle: a goal, a known status, appetite_weeks, start and end, end = start + appetite;
12
+ C3 cycle: a goal, a known status, appetite_weeks or appetite_days, start and end, end = start + appetite;
13
13
  accepted_on, when written, a date: the next cycle's acceptance while another runs
14
14
  C4 deliverables: ids D1, D2… unique, a title, a known state, acceptance criteria once ready
15
15
  C5 at most one accepted cycle, and only under an accepted charter
@@ -621,6 +621,9 @@ def _check_success(path: Path, data: dict, status, numbers: list[int] | None, fa
621
621
  fail("C6", path, f"{where}: observing since when? {action}")
622
622
 
623
623
 
624
+ APPETITES = {"appetite_weeks": "weeks", "appetite_days": "days"} # a cycle's key, and its unit
625
+
626
+
624
627
  def _check_cycle(path: Path, fail, numbers: list[int] | None = None) -> str | None:
625
628
  data, reason = read_front_matter(path)
626
629
  if data is None:
@@ -631,16 +634,25 @@ def _check_cycle(path: Path, fail, numbers: list[int] | None = None) -> str | No
631
634
  status = data.get("status")
632
635
  if not one_of(status, CYCLE_STATUSES):
633
636
  fail("C3", path, f"status '{status}': expected one of {sorted(CYCLE_STATUSES)}")
634
- weeks = data.get("appetite_weeks")
635
- if isinstance(weeks, bool) or not isinstance(weeks, int) or weeks < 1:
636
- fail("C3", path, "appetite_weeks: a whole number of weeks, decided rather than estimated")
637
- weeks = None
637
+ # The appetite in weeks, or in days for an engagement shorter than one (#370): one or the
638
+ # other, never both — one decision, and the one date it sets.
639
+ given = [unit for unit in APPETITES if data.get(unit) is not None] # a key left empty is no appetite
640
+ unit = given[0] if len(given) == 1 else None
641
+ amount = data.get(unit) if unit else None
642
+ if len(given) > 1:
643
+ fail("C3", path, "appetite_weeks and appetite_days both set: the appetite is one decision.\n"
644
+ " Action: keep one — appetite_days for a cycle shorter than a week")
645
+ amount = None
646
+ elif isinstance(amount, bool) or not isinstance(amount, int) or amount < 1:
647
+ fail("C3", path, "appetite_weeks, or appetite_days for a cycle counted in days: a whole number of at "
648
+ "least 1, decided rather than estimated")
649
+ amount = None
638
650
  start, end = as_date(data.get("start")), as_date(data.get("end"))
639
651
  if start is None or end is None:
640
652
  fail("C3", path, "start and end: dates, YYYY-MM-DD")
641
- elif weeks is not None and end != start + datetime.timedelta(weeks=weeks):
642
- fail("C3", path, f"end {end}: the appetite sets it, start + {weeks} week(s) = "
643
- f"{start + datetime.timedelta(weeks=weeks)}")
653
+ elif amount is not None and end != start + datetime.timedelta(**{APPETITES[unit]: amount}):
654
+ fail("C3", path, f"end {end}: the appetite sets it, start + {amount} {APPETITES[unit][:-1]}(s) = "
655
+ f"{start + datetime.timedelta(**{APPETITES[unit]: amount})}")
644
656
  if "accepted_on" in data and as_date(data.get("accepted_on")) is None:
645
657
  fail("C3", path, "accepted_on: the day the decider accepted this cycle, YYYY-MM-DD")
646
658
  _check_deliverables(path, data.get("deliverables"), fail)
@@ -20,7 +20,7 @@ from pathlib import Path
20
20
  import yaml
21
21
 
22
22
  from napkinstack import assurance
23
- from napkinstack.project import answer, forge, ownership
23
+ from napkinstack.project import answer, forge, organisation_owner, ownership
24
24
  from napkinstack.fitness.manifests import (changed_files, contract_entries, find_manifests,
25
25
  module_content)
26
26
 
@@ -73,6 +73,8 @@ def create(root: Path, name: str, owner: str, criticality: str, user_facing: boo
73
73
  "GitLab group/subgroup off GitHub — or a user when the project has no organisation, for "
74
74
  "example acme/billing (CODEOWNERS, .nstack/handbook/07-governance.md §7).")
75
75
  return 1
76
+ if forge(root) == "github" and organisation_owner(owner, "new-module", f"{owner}/<team>"):
77
+ return 1
76
78
  folder = root / "modules" / name
77
79
  if folder.exists():
78
80
  print(f"FAIL [new-module] modules/{name} already exists.")
@@ -160,18 +162,20 @@ def create_contract(root: Path, name: str, owner: str | None = None) -> int:
160
162
  except (OSError, yaml.YAMLError):
161
163
  answers = {}
162
164
  owner = owner or str(answers.get("owner_team") or "")
163
- if not owner_valid(root, owner):
165
+ module, folder = root / "contracts", root / "contracts" / name
166
+ created = not (module / "MANIFEST.yaml").is_file() # the owner is written only with the module
167
+ if created and not owner_valid(root, owner):
164
168
  print(f"FAIL [new-contract] no valid owner for the contracts module ('{owner}').\n"
165
169
  " Action: pass --owner organisation/team — a boundary is never orphaned "
166
170
  "(.nstack/handbook/03-contracts.md §2).")
167
171
  return 1
168
- module, folder = root / "contracts", root / "contracts" / name
172
+ if created and forge(root) == "github" and organisation_owner(owner, "new-contract", f"--owner {owner}/<team>"):
173
+ return 1
169
174
  if folder.exists():
170
175
  print(f"FAIL [new-contract] contracts/{name} already exists.\n Action: a change to it is a new "
171
176
  "version beside the first, never an edit of it (.nstack/handbook/03-contracts.md §4).")
172
177
  return 1
173
178
 
174
- created = not (module / "MANIFEST.yaml").is_file()
175
179
  if created:
176
180
  shutil.copytree(CONTRACTS, module, dirs_exist_ok=True)
177
181
  # The contact: the project's discussions on GitHub; elsewhere, the module's owner (ADR-0010).
@@ -392,13 +396,17 @@ def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | Non
392
396
  # Its evidence: a folder of its own, its output kept, its logs read after (ADR-0009).
393
397
  from napkinstack import evidence
394
398
 
395
- with evidence.one_at_a_time(root, target):
399
+ sealed = evidence.sealed(manifest)
400
+ # HELD says an ancestor holds the machine: a sealed run holds nothing, so what it starts
401
+ # does not inherit it — a run it nests waits as any other would (#402).
402
+ held_for_children = {} if sealed else {evidence.HELD: "1"}
403
+ with evidence.one_at_a_time(root, target, is_sealed=sealed):
396
404
  folder = evidence.prepare(root, known[target])
397
405
  if isinstance(folder, str):
398
406
  print(f"FAIL [e2e] module '{target}': {folder}")
399
407
  return 1
400
408
  print(f"-> {target}: {command}", flush=True)
401
- code, held = evidence.run(command, known[target], {**os.environ, evidence.HELD: "1",
409
+ code, held = evidence.run(command, known[target], {**os.environ, **held_for_children,
402
410
  "NSTACK_EVIDENCE": str(folder.resolve())}, folder)
403
411
  passed = evidence.finish(root, target, known[target], folder, code, held)
404
412
  if code == evidence.NOT_RUN and passed:
@@ -12,11 +12,14 @@ hook and CI reject any remaining marker.
12
12
 
13
13
  from __future__ import annotations
14
14
 
15
+ import json
15
16
  import os
16
17
  import re
17
18
  import subprocess
18
19
  import sys
19
20
  import tempfile
21
+ import urllib.parse
22
+ import urllib.request
20
23
  from pathlib import Path
21
24
 
22
25
  import yaml
@@ -30,6 +33,47 @@ DOWNGRADE = re.compile(r"You are downgrading from (\S+) to (\S+)\.")
30
33
  GITHUB = re.compile(r"^(?:https://github\.com/|git@github\.com:|gh:)(?P<repo>[^/]+/[^/]+?)(?:\.git)?/?$")
31
34
 
32
35
 
36
+ def organisation_owner(owner: str, command: str, instead: str) -> bool:
37
+ """True, with the refusal printed, when a bare handle written as a code owner on GitHub names an
38
+ organisation (#382): GitHub takes a user, or a team as organisation/team — never an organisation
39
+ by its name, and every CODEOWNERS line naming it would have no valid owner. A team needs no
40
+ asking; a forge that does not answer lets the owner pass, said: `nstack doctor` reads the file as
41
+ GitHub validates it (L10). A token is sent when there is one: a server in private mode answers
42
+ no one without it."""
43
+ import http.client
44
+ import urllib.error
45
+
46
+ if "/" in owner:
47
+ return False
48
+ api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/")
49
+ headers = {"Accept": "application/vnd.github+json", "User-Agent": f"nstack/{__version__}"}
50
+ if token := os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN"):
51
+ headers["Authorization"] = f"Bearer {token}"
52
+ request = urllib.request.Request(f"{api}/users/{urllib.parse.quote(owner, safe='')}", headers=headers)
53
+ try:
54
+ with urllib.request.urlopen(request, timeout=5) as response:
55
+ kind = (json.load(response) or {}).get("type")
56
+ except urllib.error.HTTPError as error:
57
+ kind = "unknown" if error.code == 404 else None
58
+ except (OSError, ValueError, AttributeError, http.client.HTTPException):
59
+ kind = None
60
+ if kind == "unknown":
61
+ print(f"NOTE [{command}] GitHub knows no user or organisation '{owner}': written as given — check the "
62
+ "spelling; nstack doctor reads the file as GitHub validates it.")
63
+ return False
64
+ if kind == "Organization":
65
+ print(f"FAIL [{command}] '{owner}' is an organisation: GitHub takes as a code owner a user, or a team "
66
+ f"written organisation/team — never an organisation by its name. Every CODEOWNERS line naming "
67
+ f"it would name no valid owner.\n Action: pass {instead} — a team of {owner} with write "
68
+ "access to the repository — or a user (.nstack/handbook/07-governance.md §7).")
69
+ return True
70
+ if kind is None:
71
+ print(f"NOTE [{command}] GitHub did not say what '{owner}' names: written as given. A code owner is a "
72
+ "user or organisation/team, never an organisation's name; nstack doctor reads the file as GitHub "
73
+ "validates it.")
74
+ return False
75
+
76
+
33
77
  def default_ref() -> str:
34
78
  """The skeleton of the engine version: they move up together (PDR-0001 R2)."""
35
79
  return f"v{__version__}"
@@ -233,6 +277,11 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
233
277
  # Not asked at init (Copier would ask): a project on GitHub starts on its CI; elsewhere no CI
234
278
  # is shipped, and its checks are attested (PDR-0018) — settled after the copy when the forge
235
279
  # was asked by Copier itself.
280
+ # Asked by Copier instead — the owner, or the forge —, the owner is read by nstack doctor (L10):
281
+ # a prompt cannot ask the forge.
282
+ owner = str(data.get("owner_team") or "")
283
+ if data.get("forge") == "github" and owner and organisation_owner(owner, "init", f"--owner-team {owner}/<team>"):
284
+ return 1
236
285
  data.setdefault("checks", "forge" if named == "github" else "attested")
237
286
  data.setdefault("hold_days", 7) # a hold goes stale after a week without work (ADR-0007)
238
287
  data.setdefault("approval", "human") # a code owner approves, until the decider says otherwise (PDR-0021)
@@ -32,7 +32,9 @@ The out-of-cycle label lifts K1 to K3 and K5, visibly and countably (.nstack/han
32
32
 
33
33
  Usage : nstack pr-check [--root ROOT] [--base BASE] [--body-file FILE] [--labels a,b]
34
34
  In CI : PR_BODY, PR_LABELS, PR_HEAD_SHA and PR_AUTHOR come from the pull_request event;
35
- --labels, when given, takes the place of PR_LABELS, as for nstack attest.
35
+ --labels, when given, takes the place of PR_LABELS, as for nstack attest. Elsewhere, with
36
+ a token and one open pull request at the head, its own labels are read, and a label
37
+ given that it does not carry is refused (#368).
36
38
 
37
39
  The verifier (T2) is a person, `@handle`, or an agent session, `session <id>`. The change's
38
40
  authors are the pull request's author, the GitHub accounts behind its commits' authors,
@@ -276,11 +278,10 @@ TRACES = """query($owner: String!, $name: String!, $number: Int!) {
276
278
  userContentEdits(first: 100) { totalCount nodes { editor { login } } } } } }"""
277
279
 
278
280
 
279
- def traces(root: Path) -> set[str] | str | None:
280
- """The accounts whose hand is on the pull request — its description's editors, its reviewers,
281
- its commenters —, lower case and without `[bot]`; why they are not read; None with no pull
282
- request number, on a workstation, and while `nstack attest` records the head: the hand is
283
- judged on the forge's run, which an edit of the description starts again."""
281
+ def _pull_request(root: Path, query: str) -> dict | str | None:
282
+ """The pull request as one GraphQL query reads it; why it is not read; None with no pull
283
+ request number, on a workstation, and while `nstack attest` records the head: what the forge
284
+ holds is judged on the forge's own run."""
284
285
  number = os.environ.get("PR_NUMBER", "").strip()
285
286
  if not re.fullmatch(r"[0-9]+", number) or os.environ.get("NSTACK_ATTESTING"):
286
287
  return None
@@ -291,7 +292,7 @@ def traces(root: Path) -> set[str] | str | None:
291
292
  owner, name = repository.split("/", 1)
292
293
  request = urllib.request.Request(
293
294
  os.environ.get("GITHUB_GRAPHQL_URL") or "https://api.github.com/graphql",
294
- data=json.dumps({"query": TRACES, "variables": {"owner": owner, "name": name, "number": int(number)}}).encode(),
295
+ data=json.dumps({"query": query, "variables": {"owner": owner, "name": name, "number": int(number)}}).encode(),
295
296
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", "User-Agent": "nstack"})
296
297
  try:
297
298
  with urllib.request.urlopen(request, timeout=10) as response:
@@ -299,16 +300,85 @@ def traces(root: Path) -> set[str] | str | None:
299
300
  if answer.get("errors"): # a field refused leaves the rest of the answer partial
300
301
  return f"the forge refused part of the query ({answer['errors'][0].get('type', 'error')})"
301
302
  found = answer["data"]["repository"]["pullRequest"]
303
+ return found if isinstance(found, dict) else "the forge did not answer (no pull request)"
304
+ except (OSError, ValueError, KeyError, TypeError, AttributeError, IndexError) as error:
305
+ return f"the forge did not answer ({type(error).__name__})"
306
+
307
+
308
+ def traces(root: Path) -> set[str] | str | None:
309
+ """The accounts whose hand is on the pull request — its description's editors, its reviewers,
310
+ its commenters —, lower case and without `[bot]`; why they are not read; None where the pull
311
+ request is not read (`_pull_request`): the hand is judged on the forge's run, which an edit of
312
+ the description starts again."""
313
+ found = _pull_request(root, TRACES)
314
+ if not isinstance(found, dict):
315
+ return found
316
+ try:
302
317
  hands = [(found[kind], key) for kind, key in (("reviews", "author"), ("comments", "author"),
303
318
  ("userContentEdits", "editor"))]
304
319
  if any(connection["totalCount"] > len(connection["nodes"]) for connection, _ in hands):
305
320
  return "more traces than one page"
306
321
  return {node[key]["login"].lower().removesuffix("[bot]") for connection, key in hands
307
322
  for node in connection["nodes"] if node and node.get(key)}
308
- except (OSError, ValueError, KeyError, TypeError, AttributeError, IndexError) as error:
323
+ except (KeyError, TypeError, AttributeError) as error:
309
324
  return f"the forge did not answer ({type(error).__name__})"
310
325
 
311
326
 
327
+ # Each reviewer's latest review that approved or asked for changes: a dismissed one is not APPROVED,
328
+ # so where the forge dismisses stale approvals (G13) none is ever read here as covering the head.
329
+ APPROVALS = """query($owner: String!, $name: String!, $number: Int!) {
330
+ repository(owner: $owner, name: $name) { pullRequest(number: $number) {
331
+ latestOpinionatedReviews(first: 100) { totalCount nodes { state author { login } commit { oid } } } } } }"""
332
+
333
+
334
+ def approvals(root: Path) -> list[tuple[str, str]] | str | None:
335
+ """Each approving reviewer's login and the commit their approval was given on; why they are not
336
+ read; None where the pull request is not read (`_pull_request`)."""
337
+ found = _pull_request(root, APPROVALS)
338
+ if not isinstance(found, dict):
339
+ return found
340
+ try:
341
+ reviews = found["latestOpinionatedReviews"]
342
+ if reviews["totalCount"] > len(reviews["nodes"]):
343
+ return "more reviewers than one page"
344
+ return [(node["author"]["login"] if node.get("author") else "a deleted account",
345
+ str((node.get("commit") or {}).get("oid") or "").lower())
346
+ for node in reviews["nodes"] if node and node.get("state") == "APPROVED"]
347
+ except (KeyError, TypeError, AttributeError) as error:
348
+ return f"the forge did not answer ({type(error).__name__})"
349
+
350
+
351
+ def check_approvals(root: Path, base: str, head: str, found: list[tuple[str, str]] | str | None,
352
+ warn: Callable[[str], None]) -> None:
353
+ """R1 (#377): where the forge keeps an approval once new commits are pushed — no ruleset, or
354
+ stale approvals not dismissed —, "approved" no longer says the head was read. An approval on
355
+ an earlier commit covers the head when only the base branch was merged in since; otherwise it
356
+ is said, with whom and which commits. A warning, never a failure: a review starts no run (D218),
357
+ so a check failed on it would stay red after the approver read the head and approved again."""
358
+ if isinstance(found, str):
359
+ warn(f"[R1] whether each approval covers the head is not read: {found}.")
360
+ return
361
+ for login, commit in found or []:
362
+ if commit == head:
363
+ continue
364
+ known = bool(commit) and not _git(root, "merge-base", "--is-ancestor", commit, head).returncode
365
+ since = _git(root, "rev-list", f"{commit}..{head}", f"^{base}").stdout.split() if known else []
366
+ # A merge counts when it carries content of its own — a conflict resolved, an edit made
367
+ # while merging —: what a clean merge of the base would not have written.
368
+ since = [one for one in since if _git(root, "rev-list", "--no-walk", "--merges", one).stdout.strip() == ""
369
+ or _git(root, "show", "--remerge-diff", "--format=", one).stdout.strip()]
370
+ if known and not since:
371
+ continue # only the base branch merged in: nothing the approver has not read
372
+ what = (f"{len(since)} commit(s) pushed since" if known
373
+ else "a commit this branch does not hold — rewritten since, or not found here")
374
+ line = (f"[R1] @{login} approved {commit[:7] or 'an unknown commit'}, not the head {head[:7]}, at this run: "
375
+ f"{what}, which the approval does not cover.")
376
+ warn(f"{line}\n Action: @{login} reads them and approves again before the merge; where the forge "
377
+ "dismisses stale approvals on push, it does this itself (.nstack/handbook/07-governance.md §7).")
378
+ if os.environ.get("GITHUB_ACTIONS") == "true": # seen on the check, not only in its log
379
+ print(f"::warning title=R1 approval behind the head::{line.removeprefix('[R1] ')}")
380
+
381
+
312
382
  def check_verifier(verifier: str, authorship: tuple[set[str], set[str], list[str]], fail: Fail,
313
383
  hands: set[str] | None = None) -> None:
314
384
  """T2: the verifier is named — people as @handle anywhere on the line, an agent session as
@@ -360,7 +430,7 @@ def _split(row: dict, width: int) -> bool:
360
430
  def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
361
431
  authorship: tuple[set[str], set[str], list[str]] = (set(), set(), []),
362
432
  strict: bool = False, unchanged: Callable[[str], bool] = lambda commit: False,
363
- hands: set[str] | None = None) -> list[str]:
433
+ hands: set[str] | None = None, same_inputs: Callable[[str], bool] = lambda commit: False) -> list[str]:
364
434
  """T1 to T5; returns the human-only scenarios, listed apart for the approver."""
365
435
  verifier, header, rows = read_sheet(body)
366
436
  if reasons and not rows:
@@ -416,7 +486,9 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
416
486
  # joins an earlier one after a `;`, never replacing it (#288).
417
487
  confirmed = [clause.strip().split(" ", 1)[0].strip("`").lower()
418
488
  for clause in row.get(CONFIRMED, "").split(";")]
419
- if kind.lower() == "automated" or strict:
489
+ if kind.lower() == "automated" and not strict and same_inputs(commit):
490
+ pass # what its module reads is unchanged since that run, and the run is fresh (D223)
491
+ elif kind.lower() == "automated" or strict:
420
492
  rerun.append(ident)
421
493
  elif not any(SHA.fullmatch(commit) and head.startswith(commit) for commit in confirmed):
422
494
  unconfirmed.append(ident)
@@ -490,8 +562,8 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
490
562
  fail("K3", f"no deliverable named.\n Action: \"Deliverable: D<n>\" in the description, "
491
563
  f"a deliverable of {path.name}."
492
564
  + ("" if labels else f"\n This run read no label. If the pull request is out of cycle, it "
493
- f"carries the {LABEL} label; a run on a workstation is given it with --labels {LABEL} "
494
- "(or PR_LABELS), as the forge passes its labels."))
565
+ f"carries the {LABEL} label, put on the pull request: a run on a workstation reads it there "
566
+ f"with a token, or is given it with --labels {LABEL} (or PR_LABELS)."))
495
567
  elif match[1] not in states:
496
568
  fail("K3", f"deliverable {match[1]} is not in {path.name}.\n Action: name one of "
497
569
  f"{', '.join(states) or 'its deliverables'}, or re-frame the cycle with the decider.")
@@ -631,6 +703,51 @@ def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, wa
631
703
  "description; restore it from the description's history otherwise.")
632
704
 
633
705
 
706
+ def _pull_labels(root: Path, head: str) -> tuple[int, set[str]] | str | None:
707
+ """The open pull request whose head is `head`, and its labels, read on the forge (#368); why not,
708
+ when it was asked; None when nothing is asked: off GitHub or without a token, and where the
709
+ labels given are already the pull request's — the forge's own run, and the checks nstack attest
710
+ runs with the labels it read."""
711
+ if os.environ.get("GITHUB_ACTIONS") == "true" or os.environ.get("NSTACK_ATTESTING") == head:
712
+ return None
713
+ from napkinstack import attest, hold
714
+
715
+ forge = hold._forge(root, attest._remote(root) or "origin")
716
+ if forge is None:
717
+ return None
718
+ try:
719
+ answer = hold._call(forge, "GET", f"/commits/{head}/pulls")
720
+ except hold.Refused as error:
721
+ return str(error)
722
+ pulls = [pull for pull in answer if isinstance(pull, dict) and pull.get("state") == "open"
723
+ and isinstance(pull.get("head"), dict) and pull["head"].get("sha") == head] if isinstance(answer, list) else []
724
+ if len(pulls) != 1:
725
+ return "no open pull request has this head" if not pulls else f"{len(pulls)} open pull requests have this head"
726
+ names = {str(label["name"]) for label in pulls[0].get("labels") or [] if isinstance(label, dict) and label.get("name")}
727
+ return int(pulls[0].get("number") or 0), names
728
+
729
+
730
+ def labels_for(root: Path, head: str, given: str) -> tuple[set[str], str, str | None]:
731
+ """The labels judged, where they come from, and a refusal: the pull request's own when it is read
732
+ — a label given that it does not carry is refused, since a label is what the reviewer sees on the
733
+ forge (#368); else the ones given, said as the caller's."""
734
+ named = {label.strip() for label in given.split(",") if label.strip()}
735
+ found = _pull_labels(root, head)
736
+ if isinstance(found, tuple):
737
+ number, carried = found
738
+ if extra := sorted(name for name in named if name.lower() not in {label.lower() for label in carried}):
739
+ return named, "", (f"pull request #{number} carries no label {', '.join(extra)}: a label is judged as the "
740
+ f"reviewer sees it on the forge.\n Action: put it on pull request #{number}, or "
741
+ "run without --labels and with PR_LABELS unset: the pull request's own are read.")
742
+ return carried, f"read from pull request #{number}", None
743
+ if os.environ.get("GITHUB_ACTIONS") == "true":
744
+ return named, "the pull request event's", None
745
+ if os.environ.get("NSTACK_ATTESTING") == head:
746
+ return named, "as nstack attest read them", None
747
+ return named, ("given by the caller (--labels, PR_LABELS)" if named else "none given") + (
748
+ f" — the pull request's not read: {found}" if found else ""), None
749
+
750
+
634
751
  def status_required(root: Path) -> bool:
635
752
  """Whether the base branch's rules require the record's own status, `nstack / local checks`
636
753
  (D221, #399): read on the forge's run only, from the rules that apply to the branch — readable
@@ -660,6 +777,50 @@ def status_required(root: Path) -> bool:
660
777
  for rule in rules if isinstance(rules, list))
661
778
 
662
779
 
780
+ def _module_inputs(record: dict | None) -> tuple[str, str, str | None] | None:
781
+ """A record's `Module checks` digest, its first run's time and base (ADR-0006, D223)."""
782
+ checks = record.get("checks") if isinstance(record, dict) and isinstance(record.get("checks"), list) else []
783
+ found = next((c for c in checks if isinstance(c, dict) and c.get("name") == "Module checks"), None)
784
+ if not found or found.get("passed") is not True or not found.get("inputs"):
785
+ return None
786
+ return str(found["inputs"]), str(found.get("kept_from") or record.get("at", "")), \
787
+ found.get("kept_base") or record.get("base_commit")
788
+
789
+
790
+ def same_inputs(root: Path, head: str, base: str) -> Callable[[str], bool]:
791
+ """T4's relief for an automated row (D223): the record of the row's commit and the head's hold
792
+ the same inputs digest, and the row's run is fresh. While nstack attest makes the head's record,
793
+ the digest it computed stands in for it."""
794
+ from napkinstack import attest
795
+
796
+ try:
797
+ answers = yaml.safe_load((root / ANSWERS).read_text(encoding="utf-8")) or {}
798
+ except (OSError, yaml.YAMLError):
799
+ answers = {}
800
+ if not isinstance(answers, dict) or answers.get("checks") != "attested":
801
+ return lambda commit: False # the forge's CI replays it: the relief is for attested checks
802
+ cache: dict[str, str | None] = {}
803
+
804
+ def head_digest() -> str | None:
805
+ if "head" not in cache:
806
+ if os.environ.get("NSTACK_ATTESTING") == head:
807
+ cache["head"] = os.environ.get("NSTACK_INPUTS") or None
808
+ else:
809
+ attest.read_remote(root)
810
+ found = _module_inputs(attest.latest(root, head))
811
+ cache["head"] = found[0] if found else None
812
+ return cache["head"]
813
+
814
+ def same(commit: str) -> bool:
815
+ full = _git(root, "rev-parse", "--verify", "--quiet", f"{commit}^{{commit}}").stdout.strip()
816
+ digest = head_digest()
817
+ found = _module_inputs(attest.latest(root, full)) if full and digest else None
818
+ base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}").stdout.strip() or None
819
+ return bool(found and found[0] == digest and attest._fresh(root, found[1], found[2], base_commit))
820
+
821
+ return same
822
+
823
+
663
824
  def check_attested(root: Path, head: str, fail, warn=lambda message: None) -> str:
664
825
  """Where the checks are judged, as the decider's answer `checks` says (A1, A2): on the forge's
665
826
  CI, or attested on a workstation by `nstack attest` — then a complete, passed record of the
@@ -738,7 +899,7 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
738
899
  modules = touched_modules(root, fork, files)
739
900
  # The option, else PR_LABELS: one way for pr-check and attest alike (D147).
740
901
  given = os.environ.get("PR_LABELS", "") if labels_given is None else labels_given
741
- labels = {label.strip() for label in given.split(",") if label.strip()}
902
+ labels, labels_from, refused = labels_for(root, head, given)
742
903
 
743
904
  failures: list[str] = []
744
905
  warnings = charter_without_pdr(root, base, files)
@@ -746,6 +907,9 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
746
907
  def fail(rule: str, message: str) -> None:
747
908
  failures.append(f"[{rule}] {message}")
748
909
 
910
+ if refused:
911
+ fail("labels", refused)
912
+
749
913
  reasons = [reason for folder, found in modules.items() if (reason := sheet_reason(folder, found))]
750
914
  authorship = authors(root, base, head, os.environ.get("PR_AUTHOR", ""))
751
915
  # A commit whose tree is the head's is the head, for a sheet (D93): merging the default
@@ -764,11 +928,13 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
764
928
  f"request is not read: {hands}.")
765
929
  human_only = check_sheet(body, head, reasons, fail, authorship, rerun_at_head(modules),
766
930
  lambda commit: bool(tree_of(commit)) and tree_of(commit) == tree_of(head),
767
- hands if isinstance(hands, set) else None) if carried else []
931
+ hands if isinstance(hands, set) else None, same_inputs(root, head, base)) if carried else []
768
932
  if modules:
769
933
  check_cycle(root, body, labels, datetime.date.today(), fail, warnings.append)
770
934
  check_hold(root, body, labels, authorship, fail, warnings.append, identities(root, base, head))
771
935
  checks = check_attested(root, head, fail, warnings.append)
936
+ if forge == "github":
937
+ check_approvals(root, base, head, approvals(root), warnings.append)
772
938
  if carried and reasons:
773
939
  check_moved(body, recorded_rows(root, fork, head), fail, warnings.append,
774
940
  lambda one, other: bool(tree_of(one)) and tree_of(one) == tree_of(other))
@@ -778,6 +944,7 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
778
944
  + ("" if carried or not reasons else " — no carrier: forge none has no pull request. T1 to T5 "
779
945
  "judge a sheet filled in docs/pull_request_template.md — with its Deliverable line — passed by "
780
946
  "nstack attest --body-file <file>"))
947
+ print(f"Labels : {', '.join(sorted(labels)) or 'none'} — {labels_from}")
781
948
  print(f"Checks : {checks}")
782
949
  for line in summary(body, authorship) if reasons and carried else []:
783
950
  print(line)
File without changes