diff --git a/docs/governance/workstreams.md b/docs/governance/workstreams.md index 527b689..da3e076 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 7800d3a..8a9871f 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 ffc778f..0a4bf6e 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 7fd8d83..31afb17 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 a6bc43b..792c0db 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: