napkinstack 0.34.0__tar.gz → 0.34.2__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.2}/PKG-INFO +4 -4
  2. {napkinstack-0.34.0 → napkinstack-0.34.2}/README.md +3 -3
  3. {napkinstack-0.34.0 → napkinstack-0.34.2}/pyproject.toml +1 -1
  4. {napkinstack-0.34.0 → napkinstack-0.34.2}/pyproject.toml.orig +1 -1
  5. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/agent.py +55 -0
  6. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/attest.py +1 -1
  7. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/cli.py +1 -1
  8. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/boundaries.py +43 -16
  9. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/hold.py +35 -4
  10. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/pull_request.py +11 -9
  11. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/skills.py +17 -5
  12. {napkinstack-0.34.0 → napkinstack-0.34.2}/LICENSE +0 -0
  13. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/__init__.py +0 -0
  14. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/__main__.py +0 -0
  15. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/assurance.py +0 -0
  16. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/board.py +0 -0
  17. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/compat.py +0 -0
  18. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/discovery.py +0 -0
  19. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/doctor.py +0 -0
  20. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/evidence.py +0 -0
  21. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/__init__.py +0 -0
  22. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/hygiene.py +0 -0
  23. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/manifests.py +0 -0
  24. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/plan.py +0 -0
  25. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/fitness/pr_scope.py +0 -0
  26. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/landed.py +0 -0
  27. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/modules.py +0 -0
  28. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/owners.py +0 -0
  29. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/project.py +0 -0
  30. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/provenance.py +0 -0
  31. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/settings.py +0 -0
  32. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.34.0 → napkinstack-0.34.2}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {napkinstack-0.34.0 → napkinstack-0.34.2}/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.2
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.2, 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.2" nstack init my-project
90
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.2"
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.2, 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.2" nstack init my-project
73
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.34.2"
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.2"
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.2"
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"
@@ -19,6 +19,7 @@ dedicated system user).
19
19
  from __future__ import annotations
20
20
 
21
21
  import html
22
+ import io
22
23
  import http.server
23
24
  import json
24
25
  import os
@@ -27,6 +28,7 @@ import secrets
27
28
  import shutil
28
29
  import subprocess
29
30
  import sys
31
+ import tarfile
30
32
  import time
31
33
  import urllib.error
32
34
  import urllib.parse
@@ -521,6 +523,55 @@ def _sockets(clone: Path) -> bool:
521
523
  return isinstance(answers, dict) and answers.get("agent_sockets") is True
522
524
 
523
525
 
