napkinstack 0.33.0__tar.gz → 0.34.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.33.0 → napkinstack-0.34.0}/PKG-INFO +5 -5
  2. {napkinstack-0.33.0 → napkinstack-0.34.0}/README.md +4 -4
  3. {napkinstack-0.33.0 → napkinstack-0.34.0}/pyproject.toml +1 -1
  4. {napkinstack-0.33.0 → napkinstack-0.34.0}/pyproject.toml.orig +1 -1
  5. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/agent.py +37 -2
  6. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/board.py +37 -5
  7. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/cli.py +1 -1
  8. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/fitness/pr_scope.py +1 -1
  9. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/project.py +34 -17
  10. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/pull_request.py +17 -4
  11. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/settings.py +1 -1
  12. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/skills.py +11 -9
  13. {napkinstack-0.33.0 → napkinstack-0.34.0}/LICENSE +0 -0
  14. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/__init__.py +0 -0
  15. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/__main__.py +0 -0
  16. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/assurance.py +0 -0
  17. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/attest.py +0 -0
  18. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/compat.py +0 -0
  19. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/discovery.py +0 -0
  20. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/doctor.py +0 -0
  21. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/evidence.py +0 -0
  22. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/fitness/__init__.py +0 -0
  23. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/fitness/boundaries.py +0 -0
  24. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/fitness/hygiene.py +0 -0
  25. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/fitness/manifests.py +0 -0
  26. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/fitness/plan.py +0 -0
  27. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/hold.py +0 -0
  28. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/landed.py +0 -0
  29. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/modules.py +0 -0
  30. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/owners.py +0 -0
  31. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/provenance.py +0 -0
  32. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.33.0 → napkinstack-0.34.0}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {napkinstack-0.33.0 → napkinstack-0.34.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.33.0
3
+ Version: 0.34.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.33.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
25
+ > **Status: v0.34.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.33.0" nstack init my-project
90
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.33.0"
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"
91
91
  ```
92
92
 
93
93
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -127,7 +127,7 @@ Each project then pins its version and changes it through `nstack update`.
127
127
  | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description; on GitHub, an approval behind the head (R1) or by Copilot's code review alone (R2) is warned |
128
128
  | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
129
129
  | `nstack attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks`; the module checks a run passed are kept while what they read is unchanged (`--again` runs them); a failed check names its tool's last lines and keeps its whole output under `.git/nstack/attest/`; `--void <commit> --reason <why>` marks a record known unsound, never kept from again |
130
- | `nstack skills` | Exposes the playbooks as skills for the agents: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex and the open layout |
130
+ | `nstack skills` | Exposes the playbooks as skills for the agents: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex and the open layout; committed, so a fresh clone has them |
131
131
  | `nstack update [--session <id>] [--forge <name>]` | Lays the new version on a branch to review; an agent's session as the commit's `Agent-Session` trailer; `--forge` moves the project to another forge, its own lines kept |
132
132
 
133
133
  **Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
@@ -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.33.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
8
+ > **Status: v0.34.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.33.0" nstack init my-project
73
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.33.0"
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"
74
74
  ```
75
75
 
76
76
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -110,7 +110,7 @@ Each project then pins its version and changes it through `nstack update`.
110
110
  | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description; on GitHub, an approval behind the head (R1) or by Copilot's code review alone (R2) is warned |
111
111
  | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
112
112
  | `nstack attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks`; the module checks a run passed are kept while what they read is unchanged (`--again` runs them); a failed check names its tool's last lines and keeps its whole output under `.git/nstack/attest/`; `--void <commit> --reason <why>` marks a record known unsound, never kept from again |
113
- | `nstack skills` | Exposes the playbooks as skills for the agents: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex and the open layout |
113
+ | `nstack skills` | Exposes the playbooks as skills for the agents: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex and the open layout; committed, so a fresh clone has them |
114
114
  | `nstack update [--session <id>] [--forge <name>]` | Lays the new version on a branch to review; an agent's session as the commit's `Agent-Session` trailer; `--forge` moves the project to another forge, its own lines kept |
115
115
 
116
116
  **Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.33.0"
3
+ version = "0.34.0"
4
4
  description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "napkinstack"
3
- version = "0.33.0"
3
+ version = "0.34.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"
@@ -47,7 +47,9 @@ PERMISSIONS = {"contents": "write", "pull_requests": "write", "issues": "write",
47
47
  # commands, git configuration their shell injects, and the variables that point gh at another host.
48
48
  PERSONAL = ("GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN", "GH_HOST",
49
49
  "SSH_AUTH_SOCK", "GIT_ASKPASS", "SSH_ASKPASS", "GIT_SSH", "GIT_SSH_COMMAND", "GIT_PROXY_COMMAND",
50
- "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT") # without the count, git reads no GIT_CONFIG_KEY_n
50
+ "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT", # without the count, git reads no GIT_CONFIG_KEY_n
51
+ # who the person commits as: they override every configuration (#456)
52
+ "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL", "EMAIL")
51
53
  REFUSED_AUTH = {"login", "logout", "refresh", "setup-git", "switch"} # what would keep or change a login
52
54
  CI_LOGS = "results-receiver.actions.githubusercontent.com" # where github.com serves a run's logs
53
55
 
@@ -310,6 +312,26 @@ def _git(*args: str, cwd: Path | None = None, env: dict | None = None) -> subpro
310
312
  return subprocess.run(["git", *args], cwd=cwd, env=env, capture_output=True, text=True)
311
313
 
312
314
 
315
+ def _identity(name: str, user: str, email: str) -> str | None:
316
+ """The agent's identity in its own git configuration, the one `nstack agent run` hands git
317
+ (#456): every repository the agent works in commits as the App, its clone or any other — and
318
+ user.useConfigOnly refuses a commit where none is set, never one git makes up from the machine."""
319
+ config = home() / name / "gitconfig"
320
+ for key, value in (("user.name", user), ("user.email", email), ("user.useConfigOnly", "true")):
321
+ if _git("config", "--file", str(config), key, value).returncode:
322
+ return f"git could not write {key} into {config}"
323
+ return None
324
+
325
+
326
+ def _declared(name: str) -> str:
327
+ """The address the agent's own git configuration declares, with its name and useConfigOnly;
328
+ empty when any of the three is missing — a partial write or a hand edit."""
329
+ config = str(home() / name / "gitconfig")
330
+ found = {key: _git("config", "--file", config, key).stdout.strip()
331
+ for key in ("user.name", "user.email", "user.useConfigOnly")}
332
+ return found["user.email"] if found["user.name"] and found["user.useConfigOnly"] == "true" else ""
333
+
334
+
313
335
  def _clone(app: dict, clone: Path, bot: dict) -> str | None:
314
336
  """Clones the repository, or takes the agent's clone made before; configures it to act as the
315
337
  App: its name, its address, its credential helper — and git's other helpers emptied first."""
@@ -334,7 +356,7 @@ def _clone(app: dict, clone: Path, bot: dict) -> str | None:
334
356
  return f"git could not configure {clone}: {' '.join(args[:-1])}"
335
357
  if _git("remote", "set-url", "origin", remote(app["repo"]), cwd=clone).returncode:
336
358
  return f"{clone} has no remote origin to point at {app['repo']}"
337
- return None
359
+ return _identity(app["name"], login, f"{bot['id']}+{login}@users.noreply.github.com")
338
360
 
339
361
 
340
362
  def _hooks(name: str, clone: Path) -> str | None:
@@ -600,6 +622,9 @@ def status(name: str | None, root: Path | None = None, everywhere: bool = False)
600
622
  "not installed for the agent: a person runs nstack agent add " + name + " again once gh is installed.") + "\n")
601
623
  + (" - hooks: the project's, run on every commit.\n" if hooked else
602
624
  " - hooks: none — the project has no .pre-commit-config.yaml, or they were removed: nstack agent add " + name + " puts them back.\n")
625
+ + (" - identity: its own git configuration declares it; a commit with none is refused.\n" if _declared(name) else
626
+ f" - identity: missing from its own git configuration — any repository but its clone would commit under one "
627
+ f"git makes up from this machine: nstack agent run {name} writes it.\n")
603
628
  + " - a pull request you open is yours to deliver; another agent's or a person's approval merges it, as the project says.")
604
629
  return 0
605
630
 
@@ -618,6 +643,16 @@ def run(name: str, command: list[str]) -> int:
618
643
  if not command:
619
644
  _say(f"FAIL [agent] no command to start.\n Action: nstack agent run {name} -- claude")
620
645
  return 1
646
+ # An agent made before #456 has an empty configuration of its own: its clone's identity is
647
+ # written there, so any other repository it works in commits as the App too.
648
+ if not _declared(name):
649
+ local = {key: _git("config", "--local", key, cwd=app["clone"]).stdout.strip() for key in ("user.name", "user.email")}
650
+ if not all(local.values()) or (said := _identity(name, local["user.name"], local["user.email"])):
651
+ _say(f"FAIL [agent] agent {name} has no identity to commit under"
652
+ + (f": {said}" if all(local.values()) else f" — its clone {app['clone']} declares none")
653
+ + f".\n Action: a person runs nstack agent add {name} again: the App is kept.")
654
+ return 1
655
+ _say(f"Agent {name}: its identity written into its own git configuration (#456).", sys.stderr)
621
656
  # A sandbox write-protects .git/config: a tracking branch or `push -u` fails there (D212).
622
657
  # Written only when it differs, so a run started inside one still starts once it is set.
623
658
  for key, value in (("branch.autoSetupMerge", "false"), ("push.default", "current")):
@@ -5,7 +5,9 @@ The cycle files are the plan; this command shows them on GitHub — a milestone
5
5
  closed or stopped cycle, an issue per deliverable — and keeps the display equal to them. A dry
6
6
  run also previews what a proposed cycle's acceptance would create, and makes none of it. Its own
7
7
  objects carry a marker in their body; an object without one is never touched. What the forge
8
- holds decides nothing but whether the display must be rewritten.
8
+ holds decides nothing but whether the display must be rewritten. Two runs at once — one by hand
9
+ beside the workflow's — each make what the other has not yet: the next run keeps the oldest of
10
+ each, closes the other issues and says a second milestone (D253).
9
11
 
10
12
  Usage : nstack board [--root ROOT] [--dry-run]
11
13
  Output: 0 whatever the forge answers — what was made, updated or not shown is said.
@@ -160,15 +162,24 @@ def _pages(forge, path: str, stop=lambda item: False) -> list[dict]:
160
162
 
161
163
 
162
164
  def _own(objects: list[dict], field_name: str, kind: str) -> dict[str, dict]:
163
- """The display's own objects, by the key their marker carries; others are never touched."""
164
- own = {}
165
- for item in objects:
165
+ """The display's own objects, by the key their marker carries — the oldest where two runs at
166
+ once made two (D253); others are never touched."""
167
+ own: dict[str, dict] = {}
168
+ for item in sorted(objects, key=lambda item: int(item.get("number") or 0)):
166
169
  found = MARKER.search(str(item.get(field_name) or ""))
167
170
  if found and found[1] == kind:
168
171
  own.setdefault(found[2], item)
169
172
  return own
170
173
 
171
174
 
175
+ def _seconds(objects: list[dict], field_name: str, kind: str) -> list[tuple[str, dict]]:
176
+ """The display's own objects that `_own` does not keep: a second one of the same key, made by a
177
+ run beside another — by hand while the workflow ran (D253)."""
178
+ kept = {id(item) for item in _own(objects, field_name, kind).values()}
179
+ return [(found[2], item) for item in objects
180
+ if (found := MARKER.search(str(item.get(field_name) or ""))) and found[1] == kind and id(item) not in kept]
181
+
182
+
172
183
  def _holders(root: Path, idents: list[tuple[str, str]]) -> dict[str, str] | None:
173
184
  """The person holding each open deliverable, or None when the holds cannot be read."""
174
185
  from napkinstack import hold
@@ -232,7 +243,13 @@ def run(root: Path, dry_run: bool = False, today: datetime.date | None = None) -
232
243
  # Every issue, not those carrying the label: a label removed by hand leaves the marker.
233
244
  issues = [item for item in _pages(forge, "/issues?state=all") if "pull_request" not in item]
234
245
  if holders is None: # the records unread too: one failed fetch reopens nothing they closed
235
- closed_ones = {key for key, issue in _own(issues, "body", "deliverable").items() if issue.get("state") == "closed"}
246
+ # Closed only where every issue of the deliverable is: a second, open one made by two runs
247
+ # at once is not a record the holds closed (D253).
248
+ states: dict[str, set] = {}
249
+ for item in issues:
250
+ if (found := MARKER.search(str(item.get("body") or ""))) and found[1] == "deliverable":
251
+ states.setdefault(found[2], set()).add(item.get("state"))
252
+ closed_ones = {key for key, seen in states.items() if seen == {"closed"}}
236
253
  shown = [item for item in shown if not (item.kind == "deliverable" and item.state == "open" and item.key in closed_ones)]
