napkinstack 0.9.6__tar.gz → 0.11.0__tar.gz

{napkinstack-0.9.6 → napkinstack-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.9.6
+Version: 0.11.0
 Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
 License-Expression: MIT
 License-File: LICENSE
@@ -20,7 +20,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.9.6, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.11.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -84,8 +84,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.9.6" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.9.6"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.11.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.11.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -120,8 +120,9 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
 | `nstack pr-check` | The test sheet and the cycle, read from the pull request description |
 | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
+| `nstack attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks` |
 | `nstack skills` | Exposes the playbooks as skills for the agent |
-| `nstack update` | Lays the new version on a branch to review |
+| `nstack update [--session <id>]` | Lays the new version on a branch to review; an agent's session as the commit's `Agent-Session` trailer |
 
 **Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
 or on a private one under the Team or Pro plan; on a private repository on the Free plan

{napkinstack-0.9.6 → napkinstack-0.11.0}/README.md

@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.9.6, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.11.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.9.6" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.9.6"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.11.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.11.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -105,8 +105,9 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
 | `nstack pr-check` | The test sheet and the cycle, read from the pull request description |
 | `nstack landed --span <before>..<after>` | What reached this branch outside a pull request, recorded |
+| `nstack attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks` |
 | `nstack skills` | Exposes the playbooks as skills for the agent |
-| `nstack update` | Lays the new version on a branch to review |
+| `nstack update [--session <id>]` | Lays the new version on a branch to review; an agent's session as the commit's `Agent-Session` trailer |
 
 **Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
 or on a private one under the Team or Pro plan; on a private repository on the Free plan

{napkinstack-0.9.6 → napkinstack-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.9.6"
+version = "0.11.0"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.9.6 → napkinstack-0.11.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.9.6"
+version = "0.11.0"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

napkinstack-0.11.0/src/napkinstack/attest.py

@@ -0,0 +1,207 @@
+"""
+Checks run where the team works, recorded in git (PDR-0013, ADR-0006).
+
+When the forge cannot run a pull request's checks, the team runs them on a workstation: this
+command runs every check the project's CI runs — from one list, bound to the workflows by a
+test — on a clean tree at a commit, and appends the run to that commit's note under
+`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.
+
+Usage :  nstack attest [--root ROOT] [--base BASE] [--body-file FILE] [--labels a,b]
+Output:  0 when every check passed, 1 otherwise — the record is written either way.
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from napkinstack import provenance
+
+NOTES = "nstack/checks"
+RECORD = "attested-checks/v1"
+CONTEXT = "nstack / local checks"
+KEPT = 64 * 1024  # bytes of a step's output kept in the record; the whole is hashed
+
+
+@dataclass(frozen=True)
+class Step:
+    signature: str  # what the job's own `run` holds: the test binding the list to the workflows reads it
+    label: str
+    command: str  # bash, at the root; NSTACK_BASE, NSTACK_BODY, NSTACK_TMP and PR_LABELS are set
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str  # the CI job's name
+    steps: tuple[Step, ...]
+
+
+# The project's CI, job by job, as a workstation runs it (skeleton/.github/workflows/). A job or a
+# step in one place and not the other fails platform/tests/test_attest.py.
+CHECKS: tuple[Check, ...] = (
+    Check("Fitness functions", (
+        Step("nstack fitness", "Manifests, boundaries, skills, plan, hygiene", "nstack fitness --root ."),)),
+    Check("PR scope and review budget", (
+        Step("nstack pr-scope", "One PR = one module", 'nstack pr-scope --root . --base "$NSTACK_BASE"'),)),
+    Check("Hooks and secrets", (
+        Step("pre-commit run --all-files", "Hooks on every file",
+             "SKIP=gitleaks pre-commit run --all-files --show-diff-on-failure"),
+        Step("pre-commit run gitleaks-history", "Secrets in the whole git history",
+             "pre-commit run gitleaks-history --hook-stage manual --all-files"),
+        Step("pre-commit run no-session-link", "No private session link in a message",
+             '{ cat "$NSTACK_BODY"; git log --format=%B "$NSTACK_BASE..HEAD"; } > "$NSTACK_TMP/said.txt" '
+             '&& pre-commit run no-session-link --hook-stage commit-msg --commit-msg-filename "$NSTACK_TMP/said.txt"'),
+    )),
+    Check("Test sheet and cycle", (
+        Step("nstack pr-check", "Test sheet and cycle",
+             'nstack pr-check --root . --base "$NSTACK_BASE" --body-file "$NSTACK_BODY"'),)),
+    Check("Module checks", (
+        Step("bash .nstack/check-modules.sh", "Every changed module",
+             'BASE="$NSTACK_BASE" bash .nstack/check-modules.sh'),)),
+)
+
+
+def _git(root: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True, check=check)
+
+
+def capped(text: str) -> str:
+    """A step's output as the record keeps it: whole up to KEPT bytes, else its head and its tail."""
+    data = text.encode("utf-8", "replace")
+    if len(data) <= KEPT:
+        return text
+    half = KEPT // 2
+    cut = len(data) - KEPT
+    return (data[:half].decode("utf-8", "ignore") + f"\n[… {cut} bytes cut …]\n"
+            + data[-half:].decode("utf-8", "ignore"))
+
+
+def latest(root: Path, commit: str) -> dict | None:
+    """The record of a commit: the latest run its note holds, or None."""
+    shown = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False)
+    if shown.returncode != 0:
+        return None
+    runs = []
+    for line in shown.stdout.splitlines():
+        try:
+            run = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(run, dict) and run.get("record") == RECORD and run.get("commit") == commit:
+            runs.append(run)
+    return max(runs, key=lambda run: str(run.get("at", "")), default=None)
+
+
+def _remote(root: Path) -> str | None:
+    """The branch's remote, else `origin`, else none."""
+    branch = _git(root, "symbolic-ref", "--quiet", "--short", "HEAD", check=False).stdout.strip()
+    if branch:
+        named = _git(root, "config", f"branch.{branch}.remote", check=False).stdout.strip()
+        if named:
+            return named
+    remotes = _git(root, "remote", check=False).stdout.split()
+    return "origin" if "origin" in remotes else None
+
+
+def fetch(root: Path) -> str | None:
+    """Brings the remote's notes in, merged line by line with ours; returns the remote's name."""
+    remote = _remote(root)
+    if remote is None:
+        return None
+    theirs = f"refs/notes/nstack-remote/{NOTES.split('/')[-1]}"
+    got = _git(root, "fetch", "--quiet", remote, f"+refs/notes/{NOTES}:{theirs}", check=False)
+    if got.returncode == 0:
+        _git(root, "notes", f"--ref={NOTES}", "merge", "--quiet", "--strategy=cat_sort_uniq", theirs, check=False)
+    return remote
+
+
+def _session(root: Path, commit: str) -> str | None:
+    trailers = _git(root, "log", "-1", "--format=%(trailers:key=Agent-Session,valueonly)", commit).stdout
+    return trailers.strip().splitlines()[0] if trailers.strip() else None
+
+
+def _show(root: Path, commit: str, passed: int, total: int) -> str:
+    """The forge's display, when there is one and a token: never a judgement, a view of the record."""
+    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+    url = _git(root, "remote", "get-url", _remote(root) or "origin", check=False).stdout.strip()
+    from napkinstack.doctor import ON_GITHUB  # the doctor's reading of a GitHub remote
+
+    found = ON_GITHUB.search(url)
+    if not token or not found:
+        return "not shown on a forge (no GitHub remote, or no token)"
+    api = os.environ.get("GITHUB_API_URL", "https://api.github.com").rstrip("/")
+    body = json.dumps({"state": "success" if passed == total else "failure", "context": CONTEXT,
+                       "description": f"attested: {passed} of {total}"}).encode()
+    request = urllib.request.Request(f"{api}/repos/{found.group(1)}/statuses/{commit}", data=body, method="POST",
+                                     headers={"Accept": "application/vnd.github+json",
+                                              "Authorization": f"Bearer {token}"})
+    try:
+        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})"
+
+
+def run(root: Path, base: str, body_file: Path | None, labels: str) -> int:
+    print(provenance.judged_by(root), flush=True)
+    if _git(root, "status", "--porcelain", "--untracked-files=normal").stdout.strip():
+        print("FAIL [attest] the tree holds changes: a record names one commit, and this tree is none.\n"
+              "      Action: commit or stash them, then run nstack attest again.")
+        return 1
+    commit = _git(root, "rev-parse", "HEAD").stdout.strip()
+    engine, origin = provenance.engine()
+    env = dict(os.environ, PR_LABELS=labels)
+    # The engine that runs this command runs the checks: its folder first on the path.
+    env["PATH"] = os.pathsep.join([str(Path(sys.argv[0]).resolve().parent), env.get("PATH", "")])
+    results = []
+    with tempfile.TemporaryDirectory() as tmp:
+        body = body_file or Path(tmp, "body.md")
+        if body_file is None:
+            body.write_text("", encoding="utf-8")
+        # NSTACK_ATTESTING: pr-check, run as one of the checks, judges the pull request's rules
+        # without asking for the record this run is making (A1, A2) — found rehearsing v0.10.0.
+        env.update(NSTACK_BASE=base, NSTACK_BODY=str(Path(body).resolve()), NSTACK_TMP=tmp,
+                   NSTACK_ATTESTING=commit)
+        for check in CHECKS:
+            steps = []
+            for step in check.steps:
+                done = subprocess.run(["bash", "-c", step.command], cwd=root, env=env,
+                                      stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+                steps.append({"label": step.label, "command": step.command, "exit": done.returncode,
+                              "output": capped(done.stdout),
+                              "sha256": hashlib.sha256(done.stdout.encode("utf-8", "replace")).hexdigest()})
+            passed = all(step["exit"] == 0 for step in steps)
+            results.append({"name": check.name, "passed": passed, "steps": steps})
+            failed = "; ".join(f"{s['label']} exited {s['exit']}" for s in steps if s["exit"])
+            print(f"FAIL [attest] {check.name}: {failed}" if failed else f"ok   [attest] {check.name}", flush=True)
+    # Who ran it, as git would sign a commit made here — its environment and its configuration.
+    ident = _git(root, "var", "GIT_COMMITTER_IDENT", check=False).stdout.strip()
+    who = ident.rsplit(" ", 2)[0] if ident.count(" ") >= 2 else ident
+    record = {"record": RECORD, "commit": commit,
+              "at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="microseconds"),
+              "engine": engine, "published": origin is None, "by": who, "session": _session(root, commit),
+              "base": base, "checks": results}
+    remote = fetch(root)
+    before = _git(root, "notes", f"--ref={NOTES}", "show", commit, check=False)
+    lines = (before.stdout.rstrip("\n") + "\n" if before.returncode == 0 and before.stdout.strip() else "")
+    lines += json.dumps(record, separators=(",", ":"), ensure_ascii=False) + "\n"
+    subprocess.run(["git", "notes", f"--ref={NOTES}", "add", "--force", "--file=-", commit], cwd=root,
+                   input=lines, text=True, capture_output=True, check=True)
+    passed = sum(1 for result in results if result["passed"])
+    where = "local only: no remote"
+    if remote is not None:
+        pushed = _git(root, "push", "--quiet", remote, f"refs/notes/{NOTES}", check=False)
+        where = f"pushed to {remote}" if pushed.returncode == 0 else f"NOT pushed to {remote}: {pushed.stderr.strip()}"
+    print(f"Record of {commit[:12]}: attested: {passed} of {len(results)}; {where}; {_show(root, commit, passed, len(results))}.")
+    return 0 if passed == len(results) else 1

{napkinstack-0.9.6 → napkinstack-0.11.0}/src/napkinstack/cli.py

@@ -8,10 +8,19 @@ import os
 import sys
 from pathlib import Path
 
-from napkinstack import assurance
+from napkinstack import assurance, attest
 from napkinstack import (compat, discovery, doctor, landed, modules, provenance, settings,
                          pull_request, skills)
 from napkinstack.fitness import boundaries, hygiene, manifests, plan, pr_scope
+from napkinstack.project import ANSWERS
+
+
+def _here() -> Path:
+    """The project the current folder belongs to: the nearest folder, this one or above, holding
+    the project's answers — as git and cargo find their root (D130). Outside any project, the
+    current folder, as before."""
+    here = Path.cwd()
+    return next((folder for folder in (here, *here.parents) if (folder / ANSWERS).is_file()), here)
 
 
 def _root(value: str) -> Path:
@@ -39,8 +48,9 @@ def _fitness(root: Path) -> int:
 
 def _add(sub, name: str, help_: str, func) -> argparse.ArgumentParser:
     parser = sub.add_parser(name, help=help_)
-    parser.add_argument("--root", type=_root, default=Path.cwd(),
-                        help="project root (default: current folder)")
+    parser.add_argument("--root", type=_root, default=_here(),
+                        help="project root (default: the nearest folder holding .copier-answers.yml, "
+                             "this one or above; else the current folder)")
     parser.set_defaults(func=func)
     return parser
 
@@ -57,7 +67,7 @@ def _init(args: argparse.Namespace) -> int:
 def _update(args: argparse.Namespace) -> int:
     from napkinstack import project
 
-    return project.update(args.root, args.ref or project.default_ref())
+    return project.update(args.root, args.ref or project.default_ref(), args.session)
 
 
 class _Version(argparse.Action):
@@ -146,6 +156,11 @@ def build_parser() -> argparse.ArgumentParser:
               lambda a: landed.run(a.root, a.span, landed.from_environment(a.root)))
     ld.add_argument("--span", default="HEAD~1..HEAD",
                     help="the commits to read, BEFORE..AFTER (default: the last commit)")
+    at = _add(sub, "attest", "runs the CI's checks here and records the run on the commit, in git",
+              lambda a: attest.run(a.root, a.base, a.body_file, a.labels))
+    at.add_argument("--base", default="origin/main")
+    at.add_argument("--body-file", type=Path, help="the pull request's description, for its checks")
+    at.add_argument("--labels", default="", help="the pull request's labels, comma-separated")
     ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent",
               lambda a: discovery.run(a.root, a.idea))
     ds.add_argument("idea", type=Path, help="the idea, a .md or .txt file")
@@ -161,6 +176,7 @@ def build_parser() -> argparse.ArgumentParser:
     up = _add(sub, "update", "merges a NapkinStack version onto a branch to review",
               _update)
     up.add_argument("--ref", help="target version: a tag vX.Y.Z, or a commit (default: the one of nstack)")
+    up.add_argument("--session", help="the agent's session, written as the commit's Agent-Session trailer")
     return parser
 
 
@@ -176,7 +192,7 @@ def _named_root(argv: list[str]) -> Path:
             return Path(argv[index + 1])
         if word.startswith("--root="):
             return Path(word.removeprefix("--root="))
-    return Path(".")
+    return _here()
 
 
 def _release(a) -> int:
@@ -215,4 +231,9 @@ def main(argv: list[str] | None = None) -> int:
         print(provenance.judged_by(args.root), flush=True)
         if said := plan.stage_line(args.root):
             print(said, flush=True)
