napkinstack 0.34.0__tar.gz → 0.34.1__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.34.0 → napkinstack-0.34.1}/PKG-INFO +4 -4
  2. {napkinstack-0.34.0 → napkinstack-0.34.1}/README.md +3 -3
  3. {napkinstack-0.34.0 → napkinstack-0.34.1}/pyproject.toml +1 -1
  4. {napkinstack-0.34.0 → napkinstack-0.34.1}/pyproject.toml.orig +1 -1
  5. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/attest.py +1 -1
  6. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/cli.py +1 -1
  7. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/fitness/boundaries.py +39 -16
  8. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/hold.py +35 -4
  9. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/pull_request.py +11 -9
  10. {napkinstack-0.34.0 → napkinstack-0.34.1}/LICENSE +0 -0
  11. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/__init__.py +0 -0
  12. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/__main__.py +0 -0
  13. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/agent.py +0 -0
  14. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/assurance.py +0 -0
  15. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/board.py +0 -0
  16. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/compat.py +0 -0
  17. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/discovery.py +0 -0
  18. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/doctor.py +0 -0
  19. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/evidence.py +0 -0
  20. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/fitness/__init__.py +0 -0
  21. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/fitness/hygiene.py +0 -0
  22. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/fitness/manifests.py +0 -0
  23. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/fitness/plan.py +0 -0
  24. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/fitness/pr_scope.py +0 -0
  25. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/landed.py +0 -0
  26. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/modules.py +0 -0
  27. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/owners.py +0 -0
  28. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/project.py +0 -0
  29. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/provenance.py +0 -0
  30. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/settings.py +0 -0
  31. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/skills.py +0 -0
  32. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.34.0 → napkinstack-0.34.1}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {napkinstack-0.34.0 → napkinstack-0.34.1}/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.34.0
3
+ Version: 0.34.1
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.34.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
25
+ > **Status: v0.34.1, 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.34.0" nstack init my-project
90
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.0"
89
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.34.1" nstack init my-project
90
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.1"
91
91
  ```
92
92
 
93
93
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -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.34.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
8
+ > **Status: v0.34.1, 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.34.0" nstack init my-project
73
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.0"
72
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.34.1" nstack init my-project
73
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.1"
74
74
  ```
75
75
 
76
76
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.34.0"
3
+ version = "0.34.1"
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.34.0"
3
+ version = "0.34.1"
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"
@@ -226,7 +226,7 @@ def _remote(root: Path) -> str | None:
226
226
  branch = _git(root, "symbolic-ref", "--quiet", "--short", "HEAD", check=False).stdout.strip()
227
227
  if branch:
228
228
  named = _git(root, "config", f"branch.{branch}.remote", check=False).stdout.strip()
229
- if named:
229
+ if named and named != ".": # "." tracks a local branch: no remote
230
230
  return named
231
231
  remotes = _git(root, "remote", check=False).stdout.split()
232
232
  return "origin" if "origin" in remotes else None
@@ -204,7 +204,7 @@ def build_parser() -> argparse.ArgumentParser:
204
204
  lambda a: hold.release(a.root, a.deliverable, a.session, a.person))
205
205
  rs.add_argument("deliverable", help="the deliverable's identifier, D<n>, or '#<n>', an issue")
206
206
  rs.add_argument("--session", help="the agent's session, written on the release")
207
- rs.add_argument("--person", help="who releases it, such as @alice (default: git's user)")
207
+ rs.add_argument("--person", help="who releases it, such as @alice (default: the hold's person when --session is one of its sessions, else git's user)")
208
208
  dl = _add(sub, "deliver", "records that a merged deliverable is delivered, criterion by criterion, with no pull request; "
209
209
  "refused with no merge of it",
210
210
  lambda a: hold.deliver_command(a.root, a.deliverable, a.held or [], a.session, a.person, a.write_states))
@@ -23,11 +23,15 @@ Rules:
23
23
 
24
24
  DETECTION — textual and deliberately simple, with no stack assumed.
25
25
  - A contract is read where a module's file names its path (contracts/billing-api/v1),