237
254
  lines += _apply(forge, shown, milestones, issues, dry_run, keep_assignees=holders is None)
238
255
  except hold.Refused as error:
@@ -393,6 +410,21 @@ def _apply(forge, shown: list[Shown], milestones: list[dict], issues: list[dict]
393
410
  call("PATCH", f"/issues/{have['number']}", want)
394
411
  said.append(f"updated issue {item.title}: {', '.join(changed)}")
395
412
 
413
+ # Two runs at once each made what the other had not yet (D253): the oldest is the display, the
414
+ # others are closed — objects the display made, never one without its marker.
415
+ for key, extra in _seconds(issues, "body", "deliverable"):
416
+ if extra.get("number") and (extra.get("state") == "open" or extra.get("milestone") or extra.get("labels")):
417
+ kept = own_issues[key].get("number")
418
+ # Out of the milestone and the labels too: its bar and its views count the display's issue once.
419
+ call("PATCH", f"/issues/{extra['number']}", {"state": "closed", "state_reason": "not_planned",
420
+ "milestone": None, "labels": []})
421
+ said.append(f"closed issue #{extra['number']}: a second issue of {key}, made by two runs at once — "
422
+ f"#{kept} shows it")
423
+ for key, extra in _seconds(milestones, "description", "cycle"):
424
+ said.append(f"milestone #{extra.get('number')} is a second one of cycle {key}, made by two runs at once: "
425
+ f"#{own_milestones[key].get('number')} shows it — delete #{extra.get('number')} on the forge: the "
426
+ "display's issues are on the first already")
427
+
396
428
  wanted = {item.key for item in shown if item.kind == "deliverable"}
397
429
  for key, have in own_issues.items():
398
430
  if key not in wanted and have.get("state") == "open" and have.get("number"):
@@ -166,7 +166,7 @@ def build_parser() -> argparse.ArgumentParser:
166
166
  lambda a: modules.create_contract(a.root, a.name, a.owner))
167
167
  nc.add_argument("name", help="the contract's name, kebab-case")
168
168
  nc.add_argument("--owner", help="owner of the contracts module (default: the foundation's owner)")
169
- pc = _add(sub, "pr-check", "test sheet, cycle and attested checks, read from the pull request description (T1-T5, K1-K5, A1-A2, C9, R1-R2)",
169
+ pc = _add(sub, "pr-check", "test sheet, cycle and attested checks, read from the pull request description (T1-T5, K1-K5, A1-A2, C1, C9, R1-R2)",
170
170
  lambda a: pull_request.run(a.root, a.base, a.body_file, a.labels))
171
171
  pc.add_argument("--base", default="origin/main")
172
172
  pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
@@ -28,7 +28,7 @@ from napkinstack.fitness.manifests import changed_files
28
28
  from napkinstack.pull_request import touched_modules
29
29
 
30
30
  GENERATED = re.compile(r"(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|go\.sum|uv\.lock"
31
- r"|\.generated\.|/generated/)")
31
+ r"|\.generated\.|/generated/|(?:^|/)\.(?:claude|agents)/skills/)") # skills: D252
32
32
 
33
33
 
34
34
  def _git(root: Path, *args: str) -> str:
@@ -293,6 +293,7 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
293
293
  return 1
294
294
 
295
295
  settle_checks(destination, given=data)
296
+ skilled, skills_said = _generate_skills(destination) # committed with the project: a fresh clone's agent has them
296
297
  created = _answers(destination)
297
298
  version = created.get("_commit", ref)
298
299
  for args in (("init", "--quiet", "--initial-branch=main"), ("add", "--all"),
@@ -306,13 +307,16 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
306
307
  return 1
307
308
 
308
309
  print(f"Project created in {destination}, NapkinStack {version}, initial commit on main.")
310
+ if skills_said:
311
+ print(("WARNING: the skills were not generated:\n" if not skilled else "") + skills_said
312
+ + ("\n Action: fix what it says, then nstack skills, and commit them." if not skilled else ""))
309
313
  print("\nNext steps:")
310
314
  print(f" 1. cd {destination} && pre-commit install")
311
315
  named = str(created.get("forge") or "github")
312
316
  if named == "github":
313
317
  print(f" 2. Create the GitHub repository {created.get('github_repo')}, push main to it, then apply "
314
318
  "these settings — nstack settings prints the calls, nstack settings --apply makes them under "
315
- "your own token (.nstack/handbook/INSTALL.md):")
319
+ "your own credential (.nstack/handbook/INSTALL.md):")
316
320
  for rule, setting, _ in CHECKLIST:
317
321
  if not unasked(rule, created): # G21 on `approval: agent` alone
318
322
  print(f" - [ ] {setting}")
@@ -605,9 +609,10 @@ def update(root: Path, ref: str, session: str | None = None) -> int:
605
609
  for path in conflicts:
606
610
  print(f" - {path}")
607
611
  print(" Action: in each file, keep the right version between <<<<<<< and >>>>>>>, "
608
- "then git add --all && git commit, and nstack skills — the generated skills follow the playbooks.\n"
612
+ "then nstack skills — the skills follow the playbooks —, then git add --all && git commit.\n"
609
613
  " The check-merge-conflict hook and CI reject any remaining marker.")
610
614
  return 1
615
+ refreshed = _refresh_skills(root) # in the update's own commit (D252), beside the playbooks it follows
611
616
  # An agent's update carries the kernel's trailer, as every commit it makes (D135).
612
617
  message = f"NapkinStack {previous} -> {current}" + (f"\n\nAgent-Session: {session}" if session else "")
613
618
  for args in (("add", "--all"), ("commit", "--quiet", "--message", message)):
@@ -641,34 +646,46 @@ def update(root: Path, ref: str, session: str | None = None) -> int:
641
646
  f"{release_notes(str(_answers(root).get('_src_path') or ''), previous, current)}")
642
647
  if note := _not_yet_published(current):
643
648
  print(note)
644
- if said := _refresh_skills(root):
645
- print(said)
649
+ if refreshed:
650
+ print(refreshed)
646
651
  print(f"\n{next_step(root, branch)}")
647
652
  return 0
648
653
 
649
654
 
650
- def _refresh_skills(root: Path) -> str | None:
651
- """D220: the skills are generated from the playbooks and git-ignored, so an update that moves a
652
- playbook leaves them behind, and the first check fails S3. Where the person generated them, the
653
- update generates them again: derived files, nothing of anyone's lost. None where there are none."""
655
+ def _generate_skills(root: Path) -> tuple[bool, str]:
656
+ """The skills generated from the playbooks, quietly: whether it succeeded, and what the generator
657
+ said that a person must read — its failure, or a folder git ignores."""
654
658
  import contextlib
655
659
  import io
656
660
 
657
661
  from napkinstack import skills
658
662
 
659
- if not any((root / folder).is_dir() for folder in skills.FOLDERS):
660
- return None
661
663
  said = io.StringIO()
662
664
  with contextlib.redirect_stdout(said):
663
665
  code = skills.run(root)
664
- if code == 0:
665
- # A folder git would track is said: the person's next commit would carry the skills.
666
- tracked = [line for line in said.getvalue().splitlines() if line.startswith("WARNING:") or line.startswith(" Action:")]
667
- return ("Skills regenerated from the updated playbooks (.claude/skills/ and .agents/skills/)"
668
- + ("".join(f"\n {line}" for line in tracked) if tracked else ", not committed."))
666
+ if code:
667
+ return False, said.getvalue()
668
+ lines = said.getvalue().splitlines()
669
+ return True, "\n".join(line for number, line in enumerate(lines)
670
+ if line.startswith("WARNING:") or (number and lines[number - 1].startswith("WARNING:")))
671
+
672
+
673
+ def _refresh_skills(root: Path) -> str | None:
674
+ """D220, D252: the skills are generated from the playbooks and committed beside them, so the
675
+ update regenerates them before its commit — a project that never committed them gets them
676
+ there. None where the project declares no skills."""
677
+ from napkinstack import skills
678
+
679
+ if not (root / skills.MAPPING).is_file():
680
+ return None
681
+ done, said = _generate_skills(root)
682
+ if done and not said:
683
+ return "Skills regenerated from the updated playbooks (.claude/skills/, .agents/skills/), in the update's commit."
684
+ if done: # generated, but git ignores a folder: the commit left it out
685
+ return "Skills regenerated from the updated playbooks, but not all in the update's commit:\n" + said
669
686
  return ("The skills could not be regenerated from the updated playbooks:\n"
670
- + "".join(f" {line}\n" for line in said.getvalue().splitlines())
671
- + " Action: fix what it says, then nstack skills.")
687
+ + "".join(f" {line}\n" for line in said.splitlines())
688
+ + " Action: fix what it says, then nstack skills, and commit them.")
672
689
 