-    return args.func(args)
+    code = args.func(args)
+    if code and args.command in JUDGES | {"attest"}:
+        # Where a person reads what the codes and words above mean (D131).
+        print("A rule's code is explained in .nstack/handbook/RULES.md; a word of the framework in "
+              ".nstack/handbook/glossary.md.", flush=True)
+    return code

{napkinstack-0.9.6 → napkinstack-0.11.0}/src/napkinstack/doctor.py

@@ -69,7 +69,11 @@ API_VERSION = "2026-03-10"
 JOBS = ("Fitness functions", "PR scope and review budget", "Hooks and secrets", "Test sheet and cycle",
         "Module checks")
 THIRD_PARTY_ACTIONS = ("astral-sh/setup-uv",)  # non-GitHub actions of the skeleton workflows
-LABELS = ("cross-module", "over-budget", "out-of-cycle")
+# The pull requests' three exceptions, then what the shipped issue templates put on an issue: a
+# label that does not exist is dropped by GitHub without a word (D128).
+EXCEPTIONS = ("cross-module", "over-budget", "out-of-cycle")
+ISSUES = ("request", "bug", "architecture", "debt", "acceptance")
+LABELS = EXCEPTIONS + ISSUES
 PUBLISHED = provenance.PUBLISHED  # a published version is a vX.Y.Z tag (ADR-0002), as CI installs it
 REMOTE = re.compile(r"https://|ssh://|git@[^:/]+:|gh:|gl:")  # as .nstack/install-engine.sh reads them
 ON_GITHUB = re.compile(r"(?:https://github\.com/|ssh://git@github\.com/|git@github\.com:|gh:)([^/]+/[^/]+?)(?:\.git)?/?$")