526
+ CLAUDE_SKILLS = ".claude/skills"
527
+
528
+
529
+ def _skills_beside(name: str, clone: Path) -> tuple[list[str], str | None]:
530
+ """D261: Claude Code's sandbox write-protects `.claude/skills/` — an agent may not rewrite its own
531
+ instructions —, so git cannot write the committed skills there either: a merge or a checkout
532
+ bringing new ones stops. Run outside the sandbox, this leaves that folder out of the clone's
533
+ working tree (a sparse checkout: still in every commit, never written) and lays the skills of
534
+ the default branch, as last fetched, in a folder of the agent's own, given to Claude Code by
535
+ --add-dir. Nothing where the project commits no Claude Code skill. Returns (arguments, what to say)."""
536
+ if _git("rev-parse", "--verify", "-q", "origin/HEAD", cwd=clone).returncode:
537
+ return [], (" - skills: the clone does not know its remote's default branch (origin/HEAD), so its committed "
538
+ "Claude Code skills are not read.\n Action: git remote set-head origin --auto, in the clone.")
539
+ if _git("rev-parse", "--verify", "-q", f"origin/HEAD:{CLAUDE_SKILLS}", cwd=clone).returncode:
540
+ return [], None
541
+ patterns = ["/*", f"!/{CLAUDE_SKILLS}/"]
542
+ sparse = _git("config", "--bool", "core.sparseCheckout", cwd=clone).stdout.strip() == "true"
543
+ if not sparse:
544
+ made = _git("sparse-checkout", "set", "--no-cone", *patterns, cwd=clone)
545
+ if made.returncode:
546
+ return [], (f" - skills: {CLAUDE_SKILLS}/ could not be left out of the clone: "
547
+ f"{(made.stderr or made.stdout).strip()}\n"
548
+ " In the sandbox, a merge or a checkout that changes the skills will stop.")
549
+ elif _git("sparse-checkout", "list", cwd=clone).stdout.split() != patterns:
550
+ return [], (f" - skills: the clone is already a sparse checkout of someone else's patterns: left as is. "
551
+ f"In the sandbox, a merge or a checkout that changes {CLAUDE_SKILLS}/ will stop.")
552
+ kept = [line[2:] for line in _git("ls-files", "-v", "--", CLAUDE_SKILLS, cwd=clone).stdout.splitlines()
553
+ if not line.startswith("S ")]
554
+ left = (f" - skills: {CLAUDE_SKILLS}/ left out of the clone's working tree, which the sandbox write-protects"
555
+ if not kept else
556
+ f" - skills: {CLAUDE_SKILLS}/ NOT left out of the clone: changed there, kept by git ({', '.join(kept[:3])}). "
557
+ f"In the sandbox, a merge that changes them will stop.\n"
558
+ f" Action: commit or restore them, then nstack agent run {name} again")
559
+ folder = home() / name / "skills"
560
+ shutil.rmtree(folder, ignore_errors=True)
561
+ folder.mkdir(parents=True)
562
+ archive = subprocess.run(["git", "archive", "origin/HEAD", CLAUDE_SKILLS], cwd=clone, capture_output=True)
563
+ try:
564
+ if archive.returncode:
565
+ raise OSError(archive.stderr.decode(errors="replace").strip())
566
+ with tarfile.open(fileobj=io.BytesIO(archive.stdout)) as tar:
567
+ tar.extractall(folder, filter="data")
568
+ except (tarfile.TarError, OSError) as exc:
569
+ return [], f"{left}.\n - skills: the default branch's could not be laid for the agent ({exc}): it starts without them."
570
+ return ["--add-dir", str(folder)], (
571
+ f"{left}; the default branch's, as last fetched, in {folder} (--add-dir), laid again at each run: "
572
+ "a change there lasts one session and reaches no one.")
573
+
574
+
524
575
  def _claude_settings(name: str, sockets: bool = False) -> Path:
525
576
  """Claude Code's settings of the agent's own, added to the person's (D199): their sandbox, when
526
577
  on, cuts the forge — the agent's git and gh go nowhere — and lets it write nowhere outside its
@@ -670,6 +721,10 @@ def run(name: str, command: list[str]) -> int:
670
721
  "no write to .git/config.\n"
671
722
  " - the agent checks who it is with: nstack agent status", sys.stderr)
672
723
  if Path(command[0]).name.lower() in ("claude", "claude.exe", "claude.cmd"):
724
+ beside, said = _skills_beside(name, Path(app["clone"]))
725
+ command = [command[0], *beside, *command[1:]]
726
+ if said:
727
+ _say(said, sys.stderr)
673
728
  if any(arg == "--settings" or arg.startswith("--settings=") for arg in command[1:]):
674
729
  _say(f" - claude: your --settings is kept; if your sandbox is on, its sandbox.network.allowedDomains "
675
730
  f"needs {', '.join(_hosts())}.", sys.stderr)
@@ -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,16 @@ 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); in a JavaScript, TypeScript or Go file, only the quoted specifier names one — the
35
+ word after `import` is the file's own name for it (D260). Its package is its
31
36
  folder's name, or `code_name` when the code names it otherwise (com.acme.billing). A
32
37
  relative path is read from the file's folder and from the module's — where the verbs run —
33
38
  and a path that names something of the module's own, or a contract it provides, is none.
@@ -53,6 +58,7 @@ SOURCE_SUFFIXES = {
53
58
  ".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java", ".kt",
54
59
  ".rb", ".php", ".cs", ".swift", ".scala", ".ex", ".exs",
55
60
  }
61
+ QUOTED_SPECIFIER = {".ts", ".tsx", ".js", ".jsx", ".go"} # the word after `import` is a binding (D260)
56
62
  SKIP_DIRS = {"node_modules", "dist", "build", "target", "vendor", ".git",
57
63
  "__pycache__", ".venv", "venv", "coverage", "generated"}
58
64
  IMPORT_HINTS = re.compile(
@@ -123,22 +129,30 @@ def read_files(module: dict):
123
129
  yield relative, data.decode("utf-8", errors="ignore").splitlines()
124
130
 
125
131
 
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."""
132
+ def code_patterns(other: dict) -> tuple[re.Pattern, re.Pattern, re.Pattern, re.Pattern]:
133
+ """(import of its code, path into its folder, Go import block, its bare package). On an import
134
+ line: its folder named from the root, or its package opening the statement (Python, Rust, Java)
135
+ or quoted as a module specifier (JavaScript, TypeScript, Ruby). On any line: a relative or rooted
136
+ path into its folder — ending where the folder's name does, so that ../billing.csv is not billing.
137
+ A package named like a module of Python's standard library is apart: in a Python file,
138
+ `import platform` is Python's own (D258). In JavaScript, TypeScript or Go the package opening the
139
+ statement is the binding, not the module: only the specifier counts (D260)."""
131
140
  code, folder = re.escape(other["code_name"]), re.escape(other["dirname"])
