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
1 change: 1 addition & 0 deletions docs/governance/workstreams.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 '#<n>'` holds an issue on `nstack/hold/issues/issue-<n>`, the same events, the same refusal of a second taker, take-over and staleness; its work branches `issue-<n>-…`, 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 '#<n>'` 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 |
Expand Down
4 changes: 3 additions & 1 deletion platform/tests/test_pull_request.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
8 changes: 4 additions & 4 deletions skeleton/.github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
5 changes: 3 additions & 2 deletions skeleton/.nstack/playbooks/verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <id>` — or, as a person, `Verifier: @<handle>`. 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

Expand Down
5 changes: 3 additions & 2 deletions src/napkinstack/pull_request.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
Loading