diff --git a/docs/adr/0004-give-agents-their-own-github-identity.md b/docs/adr/0004-give-agents-their-own-github-identity.md index 78da449d..ce5f3d66 100644 --- a/docs/adr/0004-give-agents-their-own-github-identity.md +++ b/docs/adr/0004-give-agents-their-own-github-identity.md @@ -153,7 +153,7 @@ accepted result · red: the refusal · dotted cross: what the agent's session ne | Element | Choice | Verified fact | |---|---|---| | Identity | One GitHub App per organisation, installed only on the repositories where agents work | An App consumes no seat | -| Permissions | Contents, Pull requests, Issues: read and write; Actions, Checks: read. Workflows: write only where agents maintain CI, as in this repository. Never Administration | The App's permissions bound every token | +| Permissions | Contents, Pull requests, Issues: read and write; Actions, Checks: read; Commit statuses: write, the record's own status (D221). Workflows: write only where agents maintain CI, as in this repository. Never Administration | The App's permissions bound every token | | Credentials | The private key in the workstation's secret store or the CI's secrets, never in a repository; tokens limited to the repository | Tokens expire after 1 hour and can be narrowed | | The agent's session | Reaches no human credential: no SSH key, token or GitHub CLI login of a human (a sandbox, a container or a dedicated system user) | Otherwise the agent approves under a human's name | | Merge | Ruleset on the main branch: pull request, at least 1 approval, code owner review, required checks, **empty bypass list** | Administrators bypass only when listed: with an empty list, this repository's ruleset answers `current_user_can_bypass: never` to the organisation owner | diff --git a/docs/governance/workstreams.md b/docs/governance/workstreams.md index 7c5b10e3..50eadd69 100644 --- a/docs/governance/workstreams.md +++ b/docs/governance/workstreams.md @@ -234,6 +234,7 @@ state to its index: [`docs/adr/`](../adr/README.md), [`docs/pdr/`](../pdr/README | D218 | **A review's failed run blocked the merge for good** (#394). On an attested project, 2026-11-14, a code owner approved before the record was complete — the usual moment —: « Test sheet and cycle », triggered by the review, failed (A2). The record completed by a notes push, which is no event; a later run of the same head passed, and the ruleset still refused the merge on the review's run, kept beside it. An agent cannot re-run a workflow: the person had to | **Done**: the job runs on the pull request's own events only. A review or a comment stays a verifier's hand (T2), read at the next run, which any edit of the description starts — an agent's included; T2's message and the verification playbook say so. Not chosen: skipping the job on a review, which leaves a required check « skipped », counted as passed; a separate job, since this one reads no approval. A pull request already blocked by a review's failed run is unblocked by a new push, whose head starts afresh — or, before taking this version, by a new review; never by an edit, nor by a re-run, which replays the old event's payload and fails again (seen on that project). The workflow's test seen red first | | D219 | **A workflow red on the default branch went unseen** (#387). On a desktop project, 2026-11-07 to 13, the Windows packaging workflow failed on every run of the default branch — six runs — and was noticed by chance: it is no required check, so every pull request merged green beside it | **Done**: `nstack doctor` reads, workflow by workflow — a quiet one, filtered by `paths:` or scheduled, never drops out of a window busier ones fill — the last completed runs of the default branch's own events (push, schedule, dispatch: never a pull request's, a fork's included) with the token it already has (Actions: read). It says, as information (N2) that never changes its exit, each active workflow whose last three or more runs all failed — timed out and failed to start count — with the first failure's link; cancelled and skipped runs say nothing either way. Unreadable runs are said, with the permission to add. Market: GitHub shows a red run and notifies nobody once the check is not required. Not built: a fitness check on a `paths:` filter that leaves out a module its jobs build, until it pays. Three tests seen red first; an independent verifier's findings written in (the per-workflow read, forks' runs, timeouts) | | D220 | **An update left the generated skills behind.** On a multi-agent project taking v0.29.0, 2026-11-14, the first `nstack attest` after `nstack update` failed Fitness on S3 — skill 'verification' out of sync with its playbook: the update moved the playbook, and the skills, generated and git-ignored, stayed as they were. Neither the update's output nor its next step said to run `nstack skills` | **Done**: where the person generated skills (`.claude/skills/`), `nstack update` generates them again from the updated playbooks and says so — derived files, git-ignored, nothing of anyone's lost; what stops it is said with its action; an update stopped on conflicts says `nstack skills` in its action. `nstack skills` removes a generated skill whose playbook is gone — still loaded by the agent, said by no rule — never one a person wrote. Market: a package manager's post-install step regenerates what it derives. The update scenario and the orphan's test seen red first; an independent verifier's findings written in | +| D221 | **An attested record never re-ran the pull request's check.** On a multi-agent project on v0.29.0, 2026-11-14 (#399), every pull request stayed BLOCKED after a 5/5 record: the record holds the description's sheet (D214), so it is made after the last edit, and it travels by notes, which start no run; the run from before it stayed red. The approval's run had hidden it until D218. Only an edit of the description unblocked it | **Done**: where the base branch's ruleset requires `nstack / local checks` — the status `nstack attest` already posts with the record (PDR-0013 §3) — the pull request's run leaves A1 and A2 to it and says so, read from the branch's rules with the job's token; unread or not required, the run judges the record as before, and A1's action names both ways out. An agent's App gets Commit statuses: write. Market: a result made outside CI reaches the forge as a commit status a ruleset requires — Jenkins, Buildkite, basecamp/gh-signoff. Tests seen red first | | v0.6.0 | **What is announced refuses, and the documents say what is true**: D51 to D54, and the documentary lot of the internal audit | **Done (2026-09-20)**: five workstreams merged (#83, #84, #85, #86, #87), **v0.6.0 published**, tag on `8ae544c`, verified on published artefacts — including an update of `tool-library` from v0.5.0, 9 files and no conflict, still compliant. Found doing it: D55. Next: the pilot, and M11 beside it | | Pilot | **`NapkinStack/flet`, the first real project**, run by a session that knew nothing of this repository, with the maintainer as decider and this repository's agent as observer — public on the Free plan, where the whole checklist is available, rather than private on Team where G5 is paid and G6 does not exist | **Set aside by the maintainer, 2026-10-15**, at its cycle boundary; the real product followed since is `summit`. **Ran from 2026-09-20**: discovery decided *go* after three rounds and two independent challenges, charter accepted; cycle 01 closed `stopped/reframed`, **cycle 02 closed** with two deliverables accepted and one deferred (its #27), **cycle 03 framed and approved** (#28, #30), which starts its first `critical` module; the framework taken to v0.6.1 by itself at the boundary (#29), v0.6.2 proposed (#31). It has produced D56 to D63, D68, D70 to D77, replicated D26 and D55, and measured D49 — the first figures on what an independent verifier finds (PDR-0003) | | M11 | **Ceremony follows consequence** (PDR-0011): the framework charges what a failure costs, per module and per project, and states each price before it is paid; with PDR-0004's routing, and PDR-0007, PDR-0008 and PDR-0010 — through to v0.7.0 | **Published as v0.7.0 (2026-10-12).** Planned 2026-09-23 (#98). Merged: **M11f** (#101), **M11a** (#102), **M11b** (#103), **M11d** (#104), **M11e** (#105), **M11c** (#106), **M11h** (#107), **M11g** (#108) closed by its probe — not clean, returned to M13; **M11m** (D68, D74, D75); **M11l** (PDR-0010, D59, D60); **M11n** (D79); **M11o** (PDR-0010 extended: every document has its moment); **M11p** (PDR-0002's three levels given a place: `docs/project/rules/`); **M11j** (PDR-0007: the unframed stage); **M11q** (no folder created empty; PDR-0012 proposed: a project's tree is the project's). **M11k** (PDR-0008's print mode: `nstack settings`; D77, D78). **M11s** (PDR-0012 accepted; the framework's files under `.nstack/`; an update carries what a project adapted); **M11u** (an update rewrites the old addresses a project wrote in its own files, D85). **M11t** (`nstack new-contract`: the contracts module is created by the first contract; PDR-0012 built in full); **M11v** (what the third project found: D81, D82, D83, D86, D87). **M11i**: v0.7.0 published 2026-10-12 (#125, D88). To do: **M11r** PDR-0008's apply mode and D57, after a probe on the real forge; the two earlier projects take v0.7.0 themselves, observed | diff --git a/platform/tests/test_agent.py b/platform/tests/test_agent.py index 732f65c1..24f34158 100644 --- a/platform/tests/test_agent.py +++ b/platform/tests/test_agent.py @@ -168,7 +168,8 @@ def test_one_command_makes_the_app_installs_it_and_configures_an_isolated_clone( assert action.startswith(f"{forge}/organizations/acme/settings/apps/new?state=") assert manifest["public"] is False assert manifest["default_permissions"] == {"contents": "write", "pull_requests": "write", "issues": "write", - "actions": "read", "checks": "read", "metadata": "read"} + "actions": "read", "checks": "read", "metadata": "read", + "statuses": "write"} # the record's status (D221) assert "administration" not in manifest["default_permissions"] assert manifest["hook_attributes"]["active"] is False assert browser.opened[-1] == f"{forge}/apps/demo-scout/installations/new" diff --git a/platform/tests/test_attest.py b/platform/tests/test_attest.py index a6820437..85c3a95c 100644 --- a/platform/tests/test_attest.py +++ b/platform/tests/test_attest.py @@ -10,6 +10,7 @@ import os import subprocess import sys +import urllib.error from pathlib import Path import pytest @@ -602,3 +603,71 @@ def test_an_engine_installed_from_a_path_under_the_home_keeps_its_check(tmp_path attest.run(root, "HEAD", None, "") attest.run(root, "HEAD", None, "") assert runs(root) == 1 + + +def test_in_ci_a_required_local_checks_status_judges_the_record_and_the_run_defers_to_it(tmp_path, monkeypatch, capsys): + """#399: the record is made after the description's last edit (D214) and travels by notes, which + start no run: the run before it stayed red. Where the base branch's rules require the record's + own status, that status — posted by nstack attest with the record — is the record's verdict.""" + project = tmp_path / "p" + project.mkdir() + base, _ = change(project, "attested") + with_remote(project) + monkeypatch.setattr(pull_request, "status_required", lambda root: True) + code, out = judged(project, base, monkeypatch, capsys, ci=True) + assert code == 0 and "FAIL [A1]" not in out, out + assert f"judged by the required status '{attest.CONTEXT}'" in out, out + monkeypatch.setattr(attest, "CHECKS", FAILING) + attest.run(project, base, None, "") + fresh_checkout(project) + code, out = judged(project, base, monkeypatch, capsys, ci=True) + assert code == 0 and "FAIL [A2]" not in out, "a failed record is the status's red, never a run's that stays" + assert "WARNING [A2] the latest record of the head" in out, "a failed record the status may not show is said" + + +def test_in_ci_without_the_required_status_a_head_with_no_record_names_both_ways_out(tmp_path, monkeypatch, capsys): + project = tmp_path / "p" + project.mkdir() + base, _ = change(project, "attested") + with_remote(project) + monkeypatch.setattr(pull_request, "status_required", lambda root: False) + code, out = judged(project, base, monkeypatch, capsys, ci=True) + assert code == 1 and "FAIL [A1]" in out and f"require the status '{attest.CONTEXT}'" in out, out + + +@pytest.mark.parametrize(("rules", "required"), [ + ([{"type": "required_status_checks", "parameters": {"required_status_checks": [ + {"context": "Test sheet and cycle"}, {"context": attest.CONTEXT}]}}], True), + ([{"type": "required_status_checks", "parameters": {"required_status_checks": [ + {"context": "Test sheet and cycle"}]}}, + {"type": "pull_request", "parameters": {"required_status_checks": [{"context": attest.CONTEXT}]}}], False), + (None, False), +]) +def test_the_base_branch_s_rules_say_whether_the_status_is_required(tmp_path, monkeypatch, rules, required): + read = [] + + class Answer: + def __init__(self, request): + read.append(request.full_url) + + def __enter__(self): + if rules is None: + raise urllib.error.URLError("refused") + return self + + def __exit__(self, *_): + return False + + def read(self): + return json.dumps(rules).encode() + + monkeypatch.setattr(pull_request.urllib.request, "urlopen", lambda request, timeout=None: Answer(request)) + monkeypatch.setenv("GITHUB_ACTIONS", "true") + monkeypatch.setenv("GITHUB_REPOSITORY", "owner/p") + monkeypatch.setenv("GITHUB_BASE_REF", "release/1") + monkeypatch.setenv("GH_TOKEN", "t") + monkeypatch.delenv("GITHUB_API_URL", raising=False) + assert pull_request.status_required(tmp_path) is required + assert read == ["https://api.github.com/repos/owner/p/rules/branches/release%2F1?per_page=100"] + monkeypatch.delenv("GITHUB_ACTIONS") + assert pull_request.status_required(tmp_path) is False, "a workstation's pr-check reads the record itself" diff --git a/skeleton/.github/workflows/pull-request.yml b/skeleton/.github/workflows/pull-request.yml index 0a4bf6e0..c0b476af 100644 --- a/skeleton/.github/workflows/pull-request.yml +++ b/skeleton/.github/workflows/pull-request.yml @@ -5,7 +5,8 @@ name: Pull request # description or a label re-evaluates them on the same head commit. A review or a comment is a # person's hand on the pull request when they are its named verifier (T2), read at the next run: # never a trigger, since a review's failed run stays beside the later ones and blocks the merge, -# and an attested record, pushed as notes, is no event that could replace it (D218, #394). +# and an attested record, pushed as notes, is no event that could replace it (D218, #394): its +# event is its own status, `nstack / local checks`, when a ruleset requires it (D221, #399). # # The description is untrusted input: it reaches nstack through env:, never a script. diff --git a/skeleton/.nstack/handbook/07-governance.md b/skeleton/.nstack/handbook/07-governance.md index 21a7d46d..ef3c80c0 100644 --- a/skeleton/.nstack/handbook/07-governance.md +++ b/skeleton/.nstack/handbook/07-governance.md @@ -313,6 +313,15 @@ by a commit with no change of its own — tracked or not. The record says which outside it hold is not compared: `nstack attest --again` runs them. Where the answer is `forge`, a record is information, and on a guarded repository the forge's required checks stay the barrier — a decider who wants the record to gate a protected branch requires its name at the forge. +Where the answer is `attested`, requiring it is what keeps a pull request moving: the record +holds the description's sheet, so it is made after its last edit, and notes start no run — the +pull request's last run, from before the record, would stay red. The status is the record's own +event: when the base branch's ruleset requires `nstack / local checks`, the pull request's run +leaves A1 and A2 to it, and says so. Posting it needs a token that may write commit statuses +(an agent's App made by `nstack agent add` has it; an older App gets Commit statuses: write in +its settings, accepted on its installation); without one, the record is said *not shown*, and +the merge waits. A required name is matched by any check of that name: where every record is an +agent's, the ruleset can pin the status's source to the agent's App. The record names who ran it, as git would sign a commit made in that checkout, and travels to the remote with the notes: it never publishes an address the project's history does not already show. diff --git a/src/napkinstack/agent.py b/src/napkinstack/agent.py index 19547552..75185a9e 100644 --- a/src/napkinstack/agent.py +++ b/src/napkinstack/agent.py @@ -41,7 +41,8 @@ POLL = 3.0 # seconds between two reads of the installation NAME = re.compile(r"^[a-z0-9][a-z0-9-]{0,24}$") PERMISSIONS = {"contents": "write", "pull_requests": "write", "issues": "write", - "actions": "read", "checks": "read", "metadata": "read"} + "actions": "read", "checks": "read", "metadata": "read", + "statuses": "write"} # `nstack / local checks`, posted with the record (D221) # What would let the agent's environment act as the person: their tokens, their SSH agent and # commands, git configuration their shell injects, and the variables that point gh at another host. PERSONAL = ("GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN", "GH_HOST", diff --git a/src/napkinstack/attest.py b/src/napkinstack/attest.py index d01dc04e..a4dcbb2c 100644 --- a/src/napkinstack/attest.py +++ b/src/napkinstack/attest.py @@ -7,7 +7,9 @@ `refs/notes/nstack/checks`, one JSON line per run. The note travels with the branch's remote and is merged line by line; the latest line for a commit is its record. On GitHub, with a token that may write statuses, the run is also shown as `nstack / local checks` — a name no CI job -has. A record is *attested*, never *checked*: it makes a claim traceable, not true. +has. A ruleset that requires that name gates the merge on the record, and the forge's pull +request run leaves the record to it (D221): notes start no run, a status is an event. +A record is *attested*, never *checked*: it makes a claim traceable, not true. Usage : nstack attest [--root ROOT] [--base BASE] [--body-file FILE] [--labels a,b] [--accept-identity] Output: 0 when every check passed, 1 otherwise — the record is written either way. @@ -227,7 +229,9 @@ def _show(root: Path, commit: str, passed: int, total: int) -> str: with urllib.request.urlopen(request, timeout=10): return f"shown on GitHub as '{CONTEXT}'" except (OSError, ValueError) as error: - return f"not shown on GitHub ({error})" + return (f"not shown on GitHub ({error}) — a ruleset requiring '{CONTEXT}' waits for it: a token that " + "may write commit statuses — an older agent App gets Commit statuses: write in its " + "settings, accepted on its installation — then nstack attest again") def evidence_of(root: Path, commit: str) -> list[dict]: diff --git a/src/napkinstack/pull_request.py b/src/napkinstack/pull_request.py index 792c0dbc..61e06cd1 100644 --- a/src/napkinstack/pull_request.py +++ b/src/napkinstack/pull_request.py @@ -56,6 +56,7 @@ import re import subprocess import urllib.error +import urllib.parse import urllib.request from collections.abc import Callable from pathlib import Path @@ -630,6 +631,35 @@ def check_moved(body: str, recorded: list[tuple[str, str, dict]], fail: Fail, wa "description; restore it from the description's history otherwise.") +def status_required(root: Path) -> bool: + """Whether the base branch's rules require the record's own status, `nstack / local checks` + (D221, #399): read on the forge's run only, from the rules that apply to the branch — readable + with the job's token. A record is made after the description's last edit (D214) and travels by + notes, which start no run; its status, posted by `nstack attest` with it, is the event that + says it. Unread — no token, a refusal — is False: the run judges the record itself, as before.""" + from napkinstack import attest + + branch = os.environ.get("GITHUB_BASE_REF", "") + repository = os.environ.get("GITHUB_REPOSITORY") or project.answer(root, "github_repo") or "" + token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN") + if os.environ.get("GITHUB_ACTIONS") != "true" or not branch or not token or "/" not in repository: + return False + api = os.environ.get("GITHUB_API_URL") or "https://api.github.com" + request = urllib.request.Request(f"{api}/repos/{repository}/rules/branches/{urllib.parse.quote(branch, safe='')}" + "?per_page=100", + headers={"Accept": "application/vnd.github+json", "User-Agent": "nstack", + "Authorization": f"Bearer {token}"}) + try: + with urllib.request.urlopen(request, timeout=10) as response: + rules = json.loads(response.read()) + except (OSError, ValueError): + return False + return any(isinstance(rule, dict) and rule.get("type") == "required_status_checks" + and any(isinstance(check, dict) and check.get("context") == attest.CONTEXT + for check in (rule.get("parameters") or {}).get("required_status_checks") or []) + for rule in rules if isinstance(rules, list)) + + def check_attested(root: Path, head: str, fail, warn=lambda message: None) -> str: """Where the checks are judged, as the decider's answer `checks` says (A1, A2): on the forge's CI, or attested on a workstation by `nstack attest` — then a complete, passed record of the @@ -651,6 +681,15 @@ def check_attested(root: Path, head: str, fail, warn=lambda message: None) -> st return "the forge's CI" + shown if os.environ.get("NSTACK_ATTESTING") == head: return "attested — this run is the record being made" + if status_required(root): + if record is not None and not all(check["passed"] for check in record["checks"]): + # The status is the last attest that could post one; a later run without a token is in the + # notes only — said, since the forge's green may be an earlier record's. + warn(f"[A2] the latest record of the head {head[:7]} does not pass, and the status " + f"'{attest.CONTEXT}' may be an earlier record's.\n Action: fix what failed, commit, and run " + "nstack attest again with a token that may write commit statuses.") + return (f"attested — judged by the required status '{attest.CONTEXT}', which nstack attest posts with " + "the record") if record is None and unread and os.environ.get("GITHUB_ACTIONS") == "true": # The record may well be there, out of reach: said, never failed for want of a fetch — and # never the silent line that let an unattested head through (#367). @@ -661,7 +700,9 @@ def check_attested(root: Path, head: str, fail, warn=lambda message: None) -> st if record is None: fail("A1", f"no record of the head {head[:7]}: this project's checks are attested, and none ran on " "this commit.\n Action: run nstack attest on the head, then push — the forge's check reads the " - "record again at its next run: a push, or an edit of the description.") + "record again at its next run: a push, or an edit of the description. Or require the status " + f"'{attest.CONTEXT}' in the branch's ruleset: nstack attest posts it with the record, and this " + "run leaves the record to it (07-governance.md §7).") return "attested — no record of the head" names = [check["name"] for check in record["checks"]] missing = [check.name for check in attest.CHECKS if check.name not in names]