Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/adr/0004-give-agents-their-own-github-identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
1 change: 1 addition & 0 deletions docs/governance/workstreams.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
3 changes: 2 additions & 1 deletion platform/tests/test_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
69 changes: 69 additions & 0 deletions platform/tests/test_attest.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
import os
import subprocess
import sys
import urllib.error
from pathlib import Path

import pytest
Expand Down Expand Up @@ -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"
3 changes: 2 additions & 1 deletion skeleton/.github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
9 changes: 9 additions & 0 deletions skeleton/.nstack/handbook/07-governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion src/napkinstack/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
8 changes: 6 additions & 2 deletions src/napkinstack/attest.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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]:
Expand Down
Loading
Loading