673
690
 
674
691
  def _not_yet_published(ref: str) -> str | None:
@@ -15,7 +15,8 @@ Rules:
15
15
  is confirmed at the head instead — and at criticality critical, run again like the rest;
16
16
  an explored row whose Commit cell moved, its evidence unchanged since a record of the pull
17
17
  request's commits read it, was not explored again (D214); moved from the commit the first
18
- record of that evidence names, so putting it back stands (D243)
18
+ record of that evidence names, so putting it back stands (D243), or setting it back to any
19
+ ancestor of that commit, explored before a record held it (D254)
19
20
  T5 no scenario failed; none left not verified, unless it is human only
20
21
  K1 in a framed project, delivery work needs an accepted cycle, and says which of
21
22
  the two is missing
@@ -25,6 +26,14 @@ Rules:
25
26
  K5 delivery work for a deliverable someone holds comes from its holder: one of the hold's
26
27
  sessions — named by any commit it brings, a merge included, as after a take-over — or its
27
28
  person's account (`nstack claim`)
29
+ A1 where checks are attested and the forge does not require nstack attest's status, a record
30
+ of the head — warned where CI cannot read it
31
+ A2 that record complete and passed, never voided, keeping nothing from a voided run — left to
32
+ the required status where the forge requires it
33
+ C1 the charter readable: the project's stage is never assumed
34
+ C9 an accepted charter changed with no decision record, warned
35
+ R1 an approval given before commits other than the base branch's, warned (D227)
36
+ R2 every approval Copilot's code review, warned (D246)
28
37
 
29
38
  Delivery work: a pull request that changes a module — a folder holding a MANIFEST.yaml —
30
39
  beyond its description: its manifest, AGENTS.md, README.md and docs/ (D24) — or whose manifest