132
141
  rooted = "|".join(MODULE_DIRS)
133
142
  imports = re.compile(rf"(?<![\w-])(?:{rooted})[./]{folder}(?![\w-])"
134
143
  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
144
  rf"|(?:\bfrom\s+|\b(?:require|import)\s*\(\s*|^\s*(?:import|require)\s+)"
137
145
  rf"[\"'](?:@[\w.-]+/)?{code}(?:/[^\"']*)?[\"']")
138
146
  reach = re.compile(rf"(?<![\w.-])\.\./(?:\.\./)*{folder}(?=/|[\"'\s)]|$)"
139
147
  rf"|(?<![\w-])(?:{rooted})/{folder}/")
140
148
  block = re.compile(rf"^\s*(?:\w+\s+)?\"[^\"]*(?<![\w-])(?:{rooted})/{folder}(?:/[^\"]*)?\"\s*$")
141
- return imports, reach, block
149
+ package = re.compile(rf"^\s*(?:from|import|(?:pub\s+)?use|extern\s+crate)\s+{code}(?![\w-])")
150
+ return imports, reach, block, package
151
+
152
+
153
+ def _standard(other: dict) -> bool:
154
+ """Its package bears the name of a module of Python's standard library (platform, json, logging)."""
155
+ return other["code_name"] in sys.stdlib_module_names
142
156
 
143
157
 
144
158
  TOKEN = re.compile(r"[^\s'\"`)(,;]+")
@@ -169,8 +183,10 @@ def _lands_elsewhere(root: Path, mod: dict, relative: str, found: str, other: di
169
183
  return any(place == target or place.startswith(f"{target}/") for place in (from_file, from_module))
170
184
 
171
185
 
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."""
186
+ def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, re.Pattern, re.Pattern | None]]:
187
+ """(contract, version or None, pattern, pieces) for every contract a module provides. Its name
188
+ alone, quoted, has `pieces`: the quoted `contracts` or version that makes it the path written in
189
+ pieces (ROOT / "contracts" / "billing-api"); without them, it is a word (D259)."""
174
190
  patterns = []
175
191
  for mod in modules.values():
176
192
  for provided in mod["provides"]:
@@ -181,8 +197,9 @@ def contract_patterns(modules: dict[str, dict]) -> list[tuple[str, str | None, r
181
197
  paths = [rf"(?<![\w-]){n}/{v}(?![\w-])"]
182
198
  if isinstance(provided.get("path"), str):
183
199
  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}[\"'`]")))
200
+ patterns.append((name, version, re.compile("|".join(paths)), None))
201
+ patterns.append((name, None, re.compile(rf"[\"'`]{n}[\"'`]"),
202
+ re.compile(rf"[\"'`](?:contracts|{v})[\"'`]")))
186
203
  return patterns
187
204
 
188
205
 
@@ -231,12 +248,17 @@ def check_contracts(root: Path, modules: dict[str, dict]) -> dict[str, dict[str,
231
248
  for name, mod in modules.items():
232
249
  own = {p.get("contract") for p in mod["provides"]}
233
250
  consumed = {(c.get("contract"), c.get("version")) for c in mod["consumes"]}
251
+ declared = {contract for contract, _ in consumed}
234
252
  seen: set[tuple[str, str | None]] = set()
235
253
  for relative, lines in read_files(mod):
236
254
  for lineno, line in enumerate(lines, 1):
237
- for contract, version, pattern in patterns:
255
+ for contract, version, pattern, pieces in patterns:
238
256
  if contract in own or not pattern.search(line):
239
257
  continue
258
+ # A word that happens to be its name (an event's, a label's) reads nothing,
259
+ # unless the module consumes that contract: then it is its read (D259).
260
+ if pieces and not pieces.search(line) and contract not in declared:
261
+ continue
240
262
  producer = next((v for k, v in provided.items() if k[0] == contract), None)
241
263
  if producer:
242
264
  reads[name].setdefault(producer, set()).add(contract)
@@ -315,6 +337,8 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
315
337
  unassembled(root, name, mod, read, by_folder, f"{mod['path'].relative_to(root)}/MANIFEST.yaml (commands.{verb})")
316
338
  for relative, lines in read_files(mod):
317
339
  source = Path(relative).suffix in SOURCE_SUFFIXES
340
+ python = Path(relative).suffix == ".py"
341
+ quoted = Path(relative).suffix in QUOTED_SPECIFIER
318
342
  for lineno, line in enumerate(lines, 1):
319
343
  imports = source and IMPORT_HINTS.search(line)
320
344
  text = line.replace("\\", "/")
@@ -322,10 +346,13 @@ def check_code(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
322
346
  # what is left of the line is still B2's.
323
347
  read, text = artefact_reads(root, mod, relative, text)
324
348
  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():
349
+ for other_name, (code_import, reach, block, package) in others.items():
326
350
  if other_name == name:
327
351
  continue
328
- via_import = (imports and code_import.search(line)) or (source and block.search(line))
352
+ via_import = ((imports and (code_import.search(line)
353
+ or (package.search(line) and not quoted
354
+ and not (python and _standard(modules[other_name])))))
355
+ or (source and block.search(line)))
329
356
  reaches = [m for m in reach.finditer(text)
330
357
  if not _names_a_contract(root, mod, relative,
331
358
  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
@@ -168,11 +168,18 @@ def run(root: Path, check_only: bool = False) -> int:
168
168
  return 0
169
169
 
170
170
  removed: set[str] = set()
171
+ refused: list[str] = []
171
172
  for folder in FOLDERS:
172
- for name, entry in sorted(mapping.items()):
173
- path, content = build(root, name, entry, folder)
174
- path.parent.mkdir(parents=True, exist_ok=True)
175
- path.write_text(content, encoding="utf-8")
173
+ try:
174
+ for name, entry in sorted(mapping.items()):
175
+ path, content = build(root, name, entry, folder)
176
+ path.parent.mkdir(parents=True, exist_ok=True)
177
+ path.write_text(content, encoding="utf-8")
178
+ except OSError as exc: # an agent's sandbox write-protects .claude/skills/ alone (D261)
179
+ if folder != FOLDERS[0]:
180
+ raise
181
+ refused.append(f"{folder.as_posix()}/ could not be written ({exc.strerror or exc})")
182
+ continue
176
183
  # A playbook gone leaves its skill behind, still loaded by the agent: removed when generated
177
184
  # here, never a skill a person wrote (no banner).
178
185
  for made_dir in sorted((root / folder).glob("*/")):
@@ -182,10 +189,15 @@ def run(root: Path, check_only: bool = False) -> int:
182
189
  if not any(made_dir.iterdir()):
183
190
  made_dir.rmdir()
184
191
  removed.add(made_dir.name)
185
- print(f"Skills generated in {' and '.join(f'{folder.as_posix()}/' for folder in FOLDERS)}: {len(mapping)}"
192
+ written = [folder.as_posix() for folder in FOLDERS if not any(said.startswith(f"{folder.as_posix()}/") for said in refused)]
193
+ print(f"Skills generated in {' and '.join(f'{folder}/' for folder in written) or 'no folder'}: {len(mapping)}"
186
194
  + (f"; removed, their playbook gone: {', '.join(sorted(removed))}" if removed else ""))
187
195
  for name in sorted(mapping):
188
196
  print(f" - {name}")
197
+ for said in refused:
198
+ print(f"WARNING: {said}. Inside an agent's sandbox, that folder is protected: an agent never rewrites its "
199
+ "own instructions.\n"
200
+ " Action: a person runs nstack skills outside any sandbox and commits it — S3 says it until then.")
189
201
  for folder in _ignored(root):
190
202
  print(f"WARNING: {folder}/ is ignored by git: an agent starting from a fresh clone would not have the "
191
203
  "skills.\n"
File without changes