26
- its name and version (billing-api/v1), or its name as a quoted string ("billing-api").
26
+ its name and version (billing-api/v1), or its name as a quoted string ("billing-api")
27
+ beside a quoted version or "contracts" — the path in pieces. Its quoted name alone is the
28
+ read of a contract the module consumes, and nothing for one it does not (D259).
27
29
  - Another module's code is referenced where an import line names its folder from the root
28
30
  (modules.billing, modules/billing, from modules import billing) or its package — opening
29
31
  the statement, or quoted as a module specifier, or alone on a Go import block's line — or
30
- where any line reaches into its folder (../billing/, modules/billing/). Its package is its
32
+ where any line reaches into its folder (../billing/, modules/billing/). In a Python
33
+ file, a package named like the standard library's (import platform) is Python's own
34
+ (D258). Its package is its
31
35
  folder's name, or `code_name` when the code names it otherwise (com.acme.billing). A
32
36
  relative path is read from the file's folder and from the module's — where the verbs run —
33
37
  and a path that names something of the module's own, or a contract it provides, is none.
@@ -123,22 +127,29 @@ def read_files(module: dict):
123
127
  yield relative, data.decode("utf-8", errors="ignore").splitlines()
124
128
 
125
129
 
126
- def code_patterns(other: dict) -> tuple[re.Pattern, re.Pattern, re.Pattern]:
127
- """(import of its code, path into its folder). On an import line: its folder named from the
128
- root, or its package opening the statement (Python, Rust, Java) or quoted as a module
129
- specifier (JavaScript, TypeScript, Ruby). On any line: a relative or rooted path into its
130
- folder — ending where the folder's name does, so that ../billing.csv is not billing."""
130
+ def code_patterns(other: dict) -> tuple[re.Pattern, re.Pattern, re.Pattern, re.Pattern]:
131
+ """(import of its code, path into its folder, Go import block, its bare package). On an import
132
+ line: its folder named from the root, or its package opening the statement (Python, Rust, Java)
133
+ or quoted as a module specifier (JavaScript, TypeScript, Ruby). On any line: a relative or rooted
134
+ path into its folder — ending where the folder's name does, so that ../billing.csv is not billing.
135
+ A package named like a module of Python's standard library is apart: in a Python file,
136
+ `import platform` is Python's own (D258)."""
131
137
  code, folder = re.escape(other["code_name"]), re.escape(other["dirname"])
132
138
  rooted = "|".join(MODULE_DIRS)
133
139
  imports = re.compile(rf"(?<![\w-])(?:{rooted})[./]{folder}(?![\w-])"
134
140
  rf"|^\s*from\s+(?:{rooted})\s+import\s+(?:[\w\s]*,\s*)?{folder}(?![\w-])"
135
- rf"|^\s*(?:from|import|(?:pub\s+)?use|extern\s+crate)\s+{code}(?![\w-])"
136
141
  rf"|(?:\bfrom\s+|\b(?:require|import)\s*\(\s*|^\s*(?:import|require)\s+)"
137
142
  rf"[\"'](?:@[\w.-]+/)?{code}(?:/[^\"']*)?[\"']")
138
143
  reach = re.compile(rf"(?<![\w.-])\.\./(?:\.\./)*{folder}(?=/|[\"'\s)]|$)"
139
144
  rf"|(?<![\w-])(?:{rooted})/{folder}/")
140
145
  block = re.compile(rf"^\s*(?:\w+\s+)?\"[^\"]*(?<![\w-])(?:{rooted})/{folder}(?:/[^\"]*)?\"\s*$")
141
- return imports, reach, block
146
+ package = re.compile(rf"^\s*(?:from|import|(?:pub\s+)?use|extern\s+crate)\s+{code}(?![\w-])")
147
+ return imports, reach, block, package
148
+
149
+
150
+ def _standard(other: dict) -> bool:
151
+ """Its package bears the name of a module of Python's standard library (platform, json, logging)."""
152
+ return other["code_name"] in sys.stdlib_module_names
142
153
 
143
154
 
144
155
  TOKEN = re.compile(r"[^\s'\"`)(,;]+")
@@ -169,8 +180,10 @@ def _lands_elsewhere(root: Path, mod: dict, relative: str, found: str, other: di
169
180
  return any(place == target or place.startswith(f"{target}/") for place in (from_file, from_module))
170
181
 
171
182
 
172
- def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, re.Pattern]]:
173
- """(contract, version or None, pattern) for every contract a module provides."""
183
+ def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, re.Pattern, re.Pattern | None]]:
184
+ """(contract, version or None, pattern, pieces) for every contract a module provides. Its name
185
+ alone, quoted, has `pieces`: the quoted `contracts` or version that makes it the path written in
186
+ pieces (ROOT / "contracts" / "billing-api"); without them, it is a word (D259)."""
174
187
  patterns = []
175
188
  for mod in modules.values():
176
189
  for provided in mod["provides"]:
@@ -181,8 +194,9 @@ def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, r
181
194
  paths = [rf"(?<![\w-]){n}/{v}(?![\w-])"]
182
195
  if isinstance(provided.get("path"), str):
183
196
  paths.append(re.escape(provided["path"].strip("/")))
184
- patterns.append((name, version, re.compile("|".join(paths))))
185
- patterns.append((name, None, re.compile(rf"[\"'`]{n}[\"'`]")))
197
+ patterns.append((name, version, re.compile("|".join(paths)), None))
198
+ patterns.append((name, None, re.compile(rf"[\"'`]{n}[\"'`]"),
199
+ re.compile(rf"[\"'`](?:contracts|{v})[\"'`]")))
186
200
  return patterns
187
201
 
188
202
 