@@ -705,7 +714,8 @@ def recorded_rows(root: Path, fork: str, head: str) -> list[tuple[str, str, dict
705
714
 
706
715
 
707
716
  def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, warn: Callable[[str], None],
708
- same_files: Callable[[str, str], bool] = lambda one, other: False) -> None:
717
+ same_files: Callable[[str, str], bool] = lambda one, other: False,
718
+ before_it: Callable[[str, str], bool] = lambda older, newer: False) -> None:
709
719
  """T4, the sheet's history (D214, #384): the description is edited by author and verifier alike.
710
720
  A row explored at one commit whose Commit cell now names another, its evidence unchanged, was
711
721
  never explored again — as a forge dismisses an approval the head moved past. The row's commit is
@@ -724,8 +734,10 @@ def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, wa
724
734
  # held the cell moved does not make the move the row's commit (D243, #444).
725
735
  before = next((was for _, _, was in sorted(recorded, key=lambda r: r[1])
726
736
  if was["#"] == ident and was.get("evidence") == evidence and SHA.fullmatch(was.get("commit", ""))), None)
737
+ # A cell set back to an ancestor of that commit claims less, not more — explored before the
738
+ # first record held it there, the head confirmed beside it (#460): only a move forward is said.
727
739
  if before and not (before["commit"].startswith(commit) or commit.startswith(before["commit"])
728
- or same_files(before["commit"], commit)):
740
+ or same_files(before["commit"], commit) or before_it(commit, before["commit"])):
729
741
  fail("T4", f"scenario {ident}: its Commit cell moved from {before['commit'][:7]} to {commit[:7]}, its "
730
742
  "evidence unchanged: nothing shows it was explored again.\n"
731
743
  f" Action: the verifier explores it at the head and links that run's own evidence — or puts "
@@ -992,7 +1004,8 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
992
1004
  check_copilot(found, warnings.append)
993
1005
  if carried and reasons:
994
1006
  check_moved(body, recorded_rows(root, fork, head), fail, warnings.append,
995
- lambda one, other: bool(tree_of(one)) and tree_of(one) == tree_of(other))
1007
+ lambda one, other: bool(tree_of(one)) and tree_of(one) == tree_of(other),
1008
+ lambda older, newer: _git(root, "merge-base", "--is-ancestor", older, newer).returncode == 0)
996
1009
 
997
1010
  print(f"Modules touched : {len(modules)}" + "".join(f"\n - {folder}" for folder in modules))
998
1011
  print(f"Test sheet : {'required' if reasons else 'not required'}"
@@ -335,7 +335,7 @@ def _refused(token: str | None, repo: str) -> str | None:
335
335
  return ("--apply does not run in an agent's session (nstack agent run): administering the repository "
336
336
  "is a person's gesture.\n Action: run it yourself, in your own terminal.")
337
337
  if not token:
338
- return ("--apply needs your own credential: a gh login (gh auth login), or a token in GH_TOKEN — "
338
+ return ("--apply needs your own credential: a gh login (gh auth login), or a token in GH_TOKEN (or GITHUB_TOKEN) — "
339
339
  "fine-grained, limited to this repository, Administration: write and Issues: write (the "
340
340
  f"labels), valid one day: {new_token(repo)}\n"
341
341
  " Action: log in with gh auth login, or set GH_TOKEN for this one run, then revoke the token.")
@@ -4,7 +4,9 @@ format), in every folder an agent tool reads — `.claude/skills/` for Claude Co
4
4
  `.agents/skills/` for Codex and the other tools that follow the open layout (D245).
5
5
 
6
6
  The playbooks are the SOURCE OF TRUTH (.nstack/handbook/06-decisions.md §9). Skills are derived
7
- from them: generated files, never edited by hand, never committed.
7
+ from them: generated files, never edited by hand — and committed (D252), as a lockfile is, so that
8
+ an agent starting from a fresh clone (a cloud agent, a new contributor) has them; S3, run in CI on
9
+ the committed files, says one that drifted from its playbook.
8
10
 
9
11
  Why generate rather than write skills directly:
10
12
  - portability — the OS must stay usable by an agent that knows nothing about
@@ -20,8 +22,7 @@ Rules (--check mode, run in CI):
20
22
 
21
23
  S3 reads each of those folders that holds a skill nstack generates — named after a playbook, or
22
24
  with its banner —, and only those: a folder of a person's own skills, tracked, is not asked for
23
- every playbook (D248). Skills are gitignored: a fresh
24
- clone, and therefore CI, has none, and none can be out of sync there.
25
+ every playbook (D248). A project that never generated has none, and S3 does not apply there.
25
26
 
26
27
  A root with neither .nstack/playbooks/ nor .nstack/skills.yaml, such as the NapkinStack
27
28
  repository itself, is out of scope.
@@ -185,9 +186,10 @@ def run(root: Path, check_only: bool = False) -> int:
185
186
  + (f"; removed, their playbook gone: {', '.join(sorted(removed))}" if removed else ""))
186
187
  for name in sorted(mapping):
187
188
  print(f" - {name}")
188
- for folder in _tracked(root):
189
- print(f"WARNING: {folder}/ is not ignored by git: the generated skills would be committed.\n"
190
- f" Action: add {folder}/ to .gitignore — nstack update brings the line.")
189
+ for folder in _ignored(root):
190
+ print(f"WARNING: {folder}/ is ignored by git: an agent starting from a fresh clone would not have the "
191
+ "skills.\n"
192
+ f" Action: remove the {folder}/ line from .gitignore — nstack update does — then commit the folder.")
191
193
  print("\nThey trigger on their own from their description; an agent can also")
192
194
  print("invoke them by name. The kernel stays in AGENTS.md.")
193
195
  return 0
@@ -201,8 +203,8 @@ def _generated(folder: Path, names: set[str]) -> bool:
201
203
  for made in folder.glob("*/SKILL.md"))
202
204
 
203
205
 
204
- def _tracked(root: Path) -> list[str]:
205
- """The skill folders git would track here: none outside a repository."""
206
+ def _ignored(root: Path) -> list[str]:
207
+ """The skill folders git ignores here, which a commit would leave out: none outside a repository."""
206
208
  found = []
207
209
  for folder in FOLDERS:
208
210
  try:
@@ -212,6 +214,6 @@ def _tracked(root: Path) -> list[str]:
212
214
  return []
213
215
  if done.returncode == 128: # not a repository
214
216
  return []
215
- if done.returncode == 1:
217
+ if done.returncode == 0:
216
218
  found.append(folder.as_posix())
217
219
  return found
File without changes