napkinstack 0.32.0__tar.gz → 0.33.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.32.0 → napkinstack-0.33.1}/PKG-INFO +10 -10
  2. {napkinstack-0.32.0 → napkinstack-0.33.1}/README.md +9 -9
  3. {napkinstack-0.32.0 → napkinstack-0.33.1}/pyproject.toml +1 -1
  4. {napkinstack-0.32.0 → napkinstack-0.33.1}/pyproject.toml.orig +1 -1
  5. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/agent.py +37 -2
  6. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/attest.py +12 -5
  7. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/cli.py +5 -4
  8. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/evidence.py +2 -2
  9. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/fitness/manifests.py +2 -2
  10. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/project.py +7 -3
  11. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/pull_request.py +48 -10
  12. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/settings.py +127 -19
  13. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/skills.py +71 -37
  14. {napkinstack-0.32.0 → napkinstack-0.33.1}/LICENSE +0 -0
  15. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/__init__.py +0 -0
  16. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/__main__.py +0 -0
  17. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/assurance.py +0 -0
  18. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/board.py +0 -0
  19. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/compat.py +0 -0
  20. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/discovery.py +0 -0
  21. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/doctor.py +0 -0
  22. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/fitness/__init__.py +0 -0
  23. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/fitness/boundaries.py +0 -0
  24. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/fitness/hygiene.py +0 -0
  25. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/fitness/plan.py +0 -0
  26. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/fitness/pr_scope.py +0 -0
  27. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/hold.py +0 -0
  28. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/landed.py +0 -0
  29. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/modules.py +0 -0
  30. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/owners.py +0 -0
  31. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/provenance.py +0 -0
  32. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
  33. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
  34. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/contracts/README.md +0 -0
  35. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
  36. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
  37. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/module/AGENTS.md +0 -0
  38. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
  39. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/module/README.md +0 -0
  40. {napkinstack-0.32.0 → napkinstack-0.33.1}/src/napkinstack/templates/module/src/.gitkeep +0 -0
  41. {napkinstack-0.32.0 → napkinstack-0.33.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.32.0
3
+ Version: 0.33.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.32.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
25
+ > **Status: v0.33.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.32.0" nstack init my-project
90
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.32.0"
89
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.33.1" nstack init my-project
90
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.33.1"
91
91
  ```
92
92
 
93
93
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -106,11 +106,11 @@ Each project then pins its version and changes it through `nstack update`.
106
106
 
107
107
  | Command | Role |
108
108
  |---|---|
109
- | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, the next steps for its forge (`--forge`, GitHub by default) |
109
+ | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, the next steps for its forge (`--forge`, GitHub by default); each answer given as an option or asked (`--project-name`, `--github-repo` or `--repository`, `--owner-team` — on GitHub, never an organisation's name alone) |
110
110
  | `nstack doctor` | Checks the workstation and, on GitHub, its settings, read-only; off GitHub says what it cannot verify; names a newer published version |
111
- | `nstack settings [--apply]` | Prints the calls that would bring the GitHub settings to the checklist; with `--apply`, makes them under the person's own credential, then reads the result back — never an agent's, never in CI |
111
+ | `nstack settings [--apply]` | Prints the calls that would bring the GitHub settings to the checklist; with `--apply`, makes them under the person's own credential — `GH_TOKEN`, or else their `gh` login — once they confirm the plan at the keyboard, then reads the result back — never an agent's, never in CI |
112
112
  | `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
113
- | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |
113
+ | `nstack new-contract <name> [--owner <owner>]` | Creates a contract and, the first time, the module that holds them all |
114
114
  | `nstack check`, `test`, `bootstrap`, `clean` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
115
115
  | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
116
116
  | `nstack plan` | Opens with what needs a person, or says nothing does; then the discovery, the charter and the cycles: formats, one cycle at a time, closures, and the decisions due at a closure; the project across its cycles, and who holds what |
@@ -124,10 +124,10 @@ Each project then pins its version and changes it through `nstack update`.
124
124
  | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
125
125
  | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
126
126
  | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
127
- | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
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
- | `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`; attesting the same commit again keeps the module checks it passed (`--again` runs them) |
130
- | `nstack skills` | Exposes the playbooks as skills for the agent |
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 |
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.32.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
8
+ > **Status: v0.33.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.32.0" nstack init my-project
73
- uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.32.0"
72
+ uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.33.1" nstack init my-project
73
+ uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.33.1"
74
74
  ```
75
75
 
76
76
  **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -89,11 +89,11 @@ Each project then pins its version and changes it through `nstack update`.
89
89
 
90
90
  | Command | Role |
91
91
  |---|---|
92
- | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, the next steps for its forge (`--forge`, GitHub by default) |
92
+ | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, the next steps for its forge (`--forge`, GitHub by default); each answer given as an option or asked (`--project-name`, `--github-repo` or `--repository`, `--owner-team` — on GitHub, never an organisation's name alone) |
93
93
  | `nstack doctor` | Checks the workstation and, on GitHub, its settings, read-only; off GitHub says what it cannot verify; names a newer published version |
94
- | `nstack settings [--apply]` | Prints the calls that would bring the GitHub settings to the checklist; with `--apply`, makes them under the person's own credential, then reads the result back — never an agent's, never in CI |
94
+ | `nstack settings [--apply]` | Prints the calls that would bring the GitHub settings to the checklist; with `--apply`, makes them under the person's own credential — `GH_TOKEN`, or else their `gh` login — once they confirm the plan at the keyboard, then reads the result back — never an agent's, never in CI |
95
95
  | `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
96
- | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |
96
+ | `nstack new-contract <name> [--owner <owner>]` | Creates a contract and, the first time, the module that holds them all |
97
97
  | `nstack check`, `test`, `bootstrap`, `clean` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
98
98
  | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
99
99
  | `nstack plan` | Opens with what needs a person, or says nothing does; then the discovery, the charter and the cycles: formats, one cycle at a time, closures, and the decisions due at a closure; the project across its cycles, and who holds what |
@@ -107,10 +107,10 @@ Each project then pins its version and changes it through `nstack update`.
107
107
  | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
108
108
  | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine, unless the module declares it sealed |
109
109
  | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
110
- | `nstack pr-check` | The test sheet, the cycle and the attested checks, read from the pull request description |
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
- | `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`; attesting the same commit again keeps the module checks it passed (`--again` runs them) |
113
- | `nstack skills` | Exposes the playbooks as skills for the agent |
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 |
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.32.0"
3
+ version = "0.33.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.32.0"
3
+ version = "0.33.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"
@@ -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")):
@@ -9,7 +9,8 @@ and is merged line by line; the latest line for a commit is its record. On GitHu
9
9
  that may write statuses, the run is also shown as `nstack / local checks` — a name no CI job
10
10
  has. A passed `Module checks` is kept, not run again, while the digest of what it reads is
11
11
  unchanged — the modules it runs and those they consume from or assemble, the files outside the
12
- modules, `contracts/` and `platform/` included, the engine and the person — for 7 days and 20 commits of the default branch at most (ADR-0006,
12
+ modules, `contracts/` and `platform/` included, the project's records (`docs/project/`, `docs/adr/`,
13
+ `docs/pdr/`) left out, the engine and the person — for 7 days and 20 commits of the default branch at most (ADR-0006,
13
14
  D223). A ruleset that requires that name gates the merge on the record, and the forge's pull
14
15
  request run leaves the record to it (D221): notes start no run, a status is an event.
15
16
  A record is *attested*, never *checked*: it makes a claim traceable, not true.
@@ -405,13 +406,17 @@ FRESH_COMMITS = 20 # and the default branch moved by at most this many commits
405
406
 
406
407
 
407
408
  SHARED_MODULES = ("contracts", "platform") # read by every module: counted as shared files (D223)
409
+ # The project's records — charter, cycles, rules, log; ADRs; PDRs: no module check reads them (D242).
410
+ # The rest of the root `docs/` stays an input: a module's end-to-end run may check a page it ships.
411
+ RECORDS = ("docs/project/", "docs/adr/", "docs/pdr/")
408
412
 
409
413
 
410
414
  def inputs(root: Path, base: str, identity: str = "") -> str | None:
411
415
  """The digest of what `Module checks` reads at HEAD (ADR-0006 decision 2, D223): the folders of
412
416
  the modules it runs, of those they consume from or assemble, every tracked path outside the
413
- module folders — `contracts/` and `platform/` included, which every module reads — and who runs
414
- it with which engine; git's ids, never hashed by hand. None when it cannot be told: no key."""
417
+ module folders — `contracts/` and `platform/` included, which every module reads — but the
418
+ project's records, `docs/project/`, `docs/adr/` and `docs/pdr/` (D242), and who runs it with which
419
+ engine; git's ids, never hashed by hand. None when it cannot be told: no key."""
415
420
  import yaml
416
421
 
417
422
  from napkinstack import modules
@@ -442,10 +447,12 @@ def inputs(root: Path, base: str, identity: str = "") -> str | None:
442
447
  return None
443
448
  lines.append(f"{folder} {tree}")
444
449
  inside = tuple(f"{folder}/" for folder in every.values() if folder.split("/", 1)[0] not in SHARED_MODULES)
445
- listed = _git(root, "ls-tree", "-r", "--full-tree", "HEAD", check=False)
450
+ # -z: a path git would quote — a record whose name is not ASCII, `résumé.md` — is read as it is.
451
+ listed = _git(root, "ls-tree", "-r", "-z", "--full-tree", "HEAD", check=False)
446
452
  if listed.returncode:
447
453
  return None
448
- lines += [line for line in listed.stdout.splitlines() if not line.split("\t", 1)[-1].startswith(inside)]
454
+ lines += [line for line in listed.stdout.split("\0")
455
+ if line and not line.split("\t", 1)[-1].startswith((*inside, *RECORDS))]
449
456
  return hashlib.sha256("\n".join(lines).encode("utf-8", "surrogateescape")).hexdigest()
450
457
 
451
458
 
@@ -115,8 +115,9 @@ def build_parser() -> argparse.ArgumentParser:
115
115
  "with --apply, makes them under your own credential",
116
116
  lambda a: settings.run(a.root, a.apply))
117
117
  st.add_argument("--apply", action="store_true",
118
- help="make the calls under your own credential (GH_TOKEN), then read the result back with "
119
- "nstack doctor; refused in CI and under an App's token")
118
+ help="make the calls under your own credential — GH_TOKEN when set, else your gh login — "
119
+ "once you confirm the plan at the keyboard, then read the result back with nstack "
120
+ "doctor; refused in CI, in an agent's session and under an App's token")
120
121
  nm = _add(sub, "new-module", "creates a module and its guardrails, with no imposed stack",
121
122
  lambda a: modules.create(a.root, a.name, a.owner, a.criticality, a.user_facing))
122
123
  nm.add_argument("name", help="module name, kebab-case")
@@ -165,7 +166,7 @@ def build_parser() -> argparse.ArgumentParser:
165
166
  lambda a: modules.create_contract(a.root, a.name, a.owner))
166
167
  nc.add_argument("name", help="the contract's name, kebab-case")
167
168
  nc.add_argument("--owner", help="owner of the contracts module (default: the foundation's owner)")
168
- pc = _add(sub, "pr-check", "test sheet, cycle and attested checks, read from the pull request description (T1-T5, K1-K5, A1-A2, C9)",
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
170
  lambda a: pull_request.run(a.root, a.base, a.body_file, a.labels))