@@ -231,12 +245,17 @@ def check_contracts(root: Path, modules: dict[str, dict]) -> dict[str, dict[str,
231
245
  for name, mod in modules.items():
232
246
  own = {p.get("contract") for p in mod["provides"]}
233
247
  consumed = {(c.get("contract"), c.get("version")) for c in mod["consumes"]}
248
+ declared = {contract for contract, _ in consumed}
234
249
  seen: set[tuple[str, str | None]] = set()
235
250
  for relative, lines in read_files(mod):
236
251
  for lineno, line in enumerate(lines, 1):
237
- for contract, version, pattern in patterns:
252
+ for contract, version, pattern, pieces in patterns:
238
253
  if contract in own or not pattern.search(line):
239
254
  continue
255
+ # A word that happens to be its name (an event's, a label's) reads nothing,
256
+ # unless the module consumes that contract: then it is its read (D259).
257
+ if pieces and not pieces.search(line) and contract not in declared:
258
+ continue
240
259
  producer = next((v for k, v in provided.items() if k[0] == contract), None)
241
260
  if producer:
242
261
  reads[name].setdefault(producer, set()).add(contract)
@@ -315,6 +334,7 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
315
334
  unassembled(root, name, mod, read, by_folder, f"{mod['path'].relative_to(root)}/MANIFEST.yaml (commands.{verb})")
316
335
  for relative, lines in read_files(mod):
317
336
  source = Path(relative).suffix in SOURCE_SUFFIXES
337
+ python = Path(relative).suffix == ".py"
318
338
  for lineno, line in enumerate(lines, 1):
319
339
  imports = source and IMPORT_HINTS.search(line)
320
340
  text = line.replace("\\", "/")
@@ -322,10 +342,13 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
322
342
  # what is left of the line is still B2's.
323
343
  read, text = artefact_reads(root, mod, relative, text)
324
344
  unassembled(root, name, mod, read, by_folder, f"{mod['path'].relative_to(root) / relative}:{lineno}")
325
- for other_name, (code_import, reach, block) in others.items():
345
+ for other_name, (code_import, reach, block, package) in others.items():
326
346
  if other_name == name:
327
347
  continue
328
- via_import = (imports and code_import.search(line)) or (source and block.search(line))
348
+ via_import = ((imports and (code_import.search(line)
349
+ or (package.search(line)
350
+ and not (python and _standard(modules[other_name])))))
351
+ or (source and block.search(line)))
329
352
  reaches = [m for m in reach.finditer(text)
330
353
  if not _names_a_contract(root, mod, relative,
331
354
  TOKEN.match(text, m.start()).group(), contracts)
@@ -94,6 +94,11 @@ class Unreachable(Exception):
94
94
  """The remote could not be read: nothing about its holds is known."""
95
95
 
96
96
 
97
+ def _then(error: Exception, action: str) -> str:
98
+ """The Action line a caller adds, unless the error already says its own."""
99
+ return "" if "Action:" in str(error) else f"\n Action: {action}"
100
+
101
+
97
102
  def fetch(root: Path, again: bool = False) -> str | None:
98
103
  """Brings the remote's holds, work branches and default branch in, as they are now; returns
99
104
  the remote's name. `again`: the read after a refused push, which must see the hold that won."""
@@ -108,9 +113,29 @@ def fetch(root: Path, again: bool = False) -> str | None:
108
113
  raise Unreachable(f"no answer from {name} within a minute") from None
109
114
  if got.returncode != 0:
110
115
  raise Unreachable(got.stderr.strip().splitlines()[0] if got.stderr.strip() else f"{name} refused the fetch")
116
+ _not_a_clone(root, name)
111
117
  return name
112
118
 
113
119
 
120
+ def _not_a_clone(root: Path, name: str) -> None:
121
+ """A remote that is a local clone of the forge — a verifier's `git clone --shared` of a working
122
+ clone — keeps the holds it fetched (refs/remotes, nstack's mirror), never as branches of its
123
+ own: a fetch of its branches brings none, and "nobody holds it" would be a guess. Said instead."""
124
+ if _git(root, "for-each-ref", "--count=1", f"{MIRROR}/hold").stdout.strip():
125
+ return # holds came in: the remote serves them
126
+ url = _git(root, "remote", "get-url", name).stdout.strip()
127
+ if not url.startswith("file://"):
128
+ if re.match(r"[A-Za-z][A-Za-z0-9+.-]*://", url):
129
+ return
130
+ if re.match(r"[^/\\]+:", url) and not re.match(r"[A-Za-z]:[/\\]", url):
131
+ return # user@host:path, never a local path; a Windows drive letter is one
132
+ served = _git(root, "ls-remote", name).stdout
133
+ if re.search(r"\trefs/(nstack-remote/hold|remotes/[^\n]*/nstack/hold)/", served):
134
+ raise Unreachable(f"{name} is a clone ({url}), not the forge: the holds it fetched are not its own "
135
+ f"branches.\n Action: point {name} at the forge (git remote set-url {name} <the "
136
+ "forge's address>), or run this where the remote is the forge")
137
+
138
+
114
139
  def _ci_credential(root: Path, name: str) -> list[str]:
115
140
  """In GitHub Actions, the job's token for this one command: the checkout keeps no credential
116
141
  (`persist-credentials: false`), and a private repository's holds are read with it (ADR-0008).
@@ -495,7 +520,7 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
495
520
  name = fetch(root)
496
521
  except Unreachable as error:
497
522
  print(f"FAIL [hold] the remote cannot be read: nothing is known of {ident}'s hold.\n"
498
- f" {error}\n Action: check the network and the remote, then again.")
523
+ f" {error}{_then(error, 'check the network and the remote, then again.')}")
499
524
  return 1
500
525
  current = read(root, cycle, ident)
501
526
  title = _issue_title(root, name, number) if number else title
@@ -600,6 +625,7 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
600
625
  cycle = None if number else plan.accepted_cycle(root)
601
626
  stem = ISSUES if number else (cycle[0].stem if cycle else None)
602
627
  ident = f"issue-{number}" if number else ident
628
+ named = bool(person)
603
629
  person, session = _person(root, person), (session or "").strip() or None
604
630
  if any(not value.isprintable() for value in (person, session or "")):
605
631
  print("FAIL [hold] a person or a session holds a line break or a control character.\n"
@@ -608,9 +634,11 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
608
634
  try:
609
635
  name = fetch(root)
610
636
  except Unreachable as error:
611
- print(f"FAIL [hold] the remote cannot be read.\n {error}\n Action: check it, then again.")
637
+ print(f"FAIL [hold] the remote cannot be read.\n {error}{_then(error, 'check it, then again.')}")
612
638
  return 1
613
639
  current = read(root, stem, ident) if stem else Hold()
640
+ if not named and session and session.casefold() in {one.casefold() for one in current.sessions}:
641
+ person = current.person # the holding session gives it back for its person, never git's user
614
642
  if not current.held and not current.recorded:
615
643
  ended = None if number else _ended(root, ident, stem)
616
644
  if ended:
@@ -633,8 +661,11 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
633
661
  f"--session {session}.")
634
662
  return 1
635
663
  if not (same(current.person, person) or is_decider or stale):
664
+ unnamed = ("" if named else f"\n No --person was given: git's user, {person}, was read. If you work for "
665
+ f"{current.person}, run again with --person {current.person}"
666
+ + (", or with the session that holds it." if current.sessions else "."))
636
667
  print(f"FAIL [hold] {ident} is {said(current)}: only its holder or the decider ({decider or 'none named'}) "
637
- "releases a hold that is not stale.\n Action: ask them.")
668
+ f"releases a hold that is not stale.{unnamed}\n Action: ask them.")
638
669
  return 1
639
670
  sha = _event(root, current.tip, ident, "release", person, session)
640
671
  ok, where = _record(root, name, stem, ident, sha)
@@ -1004,7 +1035,7 @@ def deliver(root: Path, ident: str, given: list[str], session: str | None = None
1004
1035
  try:
1005
1036
  name = fetch(root)
1006
1037
  except Unreachable as error:
1007
- print(f"FAIL [deliver] the remote cannot be read.\n {error}\n Action: check it, then again.")
1038
+ print(f"FAIL [deliver] the remote cannot be read.\n {error}{_then(error, 'check it, then again.')}")
1008
1039
  return 1
1009
1040
  if _shallow(root):
1010
1041
  print(f"FAIL [deliver] a shallow clone cannot read {ident}'s merges.\n Action: git fetch --unshallow, then again.")
@@ -605,12 +605,14 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
605
605
  elif _on_record(root, path, data, match[1]):
606
606
  warn(f"[K3] deliverable {match[1]} is on record as delivered, and this pull request delivers it again.\n"
607
607
  f" Action: if its record is wrong, nstack unclaim {match[1]}; a defect found since is an issue of its own.")
608
- elif states[match[1]] == "ready" and not _held(root, match[1]):
608
+ elif states[match[1]] == "ready" and _nobody_holds(root, match[1]):
609
609
  # Said, not refused. The hold says the work started; the cycle file stays the decider's
610
610
  # record, never changed by a delivery — under `docs/`, a human would have to approve it.
611
- warn(f"[K3] deliverable {match[1]} is still 'ready' and nobody holds it while this pull request "
612
- f"delivers it.\n Action: nstack claim {match[1]} — the hold says it is in progress; "
613
- f"{path.name} changes never in a delivery's pull request.")
611
+ from napkinstack import hold
612
+
613
+ warn(f"[K3] deliverable {match[1]} is still 'ready' and nobody holds it on {hold.remote(root) or 'this repository'} "
614
+ f"while this pull request delivers it.\n Action: nstack claim {match[1]} — the hold says it is in "
615
+ f"progress; {path.name} changes never in a delivery's pull request.")
614
616
 
615
617
 
616
618
  def _on_record(root: Path, path: Path, data: dict, ident: str) -> bool:
@@ -624,12 +626,12 @@ def _on_record(root: Path, path: Path, data: dict, ident: str) -> bool:
624
626
  return ident in plan.delivered_in(root, path, data)
625
627
 
626
628
 
627
- def _held(root: Path, ident: str) -> bool:
628
- """Whether someone holds the deliverable; holds that cannot be read count as none (K5 says so)."""
629
+ def _nobody_holds(root: Path, ident: str) -> bool:
630
+ """Whether the holds were read and none holds the deliverable. Holds that cannot be read are
631
+ no answer: K5 says why, and K3 never concludes "nobody"."""
629
632
  from napkinstack import hold
630
633
 
631
- found = hold.judge(root, ident)
632
- return found is not None and not isinstance(found, str)
634
+ return hold.judge(root, ident) is None
633
635
 
634
636
 
635
637
  def merge_sessions(root: Path, base: str, head: str) -> set[str]:
@@ -660,7 +662,7 @@ def check_hold(root: Path, body: str, labels: set[str], authorship: tuple[set[st
660
662
  ident = match[1].upper()
661
663
  found = hold.judge(root, ident)
662
664
  if isinstance(found, str):
663
- warn(f"[K5] the holds are not read ({found}): who holds {ident} is not judged here.")
665
+ warn(f"[K5] the holds are not read: who holds {ident} is not judged here.\n {found}")
664
666
  return
665
667
  if found is None:
666
668
  return
File without changes