{napkinstack-0.9.6 → napkinstack-0.11.0}/src/napkinstack/fitness/manifests.py

@@ -128,7 +128,9 @@ def is_description(path: str) -> bool:
     (D24); a module holding nothing else has nothing to check yet (D33)."""
     # A page at any depth describes; it runs nothing. A contract's own page —
     # contracts/<name>/v1/README.md — is the case that asked: the module that holds it must
-    # stay green until the contract gains a schema or a test (PDR-0012).
+    # stay green until the contract gains a schema or a test (PDR-0012). Once a module consumes
+    # the version, or it holds a schema, its page is the contract, and a pull request changing it
+    # changes its module (pull_request.relied_on_pages, D133).
     return (path in DESCRIPTION or path.startswith("docs/")
             or path.rsplit("/", 1)[-1] in {".gitkeep", "README.md"})
 

{napkinstack-0.9.6 → napkinstack-0.11.0}/src/napkinstack/project.py

@@ -140,6 +140,7 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
               f"folder inside it — nstack init {destination}/<project>.")
         return 1
     data = {question: value for question, value in answers.items() if value is not None}
+    data.setdefault("checks", "forge")  # a project starts judged on the forge; the decider may change it
     try:
         copier.run_copy(source, destination, data=data, vcs_ref=ref, quiet=True, unsafe=False)
     except (CopierError, ValueError, OSError) as exc:
@@ -325,7 +326,7 @@ def _readdress(root: Path) -> tuple[list[str], list[str]]:
     return rewritten, left
 
 
-def update(root: Path, ref: str) -> int:
+def update(root: Path, ref: str, session: str | None = None) -> int:
     import copier
     from copier.errors import CopierError
 
@@ -388,7 +389,9 @@ def update(root: Path, ref: str) -> int:
               "then git add --all && git commit.\n      The check-merge-conflict hook and CI "
               "reject any remaining marker.")
         return 1
-    for args in (("add", "--all"), ("commit", "--quiet", "--message", f"NapkinStack {previous} -> {current}")):
+    # An agent's update carries the kernel's trailer, as every commit it makes (D135).
+    message = f"NapkinStack {previous} -> {current}" + (f"\n\nAgent-Session: {session}" if session else "")
+    for args in (("add", "--all"), ("commit", "--quiet", "--message", message)):
         result = _git(root, *args)
         if result.returncode:
             print(f"FAIL [update] Update laid on {branch}, but `git {args[0]}` failed:\n"

{napkinstack-0.9.6 → napkinstack-0.11.0}/src/napkinstack/pull_request.py

@@ -51,6 +51,7 @@ from napkinstack.fitness import plan
 from napkinstack import assurance
 from napkinstack.fitness.manifests import MODULE_DIRS, changed_files, find_manifests, is_description
 from napkinstack.modules import LOGIN
+from napkinstack.project import ANSWERS
 
 CHARTER = plan.CHARTER.as_posix()  # docs/project/charter.md, as the diff names it
 
@@ -103,14 +104,40 @@ def touched_modules(root: Path, base: str, files: list[str]) -> dict[str, list[d
         parts = path.split("/")
         if parts[-1] == "MANIFEST.yaml" and parts[0] in MODULE_DIRS and len(parts) in (2, 3):
             manifests.setdefault(path, []).append(_manifest(_git(root, "show", f"{base}:{path}").stdout))
+    relied = relied_on_pages(root, manifests)
     touched = {}
     for path, found in sorted(manifests.items()):
         folder = path.removesuffix("/MANIFEST.yaml")
-        if any(file.startswith(f"{folder}/") and not is_description(file[len(folder) + 1:]) for file in files):
+        if any(file.startswith(f"{folder}/") and (not is_description(file[len(folder) + 1:]) or file in relied)
+               for file in files):
             touched[folder] = found
     return touched
 
 
+CONTRACT_PAGE = re.compile(r"(?P<path>.+/(?P<contract>[^/]+)/(?P<version>v\d+))/README\.md")
+
+
+def relied_on_pages(root: Path, manifests: dict[str, list[dict]]) -> set[str]:
+    """The pages of the contract versions someone relies on — a module consumes the version, or
+    it holds a schema — relative to the root (D133). Such a page is the contract: its prose is
+    held by review and by nothing else (03-contracts.md), so changing it changes its module. A
+    version nobody relies on yet keeps PDR-0012's relief: its page is a description."""
+    consumed = {(str(entry.get("contract")), str(entry.get("version")))
+                for found in manifests.values() for data in found[:1]
+                for entry in (data.get("consumes") or []) if isinstance(entry, dict)}
+    pages = set()
+    for data in (found[0] for found in manifests.values() if found):
+        for entry in data.get("provides") or []:
+            if not isinstance(entry, dict) or not entry.get("path"):
+                continue
+            page = f"{str(entry['path']).rstrip('/')}/README.md"
+            match = CONTRACT_PAGE.fullmatch(page)
+            if match and ((match["contract"], match["version"]) in consumed
+                          or any((root / match["path"]).glob("*.schema.json"))):
+                pages.add(page)
+    return pages
+
+
 def sheet_reason(folder: str, manifests: list[dict]) -> str | None:
     """Why a module requires a test sheet (T1), or None: the stricter of its manifests, so
     that a pull request cannot lower its own requirement. What each criticality requires is read
@@ -388,6 +415,46 @@ def charter_without_pdr(root: Path, base: str, files: list[str]) -> list[str]:
             "correction that decides nothing needs none (.nstack/playbooks/framing.md, Decisions)."]
 
 
+def check_attested(root: Path, head: str, fail) -> 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
+    head is required. Returns the line the summary prints."""
+    from napkinstack import attest  # the record's reader, and the one list of checks
+
+    try:
+        answers = yaml.safe_load((root / ANSWERS).read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError):
+        answers = {}
+    attest.fetch(root)
+    record = attest.latest(root, head)
+    if answers.get("checks", "forge") != "attested":
+        shown = ""
+        if record:
+            passed = sum(1 for check in record["checks"] if check["passed"])
+            shown = f"; a record of the head: attested {passed} of {len(record['checks'])} (information)"
+        return "the forge's CI" + shown
+    if os.environ.get("NSTACK_ATTESTING") == head:
+        return "attested — this run is the record being made"
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        # CI's checkout keeps no credential to fetch the notes: where the checks are attested, the
+        # record is read where the merge is decided, never failed here for want of a fetch.
+        return "attested — judged where nstack attest runs, not in CI"
+    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.")
+        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]
+    failed = [check["name"] for check in record["checks"] if not check["passed"]]
+    if missing or failed:
+        said = "; ".join(part for part in (f"missing: {', '.join(missing)}" if missing else "",
+                                           f"failed: {', '.join(failed)}" if failed else "") if part)
+        fail("A2", f"the record of the head {head[:7]} is not complete and passed ({said}).\n"
+                   "      Action: fix what failed, commit, and run nstack attest again.")
+        return "attested — the record of the head does not pass"
+    return f"attested on a workstation, by {record['by']}, at {record['at']}"
+
+
 def run(root: Path, base: str, body_file: Path | None = None) -> int:
     if body_file is not None:
         body = body_file.read_text(encoding="utf-8")
