napkinstack 0.32.0__tar.gz → 0.33.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.
- {napkinstack-0.32.0 → napkinstack-0.33.0}/PKG-INFO +10 -10
- {napkinstack-0.32.0 → napkinstack-0.33.0}/README.md +9 -9
- {napkinstack-0.32.0 → napkinstack-0.33.0}/pyproject.toml +1 -1
- {napkinstack-0.32.0 → napkinstack-0.33.0}/pyproject.toml.orig +1 -1
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/attest.py +12 -5
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/cli.py +5 -4
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/evidence.py +2 -2
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/fitness/manifests.py +2 -2
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/project.py +7 -3
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/pull_request.py +48 -10
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/settings.py +127 -19
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/skills.py +71 -37
- {napkinstack-0.32.0 → napkinstack-0.33.0}/LICENSE +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/__init__.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/__main__.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/agent.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/assurance.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/board.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/compat.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/discovery.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/doctor.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/fitness/__init__.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/fitness/boundaries.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/fitness/hygiene.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/fitness/plan.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/fitness/pr_scope.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/hold.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/landed.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/modules.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/owners.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/provenance.py +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/README.md +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/AGENTS.md +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/README.md +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/src/.gitkeep +0 -0
- {napkinstack-0.32.0 → napkinstack-0.33.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.
|
|
3
|
+
Version: 0.33.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.
|
|
25
|
+
> **Status: v0.33.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.
|
|
90
|
-
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.
|
|
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"
|
|
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
|
|
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`;
|
|
130
|
-
| `nstack skills` | Exposes the playbooks as skills for the
|
|
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.
|
|
8
|
+
> **Status: v0.33.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.
|
|
73
|
-
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.
|
|
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"
|
|
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
|
|
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`;
|
|
113
|
-
| `nstack skills` | Exposes the playbooks as skills for the
|
|
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,
|
|
@@ -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
|
|
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 —
|
|
414
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
119
|
-
"
|
|
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,
|
|
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
|
|
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 /
|
|
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
|
-
|
|
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,
|
|
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
|
|
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.
|
|
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
|
-
|
|
693
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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`.
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
|
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
|
|
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
|
|
258
|
-
|
|
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
|
|
264
|
-
"repository,
|
|
265
|
-
"
|
|
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
|
-
|
|
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
|
-
|
|
301
|
-
|
|
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
|
-
|
|
324
|
-
|
|
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
|
|
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
|
|
20
|
-
|
|
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 /
|
|
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
|
|
140
|
-
|
|
141
|
-
|
|
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
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/docs/runbook.md
RENAMED
|
File without changes
|
{napkinstack-0.32.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/tests/.gitkeep
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|