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