@@ -423,9 +490,11 @@ def run(root: Path, base: str, body_file: Path | None = None) -> int:
                              lambda commit: bool(tree_of(commit)) and tree_of(commit) == tree_of(head))
     if modules:
         check_cycle(root, body, labels, datetime.date.today(), fail, warnings.append)
+    checks = check_attested(root, head, fail)
 
     print(f"Modules touched : {len(modules)}" + "".join(f"\n  - {folder}" for folder in modules))
     print(f"Test sheet      : {'required' if reasons else 'not required'}")
+    print(f"Checks          : {checks}")
     for line in summary(body, authorship) if reasons else []:
         print(line)
     for scenario in human_only:

{napkinstack-0.9.6 → napkinstack-0.11.0}/src/napkinstack/settings.py

@@ -39,10 +39,18 @@ from napkinstack.project import ANSWERS
 RULESET_NAME = "nstack-checklist"
 IN_RULESET = ("G1", "G2", "G3", "G4", "G13", "G17", "G18")
 PULL_REQUEST = ("G1", "G2", "G3", "G13")
-LABEL_COLOURS = {"cross-module": "d93f0b", "over-budget": "fbca04", "out-of-cycle": "5319e7"}
+LABEL_COLOURS = {"cross-module": "d93f0b", "over-budget": "fbca04", "out-of-cycle": "5319e7",
+                 "request": "0e8a16", "bug": "d73a4a", "architecture": "1d76db", "debt": "c5def5",
+                 "acceptance": "bfdadc"}
+# An issue label means what its template says: the same words, the template being the source.
 LABEL_MEANING = {"cross-module": "A pull request touching several modules, with its justification",
                  "over-budget": "A pull request beyond the review budget, with its justification",
-                 "out-of-cycle": "Work outside the current cycle, with its justification"}
+                 "out-of-cycle": "Work outside the current cycle, with its justification",
+                 "request": "Something asked for that no cycle plans yet",
+                 "bug": "Incorrect behaviour in production or in test",
+                 "architecture": "Boundary, contract, coupling, structuring decision",
+                 "debt": "Identified debt, with its cost and its trigger",
+                 "acceptance": "A deliverable tried by a person — what to run, what was seen"}
 Call = tuple[str, str, str, dict | None]  # (rules closed, method, path under the repository, body)
 
 

{napkinstack-0.9.6 → napkinstack-0.11.0}/src/napkinstack/templates/contracts/AGENTS.md

@@ -13,6 +13,9 @@ Defines and versions the interface contracts between modules.
 - A version a module consumes, or marked stable, changes only with the merged `compat`
   command's approval (V1).
 - Contract tests run on **both sides**: producer and consumer.
+- A version's page (`<name>/v<n>/README.md`) is the contract once a module consumes the
+  version or it holds a schema: a pull request changing it changes this module, and this
+  module's test sheet is due — its prose is held by review and by nothing else.
 
 ## The main trap