From 48b9e28e86cd26926345a4d39a50d5654b544d0e Mon Sep 17 00:00:00 2001 From: "napkinstack-agent[bot]" <330339777+napkinstack-agent[bot]@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:33:34 +0100 Subject: [PATCH] =?UTF-8?q?D218=20=E2=80=94=20the=20pull=20request=20check?= =?UTF-8?q?=20runs=20on=20the=20pull=20request's=20own=20events=20only?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A review triggered the required « Test sheet and cycle »; on an attested project a code owner usually approves before the record is complete, so that run failed (A2). GitHub keeps it beside the later green run of the same head and the ruleset refused the merge; the notes push that completes the record is no event, and an agent cannot re-run a workflow (#394). The job now runs on pull_request events only. A review or a comment is a verifier's hand read at the next run, which any edit of the description starts — T2's message and the verification playbook say so. Agent-Session: nstack-os-d218 Co-Authored-By: Claude Opus 5.5 --- docs/governance/workstreams.md | 1 + platform/tests/test_pull_request.py | 4 +++- skeleton/.github/workflows/pull-request.yml | 8 ++++---- skeleton/.nstack/playbooks/verification.md | 5 +++-- src/napkinstack/pull_request.py | 5 +++-- 5 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/governance/workstreams.md b/docs/governance/workstreams.md index 527b689d..da3e076f 100644 --- a/docs/governance/workstreams.md +++ b/docs/governance/workstreams.md @@ -231,6 +231,7 @@ state to its index: [`docs/adr/`](../adr/README.md), [`docs/pdr/`](../pdr/README | D215 | **Three limits an agent met by failing first** (#386, #388, #368). On a multi-agent project, 2026-11-13/14: verifier sessions under a sandbox could not follow the playbook's « a worktree of your own, a build cache of your own » — `.git` read-only, the person's cache read-only — and each improvised the same answer; one build in the system's temporary folder filled the person's quota. Agents learned from a 403 that a workflow dispatch, or a change under `.github/workflows/`, is not theirs, and one asked another session to make it. Run locally without labels, `pr-check` failed K3 on an out-of-cycle pull request with no hint, and two sessions misread it | **Done**: `verification.md` names the way that works — a `git clone --shared` at the head, outputs under the agent's own cache, never the system's temporary folder, both deleted. 07 §7 and `nstack agent add`'s output say a dispatch and, without `--workflows`, a workflow change are the person's, and that the agent never asks another session. K3 says when no label was given. Not built: reading the pull request's own labels from the forge — #368's root, kept there. Two assertions seen red first | | D216 | **Out-of-cycle work had no hold** (#385). On a multi-agent project, 2026-11-13/14, about 6 of 14 pull requests were out of cycle — a gap found in review, a flaky check — assigned in a chat message only: two sessions could take one issue unseen. `nstack claim` held only a deliverable of the accepted cycle | **Done**: `nstack claim '#'` holds an issue on `nstack/hold/issues/issue-`, the same events, the same refusal of a second taker, take-over and staleness; its work branches `issue--…`, named from the issue's title when the forge answers; in a framed project or not. On GitHub a comment on the issue says who holds it, as a person writes « I take it »: the assignee stays the person's to set. `nstack unclaim '#'` gives it back once its work is merged — an issue's hold does not end with a cycle; `nstack plan` lists the issues held. `14` and `issue-14` name it too, `#` starting a shell comment. The issue's comment names the person, never an email address. Market: a forge's assignee (GitHub, GitLab, Jira) refuses nobody; the hold, git's first push wins, does on any forge. Not built: K5 for out-of-cycle pull requests — a hold says, it does not yet gate. Five tests seen red first; an independent verifier's findings written in | | D217 | **The platform tests hung while another project ran its end-to-end tests.** On a workstation where a project ran a long end-to-end run, 2026-11-14, the platform suite stopped at the same test, again and again: `test_evidence.py` starts a real run, which waits on the machine's end-to-end lock (`$XDG_RUNTIME_DIR/nstack-e2e.lock`, D84's one run at a time) — held, rightly, by the other project's run | **Done**: every test has a runtime folder of its own (`conftest.py`), so no test ever takes or waits on the machine's lock; the tests of the lock itself already set theirs. Seen red first: the file hung under a held lock, and passes in seconds under the same lock | +| 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 | | 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_pull_request.py b/platform/tests/test_pull_request.py index 7800d3ad..8a9871f7 100644 --- a/platform/tests/test_pull_request.py +++ b/platform/tests/test_pull_request.py @@ -728,7 +728,9 @@ def test_ci_gives_pr_check_the_pull_request_s_number_and_a_read_token(): workflow = yaml.safe_load((Path(__file__).parents[2] / "skeleton/.github/workflows/pull-request.yml") .read_text(encoding="utf-8")) assert workflow["permissions"] == {"contents": "read", "pull-requests": "read"}, workflow["permissions"] - assert workflow[True]["pull_request_review"] == {"types": ["submitted"]}, workflow[True] # a review re-runs it + # D218 (#394): only the pull request's own events run it — a review's failed run stayed beside the + # later green one and blocked the merge; a review is read at the next run, which an edit starts + assert set(workflow[True]) == {"pull_request"}, workflow[True] step = next(step for step in workflow["jobs"]["description"]["steps"] if "pr-check" in step.get("run", "")) assert step["env"]["PR_NUMBER"] == "${{ github.event.pull_request.number }}", step["env"] assert step["env"]["GH_TOKEN"] == "${{ github.token }}", step["env"] diff --git a/skeleton/.github/workflows/pull-request.yml b/skeleton/.github/workflows/pull-request.yml index ffc778f1..0a4bf6e0 100644 --- a/skeleton/.github/workflows/pull-request.yml +++ b/skeleton/.github/workflows/pull-request.yml @@ -2,16 +2,16 @@ name: Pull request # The rules read from the pull request's description: the test sheet # (.nstack/handbook/05-workflow.md §7) and the cycle (.nstack/handbook/project.md). Editing the -# description or a label re-evaluates them on the same head commit; so does a review, which is a -# person's hand on the pull request when they are its named verifier (T2). +# 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). # # The description is untrusted input: it reaches nstack through env:, never a script. on: pull_request: types: [opened, edited, synchronize, reopened, labeled, unlabeled] - pull_request_review: - types: [submitted] permissions: contents: read # the head, and the attested record in the remote's notes (A1, A2) diff --git a/skeleton/.nstack/playbooks/verification.md b/skeleton/.nstack/playbooks/verification.md index 7fd8d833..31afb17a 100644 --- a/skeleton/.nstack/playbooks/verification.md +++ b/skeleton/.nstack/playbooks/verification.md @@ -25,8 +25,9 @@ The session that wrote the change cannot verify it: start another session, with context, or hand the sheet to a human. Sign the sheet with your session's identifier — `Verifier: session ` — or, as a person, `Verifier: @`. CI compares it with the change's authors and refuses a match; each person named must have written the sheet into the -description or reviewed the pull request, under their own account — either starts the check -again; a comment counts too, read at the next run. +description or reviewed or commented on the pull request, under their own account. Writing the +sheet starts the check again; a review or a comment is read at the next run, which any edit of the +description starts. ### Your own ground diff --git a/src/napkinstack/pull_request.py b/src/napkinstack/pull_request.py index a6bc43b2..792c0dbc 100644 --- a/src/napkinstack/pull_request.py +++ b/src/napkinstack/pull_request.py @@ -279,7 +279,7 @@ def traces(root: Path) -> set[str] | str | None: """The accounts whose hand is on the pull request — its description's editors, its reviewers, its commenters —, lower case and without `[bot]`; why they are not read; None with no pull request number, on a workstation, and while `nstack attest` records the head: the hand is - judged on the forge's run, which a review or an edit of the description starts again.""" + judged on the forge's run, which an edit of the description starts again.""" number = os.environ.get("PR_NUMBER", "").strip() if not re.fullmatch(r"[0-9]+", number) or os.environ.get("NSTACK_ATTESTING"): return None @@ -336,7 +336,8 @@ def check_verifier(verifier: str, authorship: tuple[set[str], set[str], list[str fail("T2", f"Test sheet: the verifier @{named} left no trace on this pull request — no edit of its " "description, no review, no comment: the sheet says who should have verified, not who did.\n" f" Action: @{named} runs the sheet and writes it in the description, or reviews it; or the " - "sheet names only who did (.nstack/playbooks/verification.md).") + "sheet names only who did (.nstack/playbooks/verification.md). A review or a comment is read at " + "the next run: an edit of the description starts one.") def _result(cell: str) -> str: