napkinstack 0.30.0__tar.gz → 0.32.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.30.0 → napkinstack-0.32.0}/PKG-INFO +5 -5
  2. {napkinstack-0.30.0 → napkinstack-0.32.0}/README.md +4 -4
  3. {napkinstack-0.30.0 → napkinstack-0.32.0}/pyproject.toml +2 -1
  4. {napkinstack-0.30.0 → napkinstack-0.32.0}/pyproject.toml.orig +2 -1
  5. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/attest.py +159 -33
  6. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/board.py +39 -4
  7. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/cli.py +16 -5
  8. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/doctor.py +68 -9
  9. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/evidence.py +2 -1
  10. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/fitness/manifests.py +3 -3
  11. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/fitness/plan.py +20 -8
  12. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/hold.py +42 -15
  13. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/modules.py +8 -4
  14. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/project.py +49 -0
  15. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/pull_request.py +100 -13
  16. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/settings.py +8 -5
  17. {napkinstack-0.30.0 → napkinstack-0.32.0}/LICENSE +0 -0
  18. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/__init__.py +0 -0
  19. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/__main__.py +0 -0
  20. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/agent.py +0 -0
  21. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/assurance.py +0 -0
  22. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/compat.py +0 -0
  23. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/discovery.py +0 -0
  24. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/fitness/__init__.py +0 -0
  25. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/fitness/boundaries.py +0 -0
  26. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/fitness/hygiene.py +0 -0
  27. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/fitness/pr_scope.py +0 -0
  28. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/landed.py +0 -0
  29. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/owners.py +0 -0
  30. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/provenance.py +0 -0
  31. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/skills.py +0 -0
  32. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.30.0 → napkinstack-0.32.0}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {napkinstack-0.30.0 → napkinstack-0.32.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.30.0
3
+ Version: 0.32.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.30.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
25
+ > **Status: v0.32.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.30.0" nstack init my-project
90
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.30.0"
89
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.32.0" nstack init my-project
90
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.32.0"
91
91
  ```
92
92
 
93
93
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -117,7 +117,7 @@ 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 |
@@ -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.30.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
8
+ > **Status: v0.32.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.30.0" nstack init my-project
73
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.30.0"
72
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.32.0" nstack init my-project
73
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.32.0"
74
74
  ```
75
75
 
76
76
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -100,7 +100,7 @@ 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 |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.30.0"
3
+ version = "0.32.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"
@@ -24,6 +24,7 @@ nstack = "napkinstack.cli:main"
24
24
 
25
25
  [dependency-groups]
26
26
  dev = ["pytest==9.1.1"]
27
+ audit = ["pip-audit==2.10.1"]
27
28
 
28
29
  [tool.uv]
29
30
  required-version = ">=0.12.14,<0.13"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.30.0"
3
+ version = "0.32.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"
@@ -18,6 +18,7 @@ nstack = "napkinstack.cli:main"
18
18
 
19
19
  [dependency-groups]
20
20
  dev = ["pytest==9.1.1"]
21
+ audit = ["pip-audit==2.10.1"] # CI's audit of the lock (D234), never installed by uv sync
21
22
 
22
23
  [tool.uv]
23
24
  required-version = ">=0.12.14,<0.13"
@@ -132,20 +132,92 @@ def unplaced(value, root: Path):
132
132
  return value
133
133
 
134
134
 
135
- def latest(root: Path, commit: str) -> dict | None:
136
- """The record of a commit: the latest run its note holds, or None."""
135
+ def _lines(root: Path, commit: str) -> list[dict]:
136
+ """The runs and voids a commit's note holds, in no order: notes merge line by line, sorted."""
137
137
  shown = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False)
138
- if shown.returncode != 0:
139
- return None
140
- runs = []
141
- for line in shown.stdout.splitlines():
138
+ found = []
139
+ for line in shown.stdout.splitlines() if shown.returncode == 0 else []:
142
140
  try:
143
141
  run = json.loads(line)
144
142
  except json.JSONDecodeError:
145
143
  continue
146
144
  if isinstance(run, dict) and run.get("record") == RECORD and run.get("commit") == commit:
147
- runs.append(run)
148
- return max(runs, key=lambda run: str(run.get("at", "")), default=None)
145
+ found.append(run)
146
+ return found
147
+
148
+
149
+ def voided_runs(root: Path, commit: str) -> set[str]:
150
+ """The runs of a commit a void named, by their time (#429): each void lists the runs the note
151
+ held when it was made, so a clock ahead or a merge of notes never brings one back."""
152
+ return {str(at) for line in _lines(root, commit) if line.get("void") and isinstance(line.get("voids"), list)
153
+ for at in line["voids"]}
154
+
155
+
156
+ def latest(root: Path, commit: str) -> dict | None:
157
+ """The record of a commit: the latest run its note holds that no void named; else its latest
158
+ void, when every run was voided; else None."""
159
+ lines = _lines(root, commit)
160
+ gone = voided_runs(root, commit)
161
+ runs = [line for line in lines if not line.get("void") and str(line.get("at", "")) not in gone]
162
+ voids = [line for line in lines if line.get("void")]
163
+ return max(runs or voids, key=lambda run: str(run.get("at", "")), default=None)
164
+
165
+
166
+ def kept_from_voided(root: Path, check: dict, commit: str) -> bool:
167
+ """Whether a check a record kept comes from a run since voided (#429): its first run, on the
168
+ commit it was kept from, or on this one."""
169
+ first = check.get("kept_from") if isinstance(check, dict) else None
170
+ return bool(first) and str(first) in voided_runs(root, str(check.get("kept_commit") or commit))
171
+
172
+
173
+ def void(root: Path, ref: str, reason: str, base: str = "origin/main", accept_identity: bool = False) -> int:
174
+ """Marks a commit's record as known unsound — a run that shared what it must not, a tool that
175
+ lied (#429): a line of its own in the note naming every run the note holds. None of them is a
176
+ record afterwards, nor kept from, on its commit or through another commit's record (D223), and
177
+ pr-check reads the head unattested until it is attested again. The runs stay in the note:
178
+ evidence is never rewritten."""
179
+ reason = " ".join(reason.split())
180
+ if not reason:
181
+ print("FAIL [attest] a void says why: the next reader of the record is owed the reason.\n"
182
+ ' Action: nstack attest --void <commit> --reason "<what made it unsound>".')
183
+ return 1
184
+ who, refused = _publishable(root, base, accept_identity)
185
+ if refused:
186
+ print(refused.replace("the record would", "the void would"))
187
+ return 1
188
+ commit = _git(root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}", check=False).stdout.strip()
189
+ remote, unread = read_remote(root)
190
+ if remote is not None and unread:
191
+ print(f"FAIL [attest] the notes of {remote} are not read ({unread}): a void names every run they hold, "
192
+ "and one unread would stay a record.\n Action: fix the access, then again.")
193
+ return 1
194
+ runs = [line for line in _lines(root, commit) if not line.get("void")] if commit else []
195
+ if not runs:
196
+ print(f"FAIL [attest] no record of {ref} to void: nothing is kept from a run that was never recorded.\n"
197
+ " Action: name the commit whose record is unsound (git notes --ref=nstack/checks list).")
198
+ return 1
199
+ line = {"record": RECORD, "commit": commit,
200
+ "at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="microseconds"),
201
+ "by": who, "void": unplaced(reason, root), "voids": sorted(str(run.get("at", "")) for run in runs),
202
+ "checks": []}
203
+ before = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False).stdout.rstrip("\n")
204
+ subprocess.run(["git", "notes", f"--ref={NOTES}", "add", "--force", "--file=-", commit], cwd=root,
205
+ input=before + "\n" + json.dumps(line, separators=(",", ":"), ensure_ascii=False) + "\n",
206
+ text=True, capture_output=True, check=True)
207
+ if not (latest(root, commit) or {}).get("void"):
208
+ print(f"FAIL [attest] the void of {commit[:12]} is written, yet a run stays its record.\n"
209
+ " Action: report it: git notes --ref=nstack/checks show " + commit[:12])
210
+ return 1
211
+ where, pushed = "local only: no remote", True
212
+ if remote is not None:
213
+ sent = _git(root, "push", "--quiet", remote, f"refs/notes/{NOTES}", check=False)
214
+ pushed = sent.returncode == 0
215
+ where = f"pushed to {remote}" if pushed else f"NOT pushed to {remote}: {sent.stderr.strip()}"
216
+ print(f"Record of {commit[:12]}: voided by {who} — {line['void']}; {where}; {_show(root, commit, 0, 0, line['void'])}.\n"
217
+ + (" Nothing is kept from it any more; the commit is attested again by nstack attest on it."
218
+ if pushed else " Action: push again (git push " + str(remote) + " refs/notes/" + NOTES
219
+ + "): until then only this clone knows."))
220
+ return 0 if pushed else 1
149
221
 
