napkinstack 0.31.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.31.0 → napkinstack-0.33.0}/PKG-INFO +10 -10
- {napkinstack-0.31.0 → napkinstack-0.33.0}/README.md +9 -9
- {napkinstack-0.31.0 → napkinstack-0.33.0}/pyproject.toml +2 -1
- {napkinstack-0.31.0 → napkinstack-0.33.0}/pyproject.toml.orig +2 -1
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/attest.py +171 -38
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/cli.py +17 -6
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/doctor.py +18 -6
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/evidence.py +2 -2
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/fitness/manifests.py +2 -2
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/hold.py +42 -15
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/project.py +7 -3
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/pull_request.py +71 -16
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/settings.py +135 -24
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/skills.py +71 -37
- {napkinstack-0.31.0 → napkinstack-0.33.0}/LICENSE +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/__init__.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/__main__.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/agent.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/assurance.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/board.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/compat.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/discovery.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/fitness/__init__.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/fitness/boundaries.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/fitness/hygiene.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/fitness/plan.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/fitness/pr_scope.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/landed.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/modules.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/owners.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/provenance.py +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/AGENTS.md +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/MANIFEST.yaml +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/README.md +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/docs/runbook.md +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/contracts/tests/.gitkeep +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/AGENTS.md +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/MANIFEST.yaml +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/README.md +0 -0
- {napkinstack-0.31.0 → napkinstack-0.33.0}/src/napkinstack/templates/module/src/.gitkeep +0 -0
- {napkinstack-0.31.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,
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "napkinstack"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.33.0"
|
|
4
4
|
description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
|
|
5
5
|
requires-python = ">=3.12"
|
|
6
6
|
license = "MIT"
|
|
@@ -24,6 +24,7 @@ nstack = "napkinstack.cli:main"
|
|
|
24
24
|
|
|
25
25
|
[dependency-groups]
|
|
26
26
|
dev = ["pytest==9.1.1"]
|
|
27
|
+
audit = ["pip-audit==2.10.1"]
|
|
27
28
|
|
|
28
29
|
[tool.uv]
|
|
29
30
|
required-version = ">=0.12.14,<0.13"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "napkinstack"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.33.0"
|
|
4
4
|
description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
|
|
5
5
|
requires-python = ">=3.12"
|
|
6
6
|
license = "MIT"
|
|
@@ -18,6 +18,7 @@ nstack = "napkinstack.cli:main"
|
|
|
18
18
|
|
|
19
19
|
[dependency-groups]
|
|
20
20
|
dev = ["pytest==9.1.1"]
|
|
21
|
+
audit = ["pip-audit==2.10.1"] # CI's audit of the lock (D234), never installed by uv sync
|
|
21
22
|
|
|
22
23
|
[tool.uv]
|
|
23
24
|
required-version = ">=0.12.14,<0.13"
|
|
@@ -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.
|
|
@@ -132,20 +133,92 @@ def unplaced(value, root: Path):
|
|
|
132
133
|
return value
|
|
133
134
|
|
|
134
135
|
|
|
135
|
-
def
|
|
136
|
-
"""The
|
|
136
|
+
def _lines(root: Path, commit: str) -> list[dict]:
|
|
137
|
+
"""The runs and voids a commit's note holds, in no order: notes merge line by line, sorted."""
|
|
137
138
|
shown = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False)
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
runs = []
|
|
141
|
-
for line in shown.stdout.splitlines():
|
|
139
|
+
found = []
|
|
140
|
+
for line in shown.stdout.splitlines() if shown.returncode == 0 else []:
|
|
142
141
|
try:
|
|
143
142
|
run = json.loads(line)
|
|
144
143
|
except json.JSONDecodeError:
|
|
145
144
|
continue
|
|
146
145
|
if isinstance(run, dict) and run.get("record") == RECORD and run.get("commit") == commit:
|
|
147
|
-
|
|
148
|
-
return
|
|
146
|
+
found.append(run)
|
|
147
|
+
return found
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def voided_runs(root: Path, commit: str) -> set[str]:
|
|
151
|
+
"""The runs of a commit a void named, by their time (#429): each void lists the runs the note
|
|
152
|
+
held when it was made, so a clock ahead or a merge of notes never brings one back."""
|
|
153
|
+
return {str(at) for line in _lines(root, commit) if line.get("void") and isinstance(line.get("voids"), list)
|
|
154
|
+
for at in line["voids"]}
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def latest(root: Path, commit: str) -> dict | None:
|
|
158
|
+
"""The record of a commit: the latest run its note holds that no void named; else its latest
|
|
159
|
+
void, when every run was voided; else None."""
|
|
160
|
+
lines = _lines(root, commit)
|
|
161
|
+
gone = voided_runs(root, commit)
|
|
162
|
+
runs = [line for line in lines if not line.get("void") and str(line.get("at", "")) not in gone]
|
|
163
|
+
voids = [line for line in lines if line.get("void")]
|
|
164
|
+
return max(runs or voids, key=lambda run: str(run.get("at", "")), default=None)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def kept_from_voided(root: Path, check: dict, commit: str) -> bool:
|
|
168
|
+
"""Whether a check a record kept comes from a run since voided (#429): its first run, on the
|
|
169
|
+
commit it was kept from, or on this one."""
|
|
170
|
+
first = check.get("kept_from") if isinstance(check, dict) else None
|
|
171
|
+
return bool(first) and str(first) in voided_runs(root, str(check.get("kept_commit") or commit))
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def void(root: Path, ref: str, reason: str, base: str = "origin/main", accept_identity: bool = False) -> int:
|
|
175
|
+
"""Marks a commit's record as known unsound — a run that shared what it must not, a tool that
|
|
176
|
+
lied (#429): a line of its own in the note naming every run the note holds. None of them is a
|
|
177
|
+
record afterwards, nor kept from, on its commit or through another commit's record (D223), and
|
|
178
|
+
pr-check reads the head unattested until it is attested again. The runs stay in the note:
|
|
179
|
+
evidence is never rewritten."""
|
|
180
|
+
reason = " ".join(reason.split())
|
|
181
|
+
if not reason:
|
|
182
|
+
print("FAIL [attest] a void says why: the next reader of the record is owed the reason.\n"
|
|
183
|
+
' Action: nstack attest --void <commit> --reason "<what made it unsound>".')
|
|
184
|
+
return 1
|
|
185
|
+
who, refused = _publishable(root, base, accept_identity)
|
|
186
|
+
if refused:
|
|
187
|
+
print(refused.replace("the record would", "the void would"))
|
|
188
|
+
return 1
|
|
189
|
+
commit = _git(root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}", check=False).stdout.strip()
|
|
190
|
+
remote, unread = read_remote(root)
|
|
191
|
+
if remote is not None and unread:
|
|
192
|
+
print(f"FAIL [attest] the notes of {remote} are not read ({unread}): a void names every run they hold, "
|
|
193
|
+
"and one unread would stay a record.\n Action: fix the access, then again.")
|
|
194
|
+
return 1
|
|
195
|
+
runs = [line for line in _lines(root, commit) if not line.get("void")] if commit else []
|
|
196
|
+
if not runs:
|
|
197
|
+
print(f"FAIL [attest] no record of {ref} to void: nothing is kept from a run that was never recorded.\n"
|
|
198
|
+
" Action: name the commit whose record is unsound (git notes --ref=nstack/checks list).")
|
|
199
|
+
return 1
|
|
200
|
+
line = {"record": RECORD, "commit": commit,
|
|
201
|
+
"at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="microseconds"),
|
|
202
|
+
"by": who, "void": unplaced(reason, root), "voids": sorted(str(run.get("at", "")) for run in runs),
|
|
203
|
+
"checks": []}
|
|
204
|
+
before = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False).stdout.rstrip("\n")
|
|
205
|
+
subprocess.run(["git", "notes", f"--ref={NOTES}", "add", "--force", "--file=-", commit], cwd=root,
|
|
206
|
+
input=before + "\n" + json.dumps(line, separators=(",", ":"), ensure_ascii=False) + "\n",
|
|
207
|
+
text=True, capture_output=True, check=True)
|
|
208
|
+
if not (latest(root, commit) or {}).get("void"):
|
|
209
|
+
print(f"FAIL [attest] the void of {commit[:12]} is written, yet a run stays its record.\n"
|
|
210
|
+
" Action: report it: git notes --ref=nstack/checks show " + commit[:12])
|
|
211
|
+
return 1
|
|
212
|
+
where, pushed = "local only: no remote", True
|
|
213
|
+
if remote is not None:
|
|
214
|
+
sent = _git(root, "push", "--quiet", remote, f"refs/notes/{NOTES}", check=False)
|
|
215
|
+
pushed = sent.returncode == 0
|
|
216
|
+
where = f"pushed to {remote}" if pushed else f"NOT pushed to {remote}: {sent.stderr.strip()}"
|
|
217
|
+
print(f"Record of {commit[:12]}: voided by {who} — {line['void']}; {where}; {_show(root, commit, 0, 0, line['void'])}.\n"
|
|
218
|
+
+ (" Nothing is kept from it any more; the commit is attested again by nstack attest on it."
|
|
219
|
+
if pushed else " Action: push again (git push " + str(remote) + " refs/notes/" + NOTES
|
|
220
|
+
+ "): until then only this clone knows."))
|
|
221
|
+
return 0 if pushed else 1
|
|
149
222
|
|
|
150
223
|
|
|
151
224
|
def _remote(root: Path) -> str | None:
|
|
@@ -215,7 +288,7 @@ def _session(root: Path, commit: str) -> str | None:
|
|
|
215
288
|
return trailers.strip().splitlines()[0] if trailers.strip() else None
|
|
216
289
|
|
|
217
290
|
|
|
218
|
-
def _show(root: Path, commit: str, passed: int, total: int) -> str:
|
|
291
|
+
def _show(root: Path, commit: str, passed: int, total: int, voided: str | None = None) -> str:
|
|
219
292
|
"""The forge's display, when there is one and a token: never a judgement, a view of the record."""
|
|
220
293
|
from napkinstack import hold # the one reading of the project's GitHub
|
|
221
294
|
|
|
@@ -223,8 +296,9 @@ def _show(root: Path, commit: str, passed: int, total: int) -> str:
|
|
|
223
296
|
if forge is None:
|
|
224
297
|
return hold.unshown(root)
|
|
225
298
|
api, repo, token = forge
|
|
226
|
-
body = json.dumps({"state": "success" if passed == total else "failure", "context": CONTEXT,
|
|
227
|
-
"description": f"
|
|
299
|
+
body = json.dumps({"state": "success" if passed == total and voided is None else "failure", "context": CONTEXT,
|
|
300
|
+
"description": f"voided: {voided}"[:140] if voided is not None
|
|
301
|
+
else f"attested: {passed} of {total}"}).encode()
|
|
228
302
|
request = urllib.request.Request(f"{api}/repos/{repo}/statuses/{commit}", data=body, method="POST",
|
|
229
303
|
headers={"Accept": "application/vnd.github+json",
|
|
230
304
|
"Authorization": f"Bearer {token}"})
|
|
@@ -276,22 +350,53 @@ def _shown(root: Path, base: str) -> set[str]:
|
|
|
276
350
|
REASON = 8 # lines of a failed step shown when it says no FAIL line of its own
|
|
277
351
|
|
|
278
352
|
|
|
353
|
+
EXITED = re.compile(r"FAIL \[\w+\] module '[^']+': `.*` exited with \d+\.")
|
|
354
|
+
|
|
355
|
+
|
|
279
356
|
def why(output: str) -> list[str]:
|
|
280
357
|
"""A failed step's reason: its FAIL lines and the indented lines under each (the action), or,
|
|
281
|
-
when it says none, its last lines — a check that failed says why without its whole output (#244).
|
|
358
|
+
when it says none, its last lines — a check that failed says why without its whole output (#244).
|
|
359
|
+
A module command that exited non-zero says no more than its code: the last lines its own tool
|
|
360
|
+
wrote before it come first — a test runner's summary names the test that failed (#428)."""
|
|
282
361
|
lines = output.splitlines()
|
|
283
|
-
said, under = [], False
|
|
362
|
+
said, under, tool, audit = [], False, [], False
|
|
284
363
|
for line in lines:
|
|
285
364
|
if line.startswith("FAIL"):
|
|
365
|
+
if EXITED.match(line):
|
|
366
|
+
said.extend(tool[-REASON:])
|
|
367
|
+
tool = []
|
|
286
368
|
said.append(line)
|
|
287
369
|
under = True
|
|
288
370
|
elif under and line.startswith(" "):
|
|
289
371
|
said.append(line)
|
|
290
372
|
else:
|
|
291
373
|
under = False
|
|
374
|
+
if line.startswith(("::group::", "-> ")):
|
|
375
|
+
tool, audit = [], False # a module's own command writes after the engine says it runs it
|
|
376
|
+
elif line.startswith("Evidence of "):
|
|
377
|
+
audit = True # and before the engine audits its evidence: those lines are the engine's
|
|
378
|
+
elif line.strip() and not audit and not line.startswith(("FAIL", "::")):
|
|
379
|
+
tool.append(line)
|
|
292
380
|
return said or [line for line in lines if line.strip()][-REASON:]
|
|
293
381
|
|
|
294
382
|
|
|
383
|
+
LOG_KEPT = 8 * 1024 * 1024 # bytes of a failed step's output kept in its log, the last ones
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
def keep_log(root: Path, commit: str, check: str, steps: list[tuple[str, str]]) -> Path:
|
|
387
|
+
"""A failed check's whole output, in the clone's git folder — never in the tree, where it would
|
|
388
|
+
leave changes the next attest refuses: the record keeps 64 KiB of it and a FAIL line a few
|
|
389
|
+
lines; a test that fails once and passes again is named here, or nowhere (#428). Its last
|
|
390
|
+
8 MiB when longer; the next failure of the same commit and check replaces it."""
|
|
391
|
+
folder = (root / _git(root, "rev-parse", "--git-path", "nstack/attest").stdout.strip()).resolve()
|
|
392
|
+
folder.mkdir(parents=True, exist_ok=True)
|
|
393
|
+
path = folder / f"{commit[:12]}-{re.sub(r'[^a-z0-9]+', '-', check.lower()).strip('-')}.log"
|
|
394
|
+
text = steps[0][1] if len(steps) == 1 else "".join(f"== {label}\n{output.rstrip(chr(10))}\n" for label, output in steps)
|
|
395
|
+
data = text.encode("utf-8", "replace")
|
|
396
|
+
path.write_bytes(data if len(data) <= LOG_KEPT else data[-LOG_KEPT:])
|
|
397
|
+
return path
|
|
398
|
+
|
|
399
|
+
|
|
295
400
|
# An engine whose code a string names: published, a forge's commit, or a checkout's own commit.
|
|
296
401
|
NAMED = re.compile(r".* \(commit [0-9a-f]{7,}\)|.*@[0-9a-f]{7,}|a local checkout at (?!an unknown commit)\S+(?<!-dirty)")
|
|
297
402
|
|
|
@@ -301,13 +406,17 @@ FRESH_COMMITS = 20 # and the default branch moved by at most this many commits
|
|
|
301
406
|
|
|
302
407
|
|
|
303
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/")
|
|
304
412
|
|
|
305
413
|
|
|
306
414
|
def inputs(root: Path, base: str, identity: str = "") -> str | None:
|
|
307
415
|
"""The digest of what `Module checks` reads at HEAD (ADR-0006 decision 2, D223): the folders of
|
|
308
416
|
the modules it runs, of those they consume from or assemble, every tracked path outside the
|
|
309
|
-
module folders — `contracts/` and `platform/` included, which every module reads —
|
|
310
|
-
|
|
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."""
|
|
311
420
|
import yaml
|
|
312
421
|
|
|
313
422
|
from napkinstack import modules
|
|
@@ -338,10 +447,12 @@ def inputs(root: Path, base: str, identity: str = "") -> str | None:
|
|
|
338
447
|
return None
|
|
339
448
|
lines.append(f"{folder} {tree}")
|
|
340
449
|
inside = tuple(f"{folder}/" for folder in every.values() if folder.split("/", 1)[0] not in SHARED_MODULES)
|
|
341
|
-
|
|
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)
|
|
342
452
|
if listed.returncode:
|
|
343
453
|
return None
|
|
344
|
-
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))]
|
|
345
456
|
return hashlib.sha256("\n".join(lines).encode("utf-8", "surrogateescape")).hexdigest()
|
|
346
457
|
|
|
347
458
|
|
|
@@ -367,7 +478,7 @@ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine:
|
|
|
367
478
|
if digest is None or not check.kept or base_commit is None or not (origin is None or NAMED.fullmatch(origin)):
|
|
368
479
|
return None
|
|
369
480
|
for commit in _git(root, "rev-list", f"{base_commit}..HEAD", check=False).stdout.split():
|
|
370
|
-
record = latest(root, commit)
|
|
481
|
+
record = latest(root, commit) # a voided commit's latest line is its void: no check is kept from it
|
|
371
482
|
if record is None or (record.get("engine"), record.get("origin"), record.get("published"),
|
|
372
483
|
record.get("by")) != (engine, said, origin is None, who):
|
|
373
484
|
continue
|
|
@@ -375,6 +486,8 @@ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine:
|
|
|
375
486
|
found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
|
|
376
487
|
if not found or found.get("passed") is not True or found.get("inputs") != digest:
|
|
377
488
|
continue
|
|
489
|
+
if kept_from_voided(root, found, commit):
|
|
490
|
+
continue # kept, through this record, from a run since voided (#429)
|
|
378
491
|
first = str(found.get("kept_from") or record.get("at", ""))
|
|
379
492
|
run_base = found.get("kept_base") or record.get("base_commit")
|
|
380
493
|
if not _fresh(root, first, run_base, base_commit):
|
|
@@ -384,7 +497,7 @@ def _by_inputs(root: Path, base: str, digest: str | None, check: Check, engine:
|
|
|
384
497
|
|
|
385
498
|
|
|
386
499
|
def _kept(previous: dict | None, check: Check, engine: str, origin: str | None, base_commit: str | None,
|
|
387
|
-
who: str, said: str | None = None) -> dict | None:
|
|
500
|
+
who: str, said: str | None = None, root: Path | None = None) -> dict | None:
|
|
388
501
|
"""The check as the commit's record last passed it, when what it reads is the same: the commit,
|
|
389
502
|
the base commit, the engine — published, or one whose commit names its code — and the person who
|
|
390
503
|
ran it. A sheet filled in between changes the description, which this check never reads (#275).
|
|
@@ -399,6 +512,8 @@ def _kept(previous: dict | None, check: Check, engine: str, origin: str | None,
|
|
|
399
512
|
found = next((c for c in checks if isinstance(c, dict) and c.get("name") == check.name), None)
|
|
400
513
|
if not found or found.get("passed") is not True or found.get("kept_commit"):
|
|
401
514
|
return None # kept by its inputs from another commit: its freshness is _by_inputs' to judge (D223)
|
|
515
|
+
if root is not None and kept_from_voided(root, found, str(previous.get("commit", ""))):
|
|
516
|
+
return None # kept, on this commit, from a run since voided: a clone that had not seen the void (#429)
|
|
402
517
|
return {**found, "kept_from": found.get("kept_from") or previous.get("at")}
|
|
403
518
|
|
|
404
519
|
|
|
@@ -416,26 +531,34 @@ def sheet_of(body: str) -> dict | None:
|
|
|
416
531
|
return found or None
|
|
417
532
|
|
|
418
533
|
|
|
419
|
-
def
|
|
420
|
-
|
|
421
|
-
|
|
534
|
+
def _publishable(root: Path, base: str, accept_identity: bool) -> tuple[str, str | None]:
|
|
535
|
+
"""Who a line of the notes will name, and why it may not travel: the notes go to the remote, and
|
|
536
|
+
never publish an address the project does not already show (#235) — a run's record, or a void."""
|
|
422
537
|
who, address = _identity(root)
|
|
423
538
|
remote = _remote(root)
|
|
424
539
|
if remote is not None and not accept_identity and not NOREPLY.fullmatch(address):
|
|
425
540
|
if _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).returncode != 0:
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
return 1
|
|
541
|
+
return who, (f"FAIL [attest] base '{base}' not found: the identities the project already shows cannot "
|
|
542
|
+
f"be read, and the record would travel to {remote}.\n"
|
|
543
|
+
" Action: fetch the base (git fetch), or pass --base with a commit of the shared history.")
|
|
430
544
|
# No remote: nothing travels — the record stays in this repository, whoever ran it.
|
|
431
545
|
if remote is not None and not accept_identity and not NOREPLY.fullmatch(address) and address not in _shown(root, base):
|
|
432
546
|
# A record travels with the notes to the remote: it never publishes an address the project
|
|
433
547
|
# does not already show — a fresh clone falls back on a workstation's personal identity (#235).
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
548
|
+
return who, (f"FAIL [attest] the record would name {who or 'no one'}, an identity this project's history "
|
|
549
|
+
f"does not show — it travels with the notes to {remote}.\n"
|
|
550
|
+
" Action: set this checkout's identity to the one the project works under "
|
|
551
|
+
"(git config user.name / user.email), or, for a first record of your own, "
|
|
552
|
+
"nstack attest --accept-identity.")
|
|
553
|
+
return who, None
|
|
554
|
+
|
|
555
|
+
|
|
556
|
+
def run(root: Path, base: str, body_file: Path | None, labels: str | None, accept_identity: bool = False,
|
|
557
|
+
again: bool = False) -> int:
|
|
558
|
+
print(provenance.judged_by(root), flush=True)
|
|
559
|
+
who, refused = _publishable(root, base, accept_identity)
|
|
560
|
+
if refused:
|
|
561
|
+
print(refused)
|
|
439
562
|
return 1
|
|
440
563
|
if _git(root, "status", "--porcelain", "--untracked-files=normal").stdout.strip():
|
|
441
564
|
print("FAIL [attest] the tree holds changes: a record names one commit, and this tree is none.\n"
|
|
@@ -445,6 +568,7 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
445
568
|
engine, origin = provenance.engine()
|
|
446
569
|
base_commit = _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", check=False).stdout.strip() or None
|
|
447
570
|
previous = None if again else latest(root, commit)
|
|
571
|
+
previous = None if previous and previous.get("void") else previous # a void keeps nothing, evidence included
|
|
448
572
|
# The option, else PR_LABELS as the caller set it: one way for attest and pr-check (D147) — and the
|
|
449
573
|
# pull request's own when the forge answers, a label it does not carry refused (#368).
|
|
450
574
|
from napkinstack.pull_request import labels_for
|
|
@@ -470,7 +594,7 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
470
594
|
digest = inputs(root, base, json.dumps([engine, unplaced(origin, root), origin is None, who]))
|
|
471
595
|
env["NSTACK_INPUTS"] = digest or "" # the head's, for pr-check's T4 while this record is made (D223)
|
|
472
596
|
for check in CHECKS:
|
|
473
|
-
kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root))
|
|
597
|
+
kept = _kept(previous, check, engine, origin, base_commit, who, unplaced(origin, root), root)
|
|
474
598
|
if kept is not None:
|
|
475
599
|
results.append(kept)
|
|
476
600
|
print(f"ok [attest] {check.name}: kept from the record of {kept['kept_from']} — same commit, base "
|
|
@@ -484,21 +608,30 @@ def run(root: Path, base: str, body_file: Path | None, labels: str | None, accep
|
|
|
484
608
|
f"same inputs ({digest[:12]}), within {FRESH_DAYS} days and {FRESH_COMMITS} commits of the "
|
|
485
609
|
"default branch (nstack attest --again runs it)", flush=True)
|
|
486
610
|
continue
|
|
487
|
-
steps = []
|
|
611
|
+
steps, outputs = [], []
|
|
488
612
|
for step in check.steps:
|
|
489
|
-
done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env,
|
|
490
|
-
|
|
613
|
+
done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env, stdout=subprocess.PIPE,
|
|
614
|
+
stderr=subprocess.STDOUT, text=True, errors="replace")
|
|
491
615
|
steps.append({"label": step.label, "command": step.command, "exit": done.returncode,
|
|
492
616
|
"output": capped(done.stdout),
|
|
493
617
|
"sha256": hashlib.sha256(done.stdout.encode("utf-8", "replace")).hexdigest()})
|
|
618
|
+
outputs.append(done.stdout)
|
|
494
619
|
passed = all(step["exit"] == 0 for step in steps)
|
|
495
620
|
results.append({"name": check.name, "passed": passed, "steps": steps,
|
|
496
621
|
**({"inputs": digest} if check.kept and digest else {})})
|
|
497
622
|
failed = "; ".join(f"{s['label']} exited {s['exit']}" for s in steps if s["exit"])
|
|
498
623
|
print(f"FAIL [attest] {check.name}: {failed}" if failed else f"ok [attest] {check.name}", flush=True)
|
|
499
|
-
for step in steps:
|
|
624
|
+
for step, whole in zip(steps, outputs):
|
|
500
625
|
if step["exit"]:
|
|
501
|
-
print("\n".join(f" {line}" for line in why(
|
|
626
|
+
print("\n".join(f" {line}" for line in why(whole)), flush=True)
|
|
627
|
+
if failed:
|
|
628
|
+
try:
|
|
629
|
+
log = keep_log(root, commit, check.name, [(s["label"], o) for s, o in zip(steps, outputs)])
|
|
630
|
+
except OSError as error: # a full or read-only disk never costs the record
|
|
631
|
+
print(f" whole output: not kept ({error.strerror})", flush=True)
|
|
632
|
+
else:
|
|
633
|
+
shown = log.relative_to(root) if log.is_relative_to(root) else log
|
|
634
|
+
print(f" whole output: {shown}", flush=True)
|
|
502
635
|
record = {"record": RECORD, "commit": commit,
|
|
503
636
|
"at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="microseconds"),
|
|
504
637
|
"engine": engine, "origin": origin, "published": origin is None, "by": who, "session": _session(root, commit),
|
|
@@ -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")
|
|
@@ -176,7 +177,8 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
176
177
|
ld.add_argument("--span", default="HEAD~1..HEAD",
|
|
177
178
|
help="the commits to read, BEFORE..AFTER (default: the last commit)")
|
|
178
179
|
at = _add(sub, "attest", "runs the CI's checks here and records the run on the commit, in git",
|
|
179
|
-
lambda a: attest.
|
|
180
|
+
lambda a: attest.void(a.root, a.void, a.reason or "", a.base, a.accept_identity) if a.void
|
|
181
|
+
else attest.run(a.root, a.base, a.body_file, a.labels, a.accept_identity, a.again))
|
|
180
182
|
at.add_argument("--base", default="origin/main")
|
|
181
183
|
at.add_argument("--body-file", type=Path, help="the pull request's description, for its checks")
|
|
182
184
|
at.add_argument("--labels", help="the pull request's labels, comma-separated (default: PR_LABELS); with a "
|
|
@@ -185,6 +187,10 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
185
187
|
help="record under an identity the project's history does not show yet — a first record of yours")
|
|
186
188
|
at.add_argument("--again", action="store_true",
|
|
187
189
|
help="runs every check, even the module checks this commit's record passed with the same base and engine")
|
|
190
|
+
at.add_argument("--void", metavar="COMMIT",
|
|
191
|
+
help="marks COMMIT's record as known unsound, with --reason: no check is kept from it any more, "
|
|
192
|
+
"and pr-check reads it unattested until attested again; nothing runs")
|
|
193
|
+
at.add_argument("--reason", help="why the record is unsound, with --void")
|
|
188
194
|
cl = _add(sub, "claim", "takes a ready deliverable for a session, before its first change; "
|
|
189
195
|
"the shared remote refuses a second taker",
|
|
190
196
|
lambda a: hold.claim(a.root, a.deliverable, a.session, a.person, a.take_over))
|
|
@@ -193,7 +199,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
193
199
|
cl.add_argument("--session", help="the agent's session, written on the hold")
|
|
194
200
|
cl.add_argument("--person", help="the person accountable, such as @alice (default: git's user)")
|
|
195
201
|
cl.add_argument("--take-over", action="store_true",
|
|
196
|
-
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")
|
|
197
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",
|
|
198
204
|
lambda a: hold.release(a.root, a.deliverable, a.session, a.person))
|
|
199
205
|
rs.add_argument("deliverable", help="the deliverable's identifier, D<n>, or '#<n>', an issue")
|
|
@@ -314,7 +320,12 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
314
320
|
os.environ.pop(name, None)
|
|
315
321
|
if late := provenance.behind(_named_root(argv)):
|
|
316
322
|
print(late, file=sys.stderr, flush=True)
|
|
317
|
-
|
|
323
|
+
parser = build_parser()
|
|
324
|
+
args = parser.parse_args(argv)
|
|
325
|
+
if args.command == "attest" and (bool(args.void) != bool(args.reason) or (args.void and (args.again or args.body_file
|
|
326
|
+
or args.labels))):
|
|
327
|
+
parser.error("attest: --void and --reason go together, and with no run: never with --again, "
|
|
328
|
+
"--body-file or --labels")
|
|
318
329
|
if args.command in JUDGES:
|
|
319
330
|
print(provenance.judged_by(args.root), flush=True)
|
|
320
331
|
if said := plan.stage_line(args.root):
|