170
171
  pc.add_argument("--base", default="origin/main")
171
172
  pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
@@ -198,7 +199,7 @@ def build_parser() -> argparse.ArgumentParser:
198
199
  cl.add_argument("--session", help="the agent's session, written on the hold")
199
200
  cl.add_argument("--person", help="the person accountable, such as @alice (default: git's user)")
200
201
  cl.add_argument("--take-over", action="store_true",
201
- help="take a hold nobody has worked on for hold_days — recorded, with its previous holder")
202
+ help="take a hold nobody has worked on for hold_days, or your own person's from another session — recorded, with its previous holder")
202
203
  rs = _add(sub, "unclaim", "gives a held deliverable back: by its holder, the decider, or anyone once stale; a closed cycle's hold has ended",
203
204
  lambda a: hold.release(a.root, a.deliverable, a.session, a.person))
204
205
  rs.add_argument("deliverable", help="the deliverable's identifier, D<n>, or '#<n>', an issue")
@@ -271,8 +271,8 @@ WAIT_SAID_EVERY = 60.0 # seconds between two lines of a run that waits: a long
271
271
 
272
272
  def sealed(manifest: Path) -> bool:
273
273
  """Whether the module declares its end-to-end run sealed, `evidence.sealed: true` (#402): its own
274
- session, devices, ports, the files it writes and its processes, and timings that hold whatever the load
275
- (#419) — nothing another run shares."""
274
+ session, devices, ports, the files it writes and its processes, the user's kernel limits it stays under, and
275
+ timings that hold whatever the load (#419) — nothing another run shares."""
276
276
  try:
277
277
  data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
278
278
  except (OSError, yaml.YAMLError):
@@ -412,8 +412,8 @@ def declared_evidence(manifests: list[Path], root: Path) -> None:
412
412
  fail(name, "M12", f"the declaration of {item['pattern']!r} names no scenario: say which provokes it.\n{action}", at)
413
413
  if "sealed" in section and not isinstance(section["sealed"], bool):
414
414
  fail(name, "M12", "evidence.sealed must be true or false: true when the module's end-to-end run shares "
415
- "nothing with another run — session, devices, ports, files it writes, processes — and "
416
- "passes whatever the machine's load.\n Action: evidence.sealed: true or false, or no key: the run then waits "
415
+ "nothing with another run — session, devices, ports, files it writes, processes —, stays under the "
416
+ "user's kernel limits and passes whatever the machine's load.\n Action: evidence.sealed: true or false, or no key: the run then waits "
417
417
  "its turn (.nstack/playbooks/tests.md).", at)
418
418
  if "levels" in section and not isinstance(section["levels"], str):
419
419
  fail(name, "M12", "evidence.levels must be text, a regular expression.\n"
@@ -311,7 +311,8 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
311
311
  named = str(created.get("forge") or "github")
312
312
  if named == "github":
313
313
  print(f" 2. Create the GitHub repository {created.get('github_repo')}, push main to it, then apply "
314
- "these settings:")
314
+ "these settings — nstack settings prints the calls, nstack settings --apply makes them under "
315
+ "your own token (.nstack/handbook/INSTALL.md):")
315
316
  for rule, setting, _ in CHECKLIST:
316
317
  if not unasked(rule, created): # G21 on `approval: agent` alone
317
318
  print(f" - [ ] {setting}")
@@ -655,13 +656,16 @@ def _refresh_skills(root: Path) -> str | None:
655
656
 
656
657
  from napkinstack import skills
657
658
 
658
- if not (root / ".claude" / "skills").is_dir():
659
+ if not any((root / folder).is_dir() for folder in skills.FOLDERS):
659
660
  return None
660
661
  said = io.StringIO()
661
662
  with contextlib.redirect_stdout(said):
662
663
  code = skills.run(root)
663
664
  if code == 0:
664
- return "Skills regenerated from the updated playbooks (.claude/skills/, not committed)."
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."))
665
669
  return ("The skills could not be regenerated from the updated playbooks:\n"
666
670
  + "".join(f" {line}\n" for line in said.getvalue().splitlines())
667
671
  + " Action: fix what it says, then nstack skills.")
@@ -14,7 +14,8 @@ Rules:
14
14
  T4 evidence at the head commit: an automated scenario is run again, one explored by hand
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
- request's commits read it, was not explored again (D214)
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
19
  T5 no scenario failed; none left not verified, unless it is human only
19
20
  K1 in a framed project, delivery work needs an accepted cycle, and says which of
20
21
  the two is missing
@@ -22,7 +23,8 @@ Rules:
22
23
  K3 delivery work names a ready or in-progress deliverable of the cycle
23
24
  K4 the out-of-cycle label carries its justification
24
25
  K5 delivery work for a deliverable someone holds comes from its holder: one of the hold's
25
- sessions, or its person's account (`nstack claim`)
26
+ sessions — named by any commit it brings, a merge included, as after a take-over — or its
27
+ person's account (`nstack claim`)
26
28
 
27
29
  Delivery work: a pull request that changes a module — a folder holding a MANIFEST.yaml —
28
30
  beyond its description: its manifest, AGENTS.md, README.md and docs/ (D24) — or whose manifest
@@ -379,6 +381,27 @@ def check_approvals(root: Path, base: str, head: str, found: list[tuple[str, str
379
381
  print(f"::warning title=R1 approval behind the head::{line.removeprefix('[R1] ')}")
380
382
 
381
383
 
384
+ # Copilot's code review, as the forge names it: GraphQL's author login, REST's user login
385
+ # (measured on public pull requests it approved, 2026-11-19).
386
+ COPILOT_REVIEWER = {"copilot-pull-request-reviewer", "copilot-pull-request-reviewer[bot]"}
387
+
388
+
389
+ def check_copilot(found: list[tuple[str, str]] | str | None, warn: Callable[[str], None]) -> None:
390
+ """R2 (D246): GitHub lets a repository count Copilot's approval toward the required ones — a
391
+ setting its API does not expose, so doctor cannot read it. Where every approval is Copilot's,
392
+ the merge may rest on it alone, though it ran no test sheet and names no session: said, as R1
393
+ is, never failed."""
394
+ if isinstance(found, str) or not found:
395
+ return
396
+ if all(login.lower() in COPILOT_REVIEWER for login, _ in found):
397
+ line = ("[R2] the only approval is Copilot's code review: GitHub counts it where the repository lets "
398
+ "it, yet it ran no test sheet and names no session.")
399
+ warn(f"{line}\n Action: a human code owner approves — or, on approval: agent, the verifying "
400
+ "agent under its own identity (.nstack/handbook/07-governance.md §7).")
401
+ if os.environ.get("GITHUB_ACTIONS") == "true":
402
+ print(f"::warning title=R2 approval by Copilot alone::{line.removeprefix('[R2] ')}")
403
+
404
+
382
405
  def check_verifier(verifier: str, authorship: tuple[set[str], set[str], list[str]], fail: Fail,
383
406
  hands: set[str] | None = None) -> None:
384
407
  """T2: the verifier is named — people as @handle anywhere on the line, an agent session as
@@ -529,7 +552,7 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
529
552
  return
530
553
  stage = plan.stage(root)
531
554
  if stage == plan.UNREADABLE:
532
- # Never a silent fall back to unframed: a broken file would then switch three rules off.
555
+ # Never a silent fall back to unframed: a broken file would then switch K1 to K3 and K5 off.
533
556
  fail("C1", f"{plan.CHARTER} cannot be read: the project's stage is unknown, and nothing is "
534
557
  "assumed.\n Action: fix its front matter — nstack plan says what is wrong.")
535
558
  return
@@ -600,6 +623,15 @@ def _held(root: Path, ident: str) -> bool:
600
623
  return found is not None and not isinstance(found, str)
601
624
 
602
625
 
626
+ def merge_sessions(root: Path, base: str, head: str) -> set[str]:
627
+ """The agent sessions named by the merges the pull request brings. For K5 alone (#439): a
628
+ deliverable taken over, its new session merges the default branch into the former session's
629
+ branch, and that merge may be its only commit. A sheet's authors stay the non-merge commits'."""
630
+ log = _git(root, "log", "--merges", f"--format=%(trailers:key={SESSION_TRAILER},valueonly,separator=%x1d)%x1e",
631
+ f"{base}..{head}").stdout
632
+ return {value.strip().casefold() for record in log.split("\x1e") for value in record.split("\x1d") if value.strip()}
633
+
634
+
603
635
  def identities(root: Path, base: str, head: str) -> set[str]:
604
636
  """The git identities, `Name <email>`, of the authors and committers of the commits the pull
605
637
  request brings."""
@@ -676,7 +708,8 @@ def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, wa
676
708
  same_files: Callable[[str, str], bool] = lambda one, other: False) -> None:
677
709
  """T4, the sheet's history (D214, #384): the description is edited by author and verifier alike.
678
710
  A row explored at one commit whose Commit cell now names another, its evidence unchanged, was
679
- never explored again — as a forge dismisses an approval the head moved past. An automated row
711
+ never explored again — as a forge dismisses an approval the head moved past. The row's commit is
712
+ the one the first record holding that evidence names, whatever a later record held. An automated row
680
713
  may move: CI, or the head's record, ran it. A row a record held, gone from the sheet, is said."""
681
714
  _, header, rows = read_sheet(body)
682
715
  if any(column not in header for column in COLUMNS):
@@ -687,11 +720,12 @@ def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, wa
687
720
  if row.get("kind", "").lower() != "explored" or _result(row.get("result", "")) not in {"passed", "failed"} or not SHA.fullmatch(commit):
688
721
  continue
689
722
  evidence = hashlib.sha256(row.get("evidence", "").strip().encode()).hexdigest()[:16]
723
+ # The commit it was explored at: the first record holding this evidence. A later record that
724
+ # held the cell moved does not make the move the row's commit (D243, #444).
690
725
  before = next((was for _, _, was in sorted(recorded, key=lambda r: r[1])
691
- if was["#"] == ident and was.get("evidence") == evidence and SHA.fullmatch(was.get("commit", ""))
692
- and not (was["commit"].startswith(commit) or commit.startswith(was["commit"]))
693
- and not same_files(was["commit"], commit)), None)
694
- if before:
726
+ if was["#"] == ident and was.get("evidence") == evidence and SHA.fullmatch(was.get("commit", ""))), None)
727
+ if before and not (before["commit"].startswith(commit) or commit.startswith(before["commit"])
728
+ or same_files(before["commit"], commit)):
695
729
  fail("T4", f"scenario {ident}: its Commit cell moved from {before['commit'][:7]} to {commit[:7]}, its "
696
730
  "evidence unchanged: nothing shows it was explored again.\n"
697
731
  f" Action: the verifier explores it at the head and links that run's own evidence — or puts "
@@ -948,10 +982,14 @@ def run(root: Path, base: str, body_file: Path | None = None, labels_given: str
948
982
  hands if isinstance(hands, set) else None, same_inputs(root, head, base)) if carried else []
949
983
  if modules:
950
984
  check_cycle(root, body, labels, datetime.date.today(), fail, warnings.append)
951
- check_hold(root, body, labels, authorship, fail, warnings.append, identities(root, base, head))
985
+ logins, sessions, unnamed = authorship
986
+ check_hold(root, body, labels, (logins, sessions | merge_sessions(root, base, head), unnamed),
987
+ fail, warnings.append, identities(root, base, head))
952
988
  checks = check_attested(root, head, fail, warnings.append)
953
989
  if forge == "github":
954
- check_approvals(root, base, head, approvals(root), warnings.append)
990
+ found = approvals(root)
991
+ check_approvals(root, base, head, found, warnings.append)
992
+ check_copilot(found, warnings.append)
955
993
  if carried and reasons:
956
994
  check_moved(body, recorded_rows(root, fork, head), fail, warnings.append,
957
995
  lambda one, other: bool(tree_of(one)) and tree_of(one) == tree_of(other))
@@ -7,11 +7,17 @@ that brings it to the checklist, in a form a person runs with their own credenti
7
7
  it writes nothing, and sends nothing but reads.
8
8
 
9
9
  With `--apply`, the person who holds administration has it make those calls under their own
10
- credential, then reads the result back with `nstack doctor`. Never delegated: the forge allows
11
- no credential that administers and cannot commit (D150), so the mode refuses an App's
12
- installation token — an agent's identity, which holds no administration (ADR-0004) — and a run
13
- in CI. It stores nothing, prints each change and the forge's own error for each refusal, and
14
- ends by saying to revoke the credential.
10
+ credential, then reads the result back with `nstack doctor`. The credential is the token in
11
+ GH_TOKEN (or GITHUB_TOKEN) when one is set — portable, no gh needed — and otherwise the person's
12
+ own gh login (D244), as gh itself chooses. The plan is shown, with the account it would act as,
13
+ and applied only once the person confirms it at the keyboard: never without a terminal. Never
14
+ delegated: the forge allows no credential that administers and cannot commit (D150), so the mode
15
+ refuses an App's token — an agent's identity, which holds no administration (ADR-0004) —, an
16
+ agent's session (`nstack agent run`, whose gh is the agent's own), and a run in CI; none of them
17
+ reaches the person's gh login. The keyboard is a guard against a slip, not a wall: an agent
18
+ running unwrapped as the person already holds their gh. It
19
+ stores nothing, prints each change and the forge's own error for each refusal, and ends by
20
+ saying to revoke a token given for the run — a gh login stays as it was.
15
21
 
16
22
  What it never plans, so never prints nor applies:
17
23
  - a call that rewrites or deletes a ruleset: the missing rules go in a ruleset of their own,
@@ -25,7 +31,8 @@ named, with its cost, in doctor's own words.
25
31
 
26
32
  Usage : nstack settings [--root ROOT] [--apply]
27
33
  Output: 0 with the plan printed, or nothing to change; 1 when the repository cannot be read
28
- with the token given. With --apply: 1 when a call was refused or the mode is; else
34
+ with the token given. With --apply: 1 when a call was refused, the mode is, or the
35
+ plan is not confirmed; else
29
36
  nstack doctor's own exit code.
30
37
  """
31
38
 
@@ -34,6 +41,9 @@ from __future__ import annotations
34
41
  import http.client
35
42
  import json
36
43
  import os
44
+ import shutil
45
+ import subprocess
46
+ import sys
37
47
  import urllib.error
38
48
  import urllib.parse
39
49
  import urllib.request
@@ -133,6 +143,8 @@ def plan(client: doctor.GitHub | None, missing: set[str]) -> tuple[list[Call], l
133
143
  body = {**ruleset(in_ruleset), "name": _free(client, RULESET_NAME)}
134
144
  calls.append((", ".join(sorted(in_ruleset, key=_order)), "POST", "/rulesets", body))
135
145
  if "G4" in in_ruleset:
146
+ # D26: the rulesets API took checks it never saw run (measured 2026-11-19, D244); the
147
+ # web interface may not. --apply retries without them, and says so, when it is refused.
136
148
  notes.append("G4 the forge may refuse a check it has never seen run. If it does, open a first "
137
149
  "pull request, let the checks run, then run this call again.")
138
150
  if "G12" in missing:
@@ -252,25 +264,102 @@ class Forge(doctor.GitHub):
252
264
  return False, f"not sent ({error.__class__.__name__})"
253
265
 
254
266
 
255
- def _refused(token: str | None) -> str | None:
267
+ def new_token(repo: str) -> str:
268
+ """GitHub's form for a fine-grained token, filled in: one day, the repository's owner, the two
269
+ permissions. The form takes no repository: the person picks it there."""
270
+ owner = urllib.parse.quote(repo.split("/", 1)[0], safe="")
271
+ return ("https://github.com/settings/personal-access-tokens/new?name=nstack+settings"
272
+ f"&description=nstack+settings+--apply%2C+one+run&target_name={owner}&expires_in=1"
273
+ "&administration=write&issues=write")
274
+
275
+
276
+ def _in_ci() -> bool:
277
+ return os.environ.get("GITHUB_ACTIONS") == "true" or os.environ.get("CI", "").lower() in ("true", "1")
278
+
279
+
280
+ def _host(api: str) -> str:
281
+ """The host gh names for an API URL: github.com for api.github.com, the server's otherwise."""
282
+ host = urllib.parse.urlsplit(api).hostname or "github.com"
283
+ return "github.com" if host == "api.github.com" else host
284
+
285
+
286
+ def _gh_token() -> str | None:
287
+ """The person's own gh login's token (D244), for the host the API URL names, or None: gh
288
+ absent, logged out, or silent."""
289
+ found = shutil.which("gh")
290
+ if not found:
291
+ return None
292
+ host = _host(os.environ.get("GITHUB_API_URL") or "https://api.github.com")
293
+ try:
294
+ done = subprocess.run([found, "auth", "token", "--hostname", host], capture_output=True, text=True,
295
+ timeout=15, check=False)
296
+ except (OSError, subprocess.SubprocessError):
297
+ return None
298
+ token = done.stdout.strip()
299
+ return token if done.returncode == 0 and token else None
300
+
301
+
302
+ def _interactive() -> bool:
303
+ return sys.stdin.isatty()
304
+
305
+
306
+ def _ask(prompt: str) -> str:
307
+ try:
308
+ return input(prompt)
309
+ except EOFError:
310
+ return ""
311
+
312
+
313
+ def _login(api: str, token: str) -> str:
314
+ """The account the credential acts as, as the forge names it; empty when it does not say."""
315
+ request = urllib.request.Request(f"{api.rstrip('/')}/user", headers={
316
+ "Accept": "application/vnd.github+json", "Authorization": f"Bearer {token}",
317
+ "X-GitHub-Api-Version": doctor.API_VERSION, "User-Agent": "nstack settings"})
318
+ try:
319
+ with urllib.request.urlopen(request, timeout=10) as response:
320
+ found = json.load(response)
321
+ except (OSError, ValueError, http.client.HTTPException):
322
+ return ""
323
+ return str(found.get("login") or "") if isinstance(found, dict) else ""
324
+
325
+
326
+ def _refused(token: str | None, repo: str) -> str | None:
256
327
  """Why the apply mode does not run here, or None. It is the person's gesture: never in CI,
257
- never under an App's installation token — an agent's identity holds no administration."""
258
- if os.environ.get("GITHUB_ACTIONS") == "true" or os.environ.get("CI", "").lower() in ("true", "1"):
328
+ never in an agent's session, never under an App's token — an agent's identity holds no
329
+ administration."""
330
+ if _in_ci():
259
331
  return ("--apply does not run in CI: administering the repository is a person's gesture, under their "
260
332
  "own credential.\n Action: run it on your workstation, or print the "
261
333
  "plan without --apply.")
334
+ if os.environ.get("NSTACK_AGENT"):
335
+ return ("--apply does not run in an agent's session (nstack agent run): administering the repository "
336
+ "is a person's gesture.\n Action: run it yourself, in your own terminal.")
262
337
  if not token:
263
- return ("--apply needs your own credential in GH_TOKEN: a fine-grained token limited to this "
264
- "repository, with Administration: write and Issues: write (the labels).\n"
265
- " Action: set GH_TOKEN for this one run, then revoke the token.")
338
+ return ("--apply needs your own credential: a gh login (gh auth login), or a token in GH_TOKEN — "
339
+ "fine-grained, limited to this repository, Administration: write and Issues: write (the "
340
+ f"labels), valid one day: {new_token(repo)}\n"
341
+ " Action: log in with gh auth login, or set GH_TOKEN for this one run, then revoke the token.")
266
342
  if token.startswith(("ghs_", "ghu_")):
267
343
  return ("the token is a GitHub App's — an agent's identity, which never holds administration.\n"
268
344
  " Action: run it yourself, under your own credential.")
269
345
  return None
270
346
 
271
347
 
272
- def _apply(client: Forge, root: Path, calls: list[Call], notes: list[str]) -> int:
273
- print(f"\n{len(calls)} call(s) to close the distance to the checklist, under your credential:")
348
+ def _apply(client: Forge, root: Path, calls: list[Call], notes: list[str], source: str) -> int:
349
+ login = _login(client.api, client.token)
350
+ said = "your gh login's token" if source == "gh" else f"the token in {source}"
351
+ print(f"\n{len(calls)} call(s) to close the distance to the checklist, on {client.repo} as "
352
+ f"{'@' + login if login else 'an account the forge did not name'}, with {said}:")
353
+ for closed, method, path, _ in calls:
354
+ print(f" {closed}: {method} {path or '/'}")
355
+ if not _interactive():
356
+ print("FAIL [settings] --apply is confirmed at the keyboard, and there is no terminal here: nothing "
357
+ "was changed.\n Action: run it yourself, in your own terminal — or print the plan "
358
+ "without --apply and run the calls.")
359
+ return 1
360
+ if _ask("Make these changes? [y/N] ").strip().lower() not in ("y", "yes"):
361
+ print("Nothing was changed.")
362
+ return 1
274
363
  failed = 0
275
364
  for closed, method, path, body in calls:
276
365
  done, answer = client.send(method, path, body)
@@ -292,13 +381,28 @@ def _apply(client: Forge, root: Path, calls: list[Call], notes: list[str]) -> in
292
381
  answer = f"{answer}; without the required checks: {answer_again}"
293
382
  print(f" {'applied ' if done else 'REFUSED '} {closed}: {method} {path or '/'} ({answer})")
294
383
  failed += not done
384
+ # G4's note is for calls run by hand: here a refused check was retried above, and said.
385
+ notes = [note for note in notes if not note.startswith("G4 ")]
295
386
  if notes:
296
387
  print("\nLeft to do by hand:")
297
388
  for note in notes:
298
389
  print(f" {note.replace('run this call again', 'run nstack settings --apply again')}")
299
390
  print("\nThe result, read back by nstack doctor — not by this command's account of itself:\n")
300
- code = doctor.run(root)
301
- print("\nRevoke the credential you gave this run now: nothing kept it, and nothing asks for it again.")
391
+ lent = source == "gh"
392
+ before = os.environ.get("GH_TOKEN")
393
+ if lent: # doctor reads GH_TOKEN: the same credential, for its run only
394
+ os.environ["GH_TOKEN"] = client.token
395
+ try:
396
+ code = doctor.run(root)
397
+ finally:
398
+ if lent and before is None:
399
+ os.environ.pop("GH_TOKEN", None)
400
+ elif lent:
401
+ os.environ["GH_TOKEN"] = before
402
+ if source == "gh":
403
+ print("\nThe gh login's token was read for this run and kept nowhere: your gh login stays as it was.")
404
+ else:
405
+ print("\nRevoke the credential you gave this run now: nothing kept it, and nothing asks for it again.")
302
406
  if failed:
303
407
  print(f"FAIL [settings] {failed} call(s) refused by the forge, named above with its answer.\n"
304
408
  " Action: fix what the forge said, then run nstack settings --apply again — what is in "
@@ -320,8 +424,12 @@ def run(root: Path, apply: bool = False) -> int:
320
424
  "what the forge should refuse is listed by nstack doctor and in .nstack/handbook/INSTALL.md.")
321
425
  return 0
322
426
  repo = str(answers.get("github_repo"))
323
- token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
324
- if apply and (refusal := _refused(token)):
427
+ source = next((name for name in ("GH_TOKEN", "GITHUB_TOKEN") if os.environ.get(name)), "")
428
+ token = os.environ.get(source) if source else None
429
+ if apply and not token and not _in_ci() and not os.environ.get("NSTACK_AGENT"):
430
+ token = _gh_token() # the person's own login, as gh itself would choose it (D244)
431
+ source = "gh" if token else ""
432
+ if apply and (refusal := _refused(token, repo)):
325
433
  print(f"FAIL [settings] {refusal}")
326
434
  return 1
327
435
  client = Forge(repo, token, os.environ.get("GITHUB_API_URL") or "https://api.github.com") if token else None
@@ -386,7 +494,7 @@ def run(root: Path, apply: bool = False) -> int:
386
494
  print("\nNot read with this token, planned as if missing: " + ", ".join(unread)
387
495
  + ". A call for a setting already in place changes nothing.")
388
496
  if apply and calls:
389
- return _apply(client, root, calls, notes)
497
+ return _apply(client, root, calls, notes, source)
390
498
  if apply and notes:
391
499
  print("\nNothing for --apply to make: what is left is by hand.")
392
500
  if not calls and not notes:
@@ -1,5 +1,7 @@
1
1
  """
2
- Generates Claude Code skills from the playbooks.
2
+ Generates the agents' skills from the playbooks: one SKILL.md per playbook (the Agent Skills
3
+ format), in every folder an agent tool reads — `.claude/skills/` for Claude Code,
4
+ `.agents/skills/` for Codex and the other tools that follow the open layout (D245).
3
5
 
4
6
  The playbooks are the SOURCE OF TRUTH (.nstack/handbook/06-decisions.md §9). Skills are derived
5
7
  from them: generated files, never edited by hand, never committed.
@@ -16,14 +18,16 @@ Rules (--check mode, run in CI):
16
18
  S3 generated skills match the current playbooks
17
19
  S4 name and description follow the Agent Skills specification
18
20
 
19
- S3 only applies when .claude/skills/ exists. Skills are gitignored: a fresh clone, and
20
- therefore CI, has none, and none can be out of sync there.
21
+ S3 reads each of those folders that holds a skill nstack generates — named after a playbook, or
22
+ 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.
21
25
 
22
26
  A root with neither .nstack/playbooks/ nor .nstack/skills.yaml, such as the NapkinStack
23
27
  repository itself, is out of scope.
24
28
 
25
29
  Usage:
26
- nstack skills [--root ROOT] # generates .claude/skills/
30
+ nstack skills [--root ROOT] # generates .claude/skills/ and .agents/skills/
27
31
  nstack skills --check [--root ROOT] # checks without writing
28
32
  """
29
33
 
@@ -31,6 +35,7 @@ from __future__ import annotations
31
35
 
32
36
  import hashlib
33
37
  import re
38
+ import subprocess
34
39
  from pathlib import Path
35
40
 
36
41
  import yaml
@@ -41,6 +46,9 @@ BANNER = (
41
46
  " Edit the playbook, then run `nstack skills` again. -->"
42
47
  )
43
48
  MAPPING = Path(".nstack") / "skills.yaml"
49
+ MARK = "by nstack skills - DO NOT EDIT" # in every generated skill's banner, never in a person's
50
+ # Where each agent tool looks for skills: Claude Code, then Codex and the open layout (D245).
51
+ FOLDERS = (Path(".claude") / "skills", Path(".agents") / "skills")
44
52
 
45
53
 
46
54
  def normalise(text: str) -> str:
@@ -61,7 +69,7 @@ def described(entry: dict, playbook: str) -> str:
61
69
  return normalise(entry["description"]) + (f" {when}" if when else "")
62
70
 
63
71
 
64
- def build(root: Path, name: str, entry: dict) -> tuple[Path, str]:
72
+ def build(root: Path, name: str, entry: dict, folder: Path = FOLDERS[0]) -> tuple[Path, str]:
65
73
  body = (root / entry["source"]).read_text(encoding="utf-8")
66
74
  # Serialised, never concatenated: a ":" or "#" in a description would break the YAML.
67
75
  frontmatter = yaml.safe_dump(
@@ -69,7 +77,7 @@ def build(root: Path, name: str, entry: dict) -> tuple[Path, str]:
69
77
  allow_unicode=True, sort_keys=False, width=float("inf"),
70
78
  )
71
79
  content = "---\n" + frontmatter + "---\n\n" + BANNER.format(source=entry["source"]) + "\n\n" + body
72
- return root / ".claude" / "skills" / name / "SKILL.md", content
80
+ return root / folder / name / "SKILL.md", content
73
81
 
74
82
 
75
83
  def digest(text: str) -> str:
@@ -79,7 +87,6 @@ def digest(text: str) -> str:
79
87
  def run(root: Path, check_only: bool = False) -> int:
80
88
  map_file = root / MAPPING
81
89
  playbook_dir = root / ".nstack" / "playbooks"
82
- skill_dir = root / ".claude" / "skills"
83
90
 
84
91
  if not map_file.is_file():
85
92
  if not playbook_dir.is_dir():
@@ -135,27 +142,22 @@ def run(root: Path, check_only: bool = False) -> int:
135
142
  print(f" FAIL {failure}")
136
143
  return 1
137
144
 
138
- # S3 - generation or comparison
139
- if check_only and not skill_dir.is_dir():
140
- print(f"Skills: S1, S2 and S4 compliant. S3 not applicable: "
141
- f"{skill_dir.relative_to(root)}/ missing, no skill generated here.")
145
+ # S3 - generation or comparison, in each folder an agent tool reads
146
+ present = [folder for folder in FOLDERS if _generated(root / folder, set(mapping))]
147
+ if check_only and not present:
148
+ print("Skills: S1, S2 and S4 compliant. S3 not applicable: "
149
+ f"no skill generated here, in {' or '.join(f'{folder.as_posix()}/' for folder in FOLDERS)}.")
142
150
  return 0
143
151
 
144
- stale: list[str] = []
145
- written = 0
146
- for name, entry in sorted(mapping.items()):
147
- path, content = build(root, name, entry)
148
- if check_only:
149
- if not path.is_file():
150
- stale.append(f"[S3] skill '{name}' missing from .claude/skills/")
151
- elif digest(path.read_text(encoding="utf-8")) != digest(content):
152
- stale.append(f"[S3] skill '{name}' out of sync with {entry['source']}")
153
- else:
154
- path.parent.mkdir(parents=True, exist_ok=True)
155
- path.write_text(content, encoding="utf-8")
156
- written += 1
157
-
158
152
  if check_only:
153
+ stale: list[str] = []
154
+ for folder in present:
155
+ for name, entry in sorted(mapping.items()):
156
+ path, content = build(root, name, entry, folder)
157
+ if not path.is_file():
158
+ stale.append(f"[S3] skill '{name}' missing from {folder.as_posix()}/")
159
+ elif digest(path.read_text(encoding="utf-8")) != digest(content):
160
+ stale.append(f"[S3] skill '{name}' out of sync with {entry['source']}, in {folder.as_posix()}/")
159
161
  if stale:
160
162
  for item in stale:
161
163
  print(f" FAIL {item}")
@@ -164,20 +166,52 @@ def run(root: Path, check_only: bool = False) -> int:
164
166
  print(f"Skills: {len(mapping)} in sync with the playbooks.")
165
167
  return 0
166
168
 
167
- # A playbook gone leaves its skill behind, still loaded by the agent: removed when generated here,
168
- # never a skill a person wrote (no banner).
169
- removed = []
170
- for folder in sorted(skill_dir.glob("*/")) if skill_dir.is_dir() else []:
171
- made = folder / "SKILL.md"
172
- if folder.name not in mapping and made.is_file() and "by nstack skills - DO NOT EDIT" in made.read_text(encoding="utf-8"):
173
- made.unlink()
174
- if not any(folder.iterdir()):
175
- folder.rmdir()
176
- removed.append(folder.name)
177
- print(f"Skills generated in .claude/skills/: {written}"
178
- + (f"; removed, their playbook gone: {', '.join(removed)}" if removed else ""))
169
+ removed: set[str] = set()
170
+ for folder in FOLDERS:
171
+ for name, entry in sorted(mapping.items()):
172
+ path, content = build(root, name, entry, folder)
173
+ path.parent.mkdir(parents=True, exist_ok=True)
174
+ path.write_text(content, encoding="utf-8")
175
+ # A playbook gone leaves its skill behind, still loaded by the agent: removed when generated
176
+ # here, never a skill a person wrote (no banner).
177
+ for made_dir in sorted((root / folder).glob("*/")):
178
+ made = made_dir / "SKILL.md"
179
+ if made_dir.name not in mapping and made.is_file() and MARK in made.read_text(encoding="utf-8", errors="replace"):
180
+ made.unlink()
181
+ if not any(made_dir.iterdir()):
182
+ made_dir.rmdir()
183
+ removed.add(made_dir.name)
184
+ print(f"Skills generated in {' and '.join(f'{folder.as_posix()}/' for folder in FOLDERS)}: {len(mapping)}"
185
+ + (f"; removed, their playbook gone: {', '.join(sorted(removed))}" if removed else ""))
179
186
  for name in sorted(mapping):
180
187
  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.")
181
191
  print("\nThey trigger on their own from their description; an agent can also")
182
192
  print("invoke them by name. The kernel stays in AGENTS.md.")
183
193
  return 0
194
+
195
+
196
+ def _generated(folder: Path, names: set[str]) -> bool:
197
+ """A folder holding a skill nstack generates — named after a playbook, or carrying its banner —
198
+ rather than a person's own skills alone."""
199
+ return folder.is_dir() and any(
200
+ made.parent.name in names or MARK in made.read_text(encoding="utf-8", errors="replace")
201
+ for made in folder.glob("*/SKILL.md"))
202
+
203
+
204
+ def _tracked(root: Path) -> list[str]:
205
+ """The skill folders git would track here: none outside a repository."""
206
+ found = []
207
+ for folder in FOLDERS:
208
+ try:
209
+ done = subprocess.run(["git", "-C", str(root), "check-ignore", "-q", f"{folder.as_posix()}/x/SKILL.md"],
210
+ capture_output=True, check=False)
211
+ except OSError:
212
+ return []
213
+ if done.returncode == 128: # not a repository
214
+ return []
215
+ if done.returncode == 1:
216
+ found.append(folder.as_posix())
217
+ return found
File without changes