150
222
 
151
223
  def _remote(root: Path) -> str | None:
@@ -215,7 +287,7 @@ def _session(root: Path, commit: str) -> str | None:
215
287
  return trailers.strip().splitlines()[0] if trailers.strip() else None
216
288
 
217
289
 
218
- def _show(root: Path, commit: str, passed: int, total: int) -> str:
290
+ def _show(root: Path, commit: str, passed: int, total: int, voided: str | None = None) -> str:
219
291
  """The forge's display, when there is one and a token: never a judgement, a view of the record."""
220
292
  from napkinstack import hold # the one reading of the project's GitHub
221
293
 
@@ -223,8 +295,9 @@ def _show(root: Path, commit: str, passed: int, total: int) -> str:
223
295
  if forge is None:
224
296
  return hold.unshown(root)
225
297
  api, repo, token = forge
226
- body = json.dumps({"state": "success" if passed == total else "failure", "context": CONTEXT,
227
- "description": f"attested: {passed} of {total}"}).encode()
298
+ body = json.dumps({"state": "success" if passed == total and voided is None else "failure", "context": CONTEXT,
299
+ "description": f"voided: {voided}"[:140] if voided is not None
300
+ else f"attested: {passed} of {total}"}).encode()
228
301
  request = urllib.request.Request(f"{api}/repos/{repo}/statuses/{commit}", data=body, method="POST",
229
302
  headers={"Accept": "application/vnd.github+json",
230
303
  "Authorization": f"Bearer {token}"})
@@ -276,22 +349,53 @@ def _shown(root: Path, base: str) -> set[str]:
276
349
  REASON = 8 # lines of a failed step shown when it says no FAIL line of its own
277
350
 
278
351
 
352
+ EXITED = re.compile(r"FAIL \[\w+\] module '[^']+': `.*` exited with \d+\.")
353
+
354
+
279
355
  def why(output: str) -> list[str]:
280
356
  """A failed step's reason: its FAIL lines and the indented lines under each (the action), or,
281
- when it says none, its last lines — a check that failed says why without its whole output (#244)."""
357
+ when it says none, its last lines — a check that failed says why without its whole output (#244).
358
+ A module command that exited non-zero says no more than its code: the last lines its own tool
359
+ wrote before it come first — a test runner's summary names the test that failed (#428)."""
282
360
  lines = output.splitlines()
283
- said, under = [], False
361
+ said, under, tool, audit = [], False, [], False
284
362
  for line in lines:
285
363
  if line.startswith("FAIL"):
364
+ if EXITED.match(line):
365
+ said.extend(tool[-REASON:])
366
+ tool = []
286
367
  said.append(line)
287
368
  under = True
288
369
  elif under and line.startswith(" "):
289
370
  said.append(line)
290
371
  else:
291
372
  under = False
373
+ if line.startswith(("::group::", "-> ")):
374
+ tool, audit = [], False # a module's own command writes after the engine says it runs it
375
+ elif line.startswith("Evidence of "):
376
+ audit = True # and before the engine audits its evidence: those lines are the engine's
377
+ elif line.strip() and not audit and not line.startswith(("FAIL", "::")):
378
+ tool.append(line)
292
379
  return said or [line for line in lines if line.strip()][-REASON:]
293
380
 
294
381
 
382
+ LOG_KEPT = 8 * 1024 * 1024 # bytes of a failed step's output kept in its log, the last ones
383
+
384
+
385
+ def keep_log(root: Path, commit: str, check: str, steps: list[tuple[str, str]]) -> Path:
386
+ """A failed check's whole output, in the clone's git folder — never in the tree, where it would
387
+ leave changes the next attest refuses: the record keeps 64 KiB of it and a FAIL line a few
388
+ lines; a test that fails once and passes again is named here, or nowhere (#428). Its last
389
+ 8 MiB when longer; the next failure of the same commit and check replaces it."""
390
+ folder = (root / _git(root, "rev-parse", "--git-path", "nstack/attest").stdout.strip()).resolve()
391
+ folder.mkdir(parents=True, exist_ok=True)
392
+ path = folder / f"{commit[:12]}-{re.sub(r'[^a-z0-9]+', '-', check.lower()).strip('-')}.log"
393
+ text = steps[0][1] if len(steps) == 1 else "".join(f"== {label}\n{output.rstrip(chr(10))}\n" for label, output in steps)
394
+ data = text.encode("utf-8", "replace")
395
+ path.write_bytes(data if len(data) <= LOG_KEPT else data[-LOG_KEPT:])
396
+ return path
397
+
398
+
295
399
  # An engine whose code a string names: published, a forge's commit, or a checkout's own commit.
296
400
  NAMED = re.compile(r".* \(commit [0-9a-f]{7,}\)|.*@[0-9a-f]{7,}|a local checkout at (?!an unknown commit)\S+(?<!-dirty)")
297
401
 
@@ -367,7 +471,7 @@ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine:
367
471
  if digest is None or not check.kept or base_commit is None or not (origin is None or NAMED.fullmatch(origin)):
368
472
  return None
369
473
  for commit in _git(root, "rev-list", f"{base_commit}..HEAD", check=False).stdout.split():
370
- record = latest(root, commit)
474
+ record = latest(root, commit) # a voided commit's latest line is its void: no check is kept from it
371
475
  if record is None or (record.get("engine"), record.get("origin"), record.get("published"),
372
476
  record.get("by")) != (engine, said, origin is None, who):
373
477
  continue
@@ -375,6 +479,8 @@ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine:
375
479
  found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
376
480
  if not found or found.get("passed") is not True or found.get("inputs") != digest:
377
481
  continue
482
+ if kept_from_voided(root, found, commit):
483
+ continue # kept, through this record, from a run since voided (#429)
378
484
  first = str(found.get("kept_from") or record.get("at", ""))
379
485
  run_base = found.get("kept_base") or record.get("base_commit")
380
486
  if not _fresh(root, first, run_base, base_commit):
@@ -384,7 +490,7 @@ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine:
384
490
 
385
491
 
386
492
  def _kept(previous: dict | None, check: Check, engine: str, origin: str | None, base_commit: str | None,
387
- who: str, said: str | None = None) -> dict | None:
493
+ who: str, said: str | None = None, root: Path | None = None) -> dict | None:
388
494
  """The check as the commit's record last passed it, when what it reads is the same: the commit,
389
495
  the base commit, the engine — published, or one whose commit names its code — and the person who
390
496
  ran it. A sheet filled in between changes the description, which this check never reads (#275).
@@ -399,6 +505,8 @@ def _kept(previous: dict | None, check: Check, engine: str, origin: str | None,
399
505
  found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
400
506
  if not found or found.get("passed") is not True or found.get("kept_commit"):
401
507
  return None # kept by its inputs from another commit: its freshness is _by_inputs' to judge (D223)
508
+ if root is not None and kept_from_voided(root, found, str(previous.get("commit", ""))):
509
+ return None # kept, on this commit, from a run since voided: a clone that had not seen the void (#429)
402
510
  return {**found, "kept_from": found.get("kept_from") or previous.get("at")}
403
511
 
404
512
 
@@ -416,26 +524,34 @@ def sheet_of(body: str) -> dict | None:
416
524
  return found or None
417
525
 
418
526
 
419
- def run(root: Path, base: str, body_file: Path | None, labels: str | None, accept_identity: bool = False,
420
- again: bool = False) -> int:
421
- print(provenance.judged_by(root), flush=True)
527
+ def _publishable(root: Path, base: str, accept_identity: bool) -> tuple[str, str | None]:
528
+ """Who a line of the notes will name, and why it may not travel: the notes go to the remote, and
529
+ never publish an address the project does not already show (#235) — a run's record, or a void."""
422
530
  who, address = _identity(root)
423
531
  remote = _remote(root)
424
532
  if remote is not None and not accept_identity and not NOREPLY.fullmatch(address):
425
533
  if _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).returncode != 0:
426
- print(f"FAIL [attest] base '{base}' not found: the identities the project already shows cannot be "
427
- f"read, and the record would travel to {remote}.\n"
428
- " Action: fetch the base (git fetch), or pass --base with a commit of the shared history.")
429
- return 1
534
+ return who, (f"FAIL [attest] base '{base}' not found: the identities the project already shows cannot "
535
+ f"be read, and the record would travel to {remote}.\n"
536
+ " Action: fetch the base (git fetch), or pass --base with a commit of the shared history.")
430
537
  # No remote: nothing travels — the record stays in this repository, whoever ran it.
431
538
  if remote is not None and not accept_identity and not NOREPLY.fullmatch(address) and address not in _shown(root, base):
432
539
  # A record travels with the notes to the remote: it never publishes an address the project
433
540
  # does not already show — a fresh clone falls back on a workstation's personal identity (#235).
434
- print(f"FAIL [attest] the record would name {who or 'no one'}, an identity this project's history does not "
435
- f"show — it travels with the notes to {remote}.\n"
436
- " Action: set this checkout's identity to the one the project works under "
437
- "(git config user.name / user.email), or, for a first record of your own, "
438
- "nstack attest --accept-identity.")
541
+ return who, (f"FAIL [attest] the record would name {who or 'no one'}, an identity this project's history "
542
+ f"does not show — it travels with the notes to {remote}.\n"
543
+ " Action: set this checkout's identity to the one the project works under "
544
+ "(git config user.name / user.email), or, for a first record of your own, "
545
+ "nstack attest --accept-identity.")
546
+ return who, None
547
+
548
+
549
+ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accept_identity: bool = False,
550
+ again: bool = False) -> int:
551
+ print(provenance.judged_by(root), flush=True)
552
+ who, refused = _publishable(root, base, accept_identity)
553
+ if refused:
554
+ print(refused)
439
555
  return 1
440
556
  if _git(root, "status", "--porcelain", "--untracked-files=normal").stdout.strip():
441
557
  print("FAIL [attest] the tree holds changes: a record names one commit, and this tree is none.\n"
@@ -445,6 +561,7 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
445
561
  engine, origin = provenance.engine()
446
562
  base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).stdout.strip() or None
447
563
  previous = None if again else latest(root, commit)
564
+ previous = None if previous and previous.get("void") else previous # a void keeps nothing, evidence included
448
565
  # The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147) — and the
449
566
  # pull request's own when the forge answers, a label it does not carry refused (#368).
450
567
  from napkinstack.pull_request import labels_for
@@ -470,7 +587,7 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
470
587
  digest = inputs(root, base, json.dumps([engine, unplaced(origin, root), origin is None, who]))
471
588
  env["NSTACK_INPUTS"] = digest or "" # the head's, for pr-check's T4 while this record is made (D223)
472
589
  for check in CHECKS:
473
- kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root))
590
+ kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root), root)
474
591
  if kept is not None:
475
592
  results.append(kept)
476
593
  print(f"ok [attest] {check.name}: kept from the record of {kept['kept_from']} — same commit, base "
@@ -484,21 +601,30 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
484
601
  f"same inputs ({digest[:12]}), within {FRESH_DAYS} days and {FRESH_COMMITS} commits of the "
485
602
  "default branch (nstack attest --again runs it)", flush=True)
486
603
  continue
487
- steps = []
604
+ steps, outputs = [], []
488
605
  for step in check.steps:
489
- done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env,
490
- stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
606
+ done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env, stdout=subprocess.PIPE,
607
+ stderr=subprocess.STDOUT, text=True, errors="replace")
491
608
  steps.append({"label": step.label, "command": step.command, "exit": done.returncode,
492
609
  "output": capped(done.stdout),
493
610
  "sha256": hashlib.sha256(done.stdout.encode("utf-8", "replace")).hexdigest()})
611
+ outputs.append(done.stdout)
494
612
  passed = all(step["exit"] == 0 for step in steps)
495
613
  results.append({"name": check.name, "passed": passed, "steps": steps,
496
614
  **({"inputs": digest} if check.kept and digest else {})})
497
615
  failed = "; ".join(f"{s['label']} exited {s['exit']}" for s in steps if s["exit"])
498
616
  print(f"FAIL [attest] {check.name}: {failed}" if failed else f"ok [attest] {check.name}", flush=True)
499
- for step in steps:
617
+ for step, whole in zip(steps, outputs):
500
618
  if step["exit"]:
501
- print("\n".join(f" {line}" for line in why(step["output"])), flush=True)
619
+ print("\n".join(f" {line}" for line in why(whole)), flush=True)
620
+ if failed:
621
+ try:
622
+ log = keep_log(root, commit, check.name, [(s["label"], o) for s, o in zip(steps, outputs)])
623
+ except OSError as error: # a full or read-only disk never costs the record
624
+ print(f" whole output: not kept ({error.strerror})", flush=True)
625
+ else:
626
+ shown = log.relative_to(root) if log.is_relative_to(root) else log
627
+ print(f" whole output: {shown}", flush=True)
502
628
  record = {"record": RECORD, "commit": commit,
503
629
  "at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="microseconds"),
504
630
  "engine": engine, "origin": origin, "published": origin is None, "by": who, "session": _session(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 "
@@ -176,7 +176,8 @@ def build_parser() -> argparse.ArgumentParser:
176
176
  ld.add_argument("--span", default="HEAD~1..HEAD",
177
177
  help="the commits to read, BEFORE..AFTER (default: the last commit)")
178
178
  at = _add(sub, "attest", "runs the CI's checks here and records the run on the commit, in git",
179
- lambda a: attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity, a.again))
179
+ lambda a: attest.void(a.root, a.void, a.reason or "", a.base, a.accept_identity) if a.void
180
+ else attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity, a.again))
180
181
  at.add_argument("--base", default="origin/main")
181
182
  at.add_argument("--body-file", type=Path, help="the pull request's description, for its checks")
182
183
  at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
@@ -185,6 +186,10 @@ def build_parser() -> argparse.ArgumentParser:
185
186
  help="record under an identity the project's history does not show yet — a first record of yours")
186
187
  at.add_argument("--again", action="store_true",
187
188
  help="runs every check, even the module checks this commit's record passed with the same base and engine")
189
+ at.add_argument("--void", metavar="COMMIT",
190
+ help="marks COMMIT's record as known unsound, with --reason: no check is kept from it any more, "
191
+ "and pr-check reads it unattested until attested again; nothing runs")
192
+ at.add_argument("--reason", help="why the record is unsound, with --void")
188
193
  cl = _add(sub, "claim", "takes a ready deliverable for a session, before its first change; "
189
194
  "the shared remote refuses a second taker",
190
195
  lambda a: hold.claim(a.root, a.deliverable, a.session, a.person, a.take_over))
@@ -209,7 +214,7 @@ def build_parser() -> argparse.ArgumentParser:
209
214
  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")
210
215
  bd = _add(sub, "board", "shows the cycles and their deliverables on the forge, one way: milestones and issues",
211
216
  lambda a: board.run(a.root, a.dry_run))
212
- bd.add_argument("--dry-run", action="store_true", help="say what would change, change nothing")
217
+ 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")
213
218
  ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent",
214
219
  lambda a: discovery.run(a.root, a.idea))
215
220
  ds.add_argument("idea", type=Path, help="the idea, a .md or .txt file")
@@ -252,7 +257,8 @@ def build_parser() -> argparse.ArgumentParser:
252
257
  ini.add_argument("--repository", help="the repository's path at another forge, group/name or "
253
258
  "group/subgroup/name (asked when absent)")
254
259
  ini.add_argument("--owner-team", help="owner of the foundation: organisation/team, or a user "
255
- "when the project has no organisation (asked when absent)")
260
+ "when the project has no organisation — on GitHub, never an "
261
+ "organisation's name alone (asked when absent)")
256
262
  ini.add_argument("--source", help="template: URL or path (default: the NapkinStack repository)")
257
263
  ini.add_argument("--ref", help="skeleton version: a tag vX.Y.Z, or a commit (default: the one of nstack)")
258
264
  ini.set_defaults(func=_init)
@@ -313,7 +319,12 @@ def main(argv: list[str] | None = None) -> int:
313
319
  os.environ.pop(name, None)
314
320
  if late := provenance.behind(_named_root(argv)):
315
321
  print(late, file=sys.stderr, flush=True)
316
- args = build_parser().parse_args(argv)
322
+ parser = build_parser()
323
+ args = parser.parse_args(argv)
324
+ if args.command == "attest" and (bool(args.void) != bool(args.reason) or (args.void and (args.again or args.body_file
325
+ or args.labels))):
326
+ parser.error("attest: --void and --reason go together, and with no run: never with --again, "
327
+ "--body-file or --labels")
317
328
  if args.command in JUDGES:
318
329
  print(provenance.judged_by(args.root), flush=True)
319
330
  if said := plan.stage_line(args.root):