napkinstack 0.4.0__tar.gz → 0.6.0__tar.gz

{napkinstack-0.4.0 → napkinstack-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.4.0
+Version: 0.6.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,14 +20,21 @@ 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.4.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): every barrier
+> **Status: v0.5.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): every barrier
 > the framework announces refuses what it claims to — the boundaries read the contracts a
 > module uses, a contract version someone relies on changes only with a proof, the module
 > checks and stale approvals are enforced, a verifier is not an author, and every verdict names
-> the framework that gave it. A first pilot project, private, starts from it. Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
+> the framework that gave it. Proved on the project that exposed the defects: eight probes
+> replayed, each refused or accepted as announced. The contract proof now runs in the base's
+> tree, so a change cannot rewrite what judges it; the diagnosis says whether anything refuses
+> at all; and a record names what reached the default branch outside a pull request — it
+> records, it never refuses. A first pilot project, private, starts from here.
+> Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
 > [move to English](docs/governance/plans/2026-09-16-english-migration.md),
 > [frame, verify, approve](docs/governance/plans/2026-09-16-v0.3.0-frame-verify-approve.md),
 > [every barrier refuses](docs/governance/plans/2026-09-19-v0.4.0-every-barrier-refuses.md),
+> [a proof that cannot be rewritten](docs/governance/plans/2026-09-20-v0.5.0-a-proof-that-cannot-be-rewritten.md),
+> [the conformance suite](docs/governance/plans/2026-09-20-m12-conformance-suite.md),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -78,10 +85,25 @@ uv tool install napkinstack --with-executables-from pre-commit   # prerequisites
 nstack init my-project
 ```
 
-Each project then pins its version and changes it through `nstack update`. Every published
-version carries a provenance attestation, visible on PyPI, tying it to the workflow and
-the commit of this repository
-([ADR-0002](docs/adr/0002-distribute-napkinstack-on-pypi.md)).
+To try it without installing anything, or to install it from this repository instead of the
+registry — always pinned to a release tag:
+
+```bash
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.5.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.5.0"
+```
+
+**Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
+`vX.Y.Z` tag carries a provenance attestation tying it to the workflow and the commit of this
+repository. The forge distributes that same tag's source, which is a supported way in and
+never a published one — a tag can be moved, and carries no attestation — so a run installed
+that way says where its rules came from, on every line that judges
+([ADR-0002](docs/adr/0002-distribute-napkinstack-on-pypi.md),
+[PDR-0005](docs/pdr/0005-work-on-the-framework-while-using-it.md)). The project itself is
+unaffected: created from either channel at the same tag, it records the same version and its
+CI installs from the registry.
+
+Each project then pins its version and changes it through `nstack update`.
 
 ## The commands
 
@@ -99,6 +121,7 @@ the commit of this repository
 | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
 | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared |
 | `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 skills` | Exposes the playbooks as skills for the agent |
 | `nstack update` | Lays the new version on a branch to review |
 

{napkinstack-0.4.0 → napkinstack-0.6.0}/README.md

@@ -5,14 +5,21 @@ 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.4.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): every barrier
+> **Status: v0.5.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): every barrier
 > the framework announces refuses what it claims to — the boundaries read the contracts a
 > module uses, a contract version someone relies on changes only with a proof, the module
 > checks and stale approvals are enforced, a verifier is not an author, and every verdict names
-> the framework that gave it. A first pilot project, private, starts from it. Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
+> the framework that gave it. Proved on the project that exposed the defects: eight probes
+> replayed, each refused or accepted as announced. The contract proof now runs in the base's
+> tree, so a change cannot rewrite what judges it; the diagnosis says whether anything refuses
+> at all; and a record names what reached the default branch outside a pull request — it
+> records, it never refuses. A first pilot project, private, starts from here.
+> Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
 > [move to English](docs/governance/plans/2026-09-16-english-migration.md),
 > [frame, verify, approve](docs/governance/plans/2026-09-16-v0.3.0-frame-verify-approve.md),
 > [every barrier refuses](docs/governance/plans/2026-09-19-v0.4.0-every-barrier-refuses.md),
+> [a proof that cannot be rewritten](docs/governance/plans/2026-09-20-v0.5.0-a-proof-that-cannot-be-rewritten.md),
+> [the conformance suite](docs/governance/plans/2026-09-20-m12-conformance-suite.md),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -63,10 +70,25 @@ uv tool install napkinstack --with-executables-from pre-commit   # prerequisites
 nstack init my-project
 ```
 
-Each project then pins its version and changes it through `nstack update`. Every published
-version carries a provenance attestation, visible on PyPI, tying it to the workflow and
-the commit of this repository
-([ADR-0002](docs/adr/0002-distribute-napkinstack-on-pypi.md)).
+To try it without installing anything, or to install it from this repository instead of the
+registry — always pinned to a release tag:
+
+```bash
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.5.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.5.0"
+```
+
+**Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
+`vX.Y.Z` tag carries a provenance attestation tying it to the workflow and the commit of this
+repository. The forge distributes that same tag's source, which is a supported way in and
+never a published one — a tag can be moved, and carries no attestation — so a run installed
+that way says where its rules came from, on every line that judges
+([ADR-0002](docs/adr/0002-distribute-napkinstack-on-pypi.md),
+[PDR-0005](docs/pdr/0005-work-on-the-framework-while-using-it.md)). The project itself is
+unaffected: created from either channel at the same tag, it records the same version and its
+CI installs from the registry.
+
+Each project then pins its version and changes it through `nstack update`.
 
 ## The commands
 
@@ -84,6 +106,7 @@ the commit of this repository
 | `nstack compat [module] --base <base>` | A contract version consumed or stable changes only with the project's merged comparator |
 | `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared |
 | `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 skills` | Exposes the playbooks as skills for the agent |
 | `nstack update` | Lays the new version on a branch to review |
 

{napkinstack-0.4.0 → napkinstack-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.4.0"
+version = "0.6.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.4.0 → napkinstack-0.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.4.0"
+version = "0.6.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.4.0 → napkinstack-0.6.0}/src/napkinstack/cli.py

@@ -6,7 +6,8 @@ import argparse
 import json
 from pathlib import Path
 
-from napkinstack import __version__, compat, discovery, doctor, modules, provenance, pull_request, skills
+from napkinstack import (__version__, compat, discovery, doctor, landed, modules, provenance,
+                         pull_request, skills)
 from napkinstack.fitness import boundaries, hygiene, manifests, plan, pr_scope
 
 
@@ -18,7 +19,7 @@ def _root(value: str) -> Path:
 
 
 def _modules(args: argparse.Namespace) -> int:
-    found = modules.listing(args.root, args.changed_since)
+    found = modules.listing(args.root, args.changed_since, args.with_contract_sides)
     if found is None:
         print(f"FAIL [modules] base '{args.changed_since}' not found in {args.root}.\n"
               "      Action: fetch the history (fetch-depth: 0), or pass an existing commit.")
@@ -62,7 +63,7 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", required=True, metavar="command")
     _add(sub, "manifests", "manifests, lifecycles, deprecations (M1-M10)",
          lambda a: manifests.run(a.root))
-    _add(sub, "boundaries", "declared graph against real graph (B1-B7)",
+    _add(sub, "boundaries", "declared graph against real graph (B1-B8)",
          lambda a: boundaries.run(a.root))
     _add(sub, "plan", "the discovery, the charter and the cycles (C1-C7)", lambda a: plan.run(a.root))
     sk = _add(sub, "skills", "generates or checks the skills (S1-S4)",
@@ -97,6 +98,9 @@ def build_parser() -> argparse.ArgumentParser:
     rn.add_argument("module")
     md = _add(sub, "modules", "the project's modules, or those with a file changed since a base", _modules)
     md.add_argument("--changed-since", metavar="BASE", help="only the modules with a file changed since BASE")
+    md.add_argument("--with-contract-sides", action="store_true",
+                    help="also the producer and the declared consumers of a contract version "
+                         "this change touches (with --changed-since)")
     md.add_argument("--json", action="store_true", help="a JSON list, for CI")
     ps = _add(sub, "pr-scope", "one PR = one module, review budget (P1-P2)",
               lambda a: pr_scope.run(a.root, a.base))
@@ -105,6 +109,10 @@ def build_parser() -> argparse.ArgumentParser:
               lambda a: pull_request.run(a.root, a.base, a.body_file))
     pc.add_argument("--base", default="origin/main")
     pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
+    ld = _add(sub, "landed", "what reached this branch outside a pull request, recorded (W1)",
+              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)")
     ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent (PDR-0002)",
               lambda a: discovery.run(a.root, a.idea))
     ds.add_argument("idea", type=Path, help="the idea, a .md or .txt file")
@@ -124,7 +132,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 JUDGES = {"manifests", "boundaries", "plan", "skills", "hygiene", "fitness", "doctor", "pr-scope",
-          "pr-check", "compat"}  # the commands whose verdict depends on the framework's rules
+          "pr-check", "compat", "landed"}  # the commands whose verdict depends on the framework's rules
 
 
 def main(argv: list[str] | None = None) -> int:

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/compat.py

@@ -98,12 +98,15 @@ def _holder(root: Path, path: str) -> tuple[str, Path] | None:
     return None
 
 
-def _extract(root: Path, base: str, path: str, into: Path) -> Path:
-    archive = subprocess.run(["git", "archive", "--format=tar", base, "--", path], cwd=root,
+def _base_tree(root: Path, base: str, into: Path) -> Path:
+    """The whole repository as it is at the base. The proof runs here, so the change it judges
+    cannot rewrite what judges it — a script, a fixture, anything it reads (D44). Measured on
+    2026-09-20: 7 ms for 1.6 MB."""
+    archive = subprocess.run(["git", "archive", "--format=tar", base], cwd=root,
                              capture_output=True, check=True).stdout
     with tarfile.open(fileobj=io.BytesIO(archive)) as tar:
         tar.extractall(into, filter="data")
-    return into / path
+    return into
 
 
 def run(root: Path, module: str | None, base: str) -> int:
@@ -152,15 +155,26 @@ def run(root: Path, module: str | None, base: str) -> int:
                             "a new version beside it (docs/os/03-contracts.md §4).")
             continue
         with tempfile.TemporaryDirectory() as temporary:
+            tree = _base_tree(root, fork, Path(temporary))
+            where_it_runs = tree / folder.relative_to(root)
+            if not where_it_runs.is_dir():
+                failures.append(f"[V1] {label}: module '{name}' has no folder at the base, so its "
+                                f"compatibility command cannot be run as merged.\n      Action: "
+                                "declare the command where the module now lives, in a pull request "
+                                "of its own (docs/os/03-contracts.md §4).")
+                continue
             env = {**os.environ, "NSTACK_CONTRACT": contract, "NSTACK_VERSION": version,
-                   "NSTACK_BASE_PATH": str(_extract(root, fork, path, Path(temporary))),
-                   "NSTACK_HEAD_PATH": str(root / target)}
+                   "NSTACK_BASE_PATH": str(tree / path), "NSTACK_HEAD_PATH": str(root / target)}
             print(f"-> {name}: {command}", flush=True)
-            code = subprocess.run(command, shell=True, cwd=folder, env=env).returncode
+            code = subprocess.run(command, shell=True, cwd=where_it_runs, env=env).returncode
         if code:
-            failures.append(f"[V1] {label}: `{command}` exited with {code}, a breaking change.\n"
-                            "      Action: publish it as a new version beside it, then migrate its "
-                            "consumers (expand/contract, docs/os/03-contracts.md §4).")
+            failures.append(f"[V1] {label}: the compatibility command of module '{name}' ({where}) "
+                            f"did not prove the change compatible (exit {code}).\n"
+                            "      Action: read the comparator's output above. If the change is "
+                            "breaking, publish it as a new version beside this one and migrate its "
+                            "consumers (expand/contract, docs/os/03-contracts.md §4). If the command "
+                            "could not run — a missing tool, no network — fix the command: V1 cannot "
+                            "pass without a proof.")
         else:
             checked.append(f"{label}: proven compatible")
     for line in checked:

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/doctor.py

@@ -44,6 +44,10 @@ from napkinstack import __version__, provenance
 from napkinstack.project import ANSWERS
 
 OK, GAP, UNKNOWN, NOT_APPLICABLE = "OK", "FAIL", "NOT VERIFIED", "NOT APPLICABLE"
+OUT_OF_REACH = "OUT OF REACH"      # the plan forbids it: a state, not a fault (PDR-0006)
+# The settings that make the forge refuse a merge. A repository is guarded when they are
+# all in force; the others matter and none of them stops a merge.
+BLOCKING = ("G1", "G2", "G3", "G4", "G12", "G13")
 API_VERSION = "2026-03-10"
 PLACEHOLDER = "<One sentence: what this project does.>"
 JOBS = ("Fitness functions", "PR scope and review budget", "Hooks and secrets", "Test sheet and cycle",
@@ -287,6 +291,35 @@ def _display(rule: str, setting: str, status: str, detail: str) -> None:
         print(f"                 {line}")
 
 
+def _state(results: list[tuple[str, str, str, str]]) -> None:
+    """Guarded when every setting that refuses a merge is in force; unguarded otherwise, with
+    what a plan forbids kept apart from what is not yet done; never guarded on what could not
+    be read (PDR-0006)."""
+    status_of = {rule: status for rule, _, status, _ in results}
+    blocking = [status_of.get(rule, UNKNOWN) for rule in BLOCKING]
+    if any(status == UNKNOWN for status in blocking):
+        print("\nThis repository: not verified — what cannot be read is never reported as guarded.")
+        return
+    if all(status == OK for status in blocking):
+        print("\nThis repository: guarded — the forge refuses what the checklist asks it to refuse.")
+        return
+    groups = {name: [rule for rule, _, status, _ in results
+                     if status == name and rule.startswith("G")]
+              for name in (OK, GAP, OUT_OF_REACH)}
+    print("\nThis repository: unguarded — nothing here refuses a merge.")
+    for label, name in (("In force", OK), ("Not yet in place", GAP),
+                        ("Out of reach on this plan", OUT_OF_REACH)):
+        if groups[name]:
+            print(f"  {label:<26}: {', '.join(groups[name])}")
+    if groups[OUT_OF_REACH]:
+        print("  What it would take        : make the repository public, where these work at no "
+              "cost on any plan;\n                              or move the private repository to a "
+              "plan that enforces rules;\n                              or keep working here, "
+              "knowing that nothing refuses.")
+    if groups[GAP]:
+        print("  Each setting not yet in place carries its action above.")
+
+
 def run(root: Path) -> int:
     if not (root / ANSWERS).is_file():
         print(f"FAIL [doctor] {ANSWERS} not found in {root}: this folder is not a project "
@@ -324,16 +357,19 @@ def run(root: Path) -> int:
             except Gap as action:
                 status, detail = GAP, f"Action: {action}"
             if private and status != OK and rule in PRIVATE_PLAN:
-                detail += f"\n{PRIVATE_PLAN[rule]}"
+                status, detail = OUT_OF_REACH, f"Reason: {PRIVATE_PLAN[rule]}"
         results.append((rule, setting, status, detail))
         _display(rule, setting, status, detail)
 
     gaps = sum(status == GAP for _, _, status, _ in results)
     unknown = sum(status == UNKNOWN for _, _, status, _ in results)
     skipped = sum(status == NOT_APPLICABLE for _, _, status, _ in results)
+    out_of_reach = sum(status == OUT_OF_REACH for _, _, status, _ in results)
+    _state(results)
     suffix = f", {skipped} not applicable" if skipped else ""
     if not gaps and not unknown:
-        print(f"\nnstack doctor: compliant{suffix}.")
+        reach = f"; {out_of_reach} setting(s) out of reach on this plan" if out_of_reach else ""
+        print(f"\nnstack doctor: compliant{suffix}{reach}.")
         return 0
     print(f"\nnstack doctor: {gaps} gap(s), {unknown} not verified{suffix}.\nWorkflows inform; "
           "it is the GitHub settings that block, and they are not copied with the project.")

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/fitness/boundaries.py

@@ -16,6 +16,8 @@ Rules:
   B5  no direct access to another module's data (tables declared elsewhere)
   B6  a consumed contract is provided: its contract, version and module match a provides entry
   B7  a provided contract exists: its path holds its document, inside a module's folder
+  B8  a contract consumed from a deprecated module (warning): a deprecated module takes no
+      new consumer, and the existing ones migrate before its removal date
 
 DETECTION — textual and deliberately simple, with no stack assumed.
   - A contract is read where a module's file names its path (contracts/billing-api/v1),
@@ -87,10 +89,13 @@ def load_modules(root: Path) -> dict[str, dict]:
             owns = section.get("owns") if isinstance(section.get("owns"), list) else []
             name = mod.get("name") if isinstance(mod.get("name"), str) and mod["name"] else manifest.parent.name
             code_name = mod.get("code_name")
+            deprecation = mod.get("deprecation") if isinstance(mod.get("deprecation"), dict) else {}
             modules[name] = {
                 "path": manifest.parent,
                 "dirname": manifest.parent.name,
                 "code_name": code_name if isinstance(code_name, str) and code_name else name,
+                "lifecycle": mod.get("lifecycle") if isinstance(mod.get("lifecycle"), str) else None,
+                "removal": deprecation.get("removal_date"),
                 "provides": contract_entries(data, "provides"),
                 "consumes": contract_entries(data, "consumes"),
                 "owns_data": {table for table in owns if isinstance(table, str)},
@@ -204,6 +209,15 @@ def check_contracts(root: Path, modules: dict[str, dict]) -> dict[str, dict[str,
             elif c.get("module") not in (None, producer):
                 fail("B6", name, f"consumes {key[0]} {key[1]} from '{c.get('module')}', which is "
                                  f"provided by '{producer}'.\n      Action: name the producer.")
+            # B8 - a deprecated producer. Reported, not refused: what is already declared is
+            # bounded by the removal date, which M5 turns red once it has passed.
+            elif modules[producer]["lifecycle"] == "deprecated":
+                when = modules[producer]["removal"]
+                warn("B8", name, f"consumes {key[0]} {key[1]} from '{producer}', which is deprecated"
+                                 + (f" (removal {when})" if when else "")
+                                 + ": a deprecated module takes no new consumer.\n      Action: "
+                                 "migrate to the module that replaces it before that date "
+                                 "(docs/os/02-modules.md §6); M5 turns red once it has passed.")
 
     patterns = contract_patterns(modules)
     reads: dict[str, dict[str, set[str]]] = {name: {} for name in modules}

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/fitness/manifests.py

@@ -25,6 +25,7 @@ Output:  0 if everything passes, 1 otherwise. Every failure explains the rule br
 from __future__ import annotations
 import sys
 import datetime
+import re
 import subprocess
 from pathlib import Path
 
@@ -86,6 +87,24 @@ def contract_entries(data: dict, section: str) -> list[dict]:
             and all(isinstance(entry.get(field), (str, type(None))) for field in CONTRACT_FIELDS[section])]
 
 
+UNFILLED = re.compile(r"<[^<>\s][^<>]*>")  # the angle-bracket placeholder of a template
+TODO = re.compile(r"^TODO\b", re.I)
+
+
+def unfilled(value) -> bool:
+    """Whether a declaration still holds the template's words: empty, carrying a placeholder
+    such as <github-handle>, or opening with TODO (D51).
+
+    A *declaration* is unfilled as soon as it carries a placeholder — nobody writes a success
+    criterion around one. A *cell* of a test sheet is unfilled only when it is nothing but a
+    placeholder, which is the template's example row: that one is `pull_request.PLACEHOLDER`,
+    and the two meanings are deliberately different. A placeholder opens on a non-space, so
+    "stays < 200 ms" is a comparison, not a placeholder.
+    """
+    text = str(value or "").strip()
+    return not text or bool(UNFILLED.search(text)) or bool(TODO.match(text))
+
+
 def is_description(path: str) -> bool:
     """A module's description — its manifest, AGENTS.md, README.md, docs/ — or an empty
     placeholder, `path` relative to the module's folder. Changing it changes no behaviour
@@ -208,9 +227,18 @@ def check_manifest(path: Path, today: datetime.date) -> None:
                 fail(rel, "M6", f"contract {name}: removal date passed ({removal}). "
                                 "Finish the contraction (docs/os/03-contracts.md §4).")
 
-    # M7 - standard verbs, once there is something to check (D33)
     commands = data.get("commands") or {}
     content = module_content(path.parent)
+
+    # M2 - the responsibility still the template's, once the module holds more than its
+    # description: a module is green as created (D33) and says what it does from its first
+    # file of code.
+    if content and unfilled(resp):
+        fail(rel, "M2", f'module.responsibility is still the template\'s: "{resp}"\n'
+                        "      Action: one sentence naming the capability this module covers, "
+                        "in MANIFEST.yaml (docs/os/02-modules.md §5).")
+
+    # M7 - standard verbs, once there is something to check (D33)
     for verb in REQUIRED_COMMANDS:
         if content and not commands.get(verb):
             fail(rel, "M7", f"standard verb missing: commands.{verb}, and the module holds more "

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/fitness/plan.py

@@ -31,6 +31,7 @@ from pathlib import Path
 
 import yaml
 
+from napkinstack.fitness.manifests import unfilled
 from napkinstack.modules import HANDLE
 
 PROJECT = Path("docs") / "project"
@@ -114,8 +115,9 @@ def _check_charter(path: Path, fail) -> bool:
         fail("C2", path, f"status '{data.get('status')}': expected one of {sorted(CHARTER_STATUSES)}")
     check_decider("C2", path, data.get("decider"), fail)
     criteria = data.get("success_criteria")
-    if not isinstance(criteria, list) or not [c for c in criteria if str(c or "").strip()]:
-        fail("C2", path, "success_criteria: at least one, they say when the project itself ends")
+    if not isinstance(criteria, list) or not [c for c in criteria if not unfilled(c)]:
+        fail("C2", path, "success_criteria: at least one, filled in — they say when the project "
+                         "itself ends. The template's example is not one")
     return data.get("status") == "accepted"
 
 
@@ -135,16 +137,17 @@ def _check_deliverables(path: Path, deliverables, fail) -> None:
         elif ident in seen:
             fail("C4", path, f"deliverable {ident}: id used twice")
         seen.add(ident)
-        if not str(item.get("title") or "").strip():
-            fail("C4", path, f"deliverable {where}: title missing")
+        if unfilled(item.get("title")):
+            fail("C4", path, f"deliverable {where}: title missing, or still the template's")
         state = item.get("state")
         if state not in DELIVERABLE_STATES:
             fail("C4", path, f"deliverable {where}: state '{state}', expected one of {sorted(DELIVERABLE_STATES)}")
         criteria = item.get("acceptance")
-        filled = isinstance(criteria, list) and [c for c in criteria if str(c or "").strip()]
+        filled = isinstance(criteria, list) and [c for c in criteria if not unfilled(c)]
         if state in DELIVERABLE_STATES - WITHOUT_CRITERIA and not filled:
-            fail("C4", path, f"deliverable {where}: state '{state}' requires acceptance criteria — "
-                             "the definition of ready, and the source of its test sheet (PDR-0003)")
+            fail("C4", path, f"deliverable {where}: state '{state}' requires acceptance criteria "
+                             "filled in — the definition of ready, and the source of its test "
+                             "sheet (PDR-0003)")
 
 
 def _check_cycle(path: Path, fail) -> str | None:
@@ -188,7 +191,7 @@ def _check_discovery(path: Path, fail) -> str | None:
         check_decider("C7", path, data.get("decider"), fail)
         if as_date(data.get("decided_on")) is None:
             fail("C7", path, f"a decision ({decision}) records decided_on, YYYY-MM-DD")
-        if decision == "go" and not str(data.get("challenger") or "").strip():
+        if decision == "go" and unfilled(data.get("challenger")):
             fail("C7", path, "a go names its challenger: another session, or a human, challenged the "
                              "document first (playbooks/discovery.md, stage 5)")
     return decision if isinstance(decision, str) else None

napkinstack-0.6.0/src/napkinstack/landed.py

@@ -0,0 +1,122 @@
+"""
+What reached the default branch (PDR-0006).
+
+Rule:
+  W1  a commit on the default branch arrived through a pull request
+
+This is a record, not a barrier. Where the forge can refuse — a ruleset requiring a pull
+request — nothing reaches the default branch any other way, and this says so. Where it
+cannot, because the repository's plan does not allow it, a commit pushed straight to the
+branch is the one thing nobody would otherwise be told about. A record that fires late is
+worth more than a silence.
+
+It says nothing about what predates it: the commit that created the repository, and
+everything the repository already held when the record arrived, are not reported. A record
+that greets a project by failing on its own arrival teaches people to ignore it.
+
+The forge is read with a token supplied by the run (GH_TOKEN, otherwise GITHUB_TOKEN), which
+needs no write access of any kind: the project's automation token stays read-only (G10).
+Without a token, or when the span cannot be read, nothing is claimed.
+
+Usage :  nstack landed [--root ROOT] [--span BEFORE..AFTER]
+Output:  0 when every commit of the span arrived through a pull request, or when nothing
+         could be verified; 1 when one did not.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+import yaml
+
+from napkinstack.doctor import GitHub, NotVerified
+from napkinstack.project import ANSWERS
+
+# The workflow that runs this record in a generated project. Its own arrival is what the
+# record treats as its beginning; platform/tests/run.sh checks the two names match.
+RECORD = ".github/workflows/commits-on-main.yml"
+EMPTY = "0" * 40
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+
+
+def _commits(root: Path, span: str) -> list[str] | None:
+    """The commits of the span, newest first; None when the span cannot be read."""
+    before, _, after = span.partition("..")
+    if not after or before in ("", EMPTY):
+        after, before = (after or before), ""          # a branch's first push has no before
+    read = (_git(root, "rev-list", f"{before}..{after}") if before
+            else _git(root, "rev-list", "-1", after))
+    return None if read.returncode else read.stdout.split()
+
+
+def _beginning(root: Path) -> str | None:
+    """The commit that brought the record into the repository, if it is there."""
+    read = _git(root, "log", "--diff-filter=A", "--format=%H", "--", RECORD)
+    return read.stdout.split()[-1] if read.returncode == 0 and read.stdout.split() else None
+
+
+def _exempt(root: Path, commit: str, beginning: str | None) -> str | None:
+    """Why this commit is not recorded, or None when it is to be checked."""
+    if _git(root, "rev-parse", "--verify", "--quiet", f"{commit}^").returncode:
+        return "the first commit of the repository"
+    if beginning and _git(root, "merge-base", "--is-ancestor", commit, beginning).returncode == 0:
+        return "older than the record itself"
+    return None
+
+
+def _described(root: Path, commit: str) -> str:
+    return _git(root, "show", "-s", "--format=%h (%an, %ad)", "--date=short", commit).stdout.strip()
+
+
+def run(root: Path, span: str, forge: GitHub | None) -> int:
+    commits = _commits(root, span)
+    if commits is None:
+        print(f"[W1] the commits of '{span}' cannot be read: not verified.\n"
+              "      Action: fetch the history (fetch-depth: 0), or pass an existing range.")
+        return 0
+    if forge is None:
+        print("[W1] no token (GH_TOKEN or GITHUB_TOKEN): how each commit arrived is not verified.\n"
+              "      Action: supply a token with read access to the repository's pull requests.")
+        return 0
+    beginning = _beginning(root)
+    outside, checked = [], 0
+    for commit in commits:
+        why = _exempt(root, commit, beginning)
+        if why:
+            print(f"Commit {_described(root, commit)}: not recorded, {why}.")
+            continue
+        try:
+            pulls = forge.get(f"/commits/{commit}/pulls")
+        except NotVerified as reason:
+            print(f"[W1] commit {commit[:12]}: not verified. Reason: {reason}")
+            continue
+        checked += 1
+        if pulls:
+            print(f"Commit {_described(root, commit)}: arrived through a pull request.")
+        else:
+            outside.append(commit)
+    for commit in outside:
+        print(f"FAIL [W1] commit {_described(root, commit)} reached this branch outside a pull "
+              "request.\n      This run records it; it does not refuse it — on this repository "
+              "nothing could.\n      Action: read the commit. If it was not meant to land this "
+              "way, revert it through a pull request.")
+    if outside:
+        return 1
+    if checked:
+        print(f"Every commit of this push arrived through a pull request ({checked} checked).")
+    return 0
+
+
+def from_environment(root: Path) -> GitHub | None:
+    """The forge, read-only, from the project's own answers and the run's token."""
+    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+    if not token:
+        return None
+    answers = yaml.safe_load((root / ANSWERS).read_text(encoding="utf-8")) or {}
+    return GitHub(str(answers.get("github_repo")), token,
+                  os.environ.get("GITHUB_API_URL") or "https://api.github.com")

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/modules.py

@@ -17,7 +17,8 @@ from pathlib import Path
 
 import yaml
 
-from napkinstack.fitness.manifests import changed_files, find_manifests, module_content
+from napkinstack.fitness.manifests import (changed_files, contract_entries, find_manifests,
+                                           module_content)
 
 TEMPLATE = Path(__file__).resolve().parent / "templates" / "module"
 NAME = re.compile(r"[a-z][a-z0-9-]*")
@@ -118,10 +119,15 @@ def next_steps(root: Path, name: str, criticality: str, user_facing: bool) -> li
         why = "user-facing" if user_facing else f"criticality {criticality}"
         steps.append(f"Every pull request that changes its behaviour carries a test sheet ({why}), "
                      "run by a verifier who is not its author (T1–T5, docs/os/05-workflow.md §7)")
-    cycle = plan.accepted_cycle(root) if plan.charter_accepted(root) else None
-    if cycle is None:
-        steps.append("The project is not framed: delivery work needs an accepted charter and cycle (K1), "
+    framed = plan.charter_accepted(root)
+    cycle = plan.accepted_cycle(root) if framed else None
+    if not framed:
+        steps.append("The project is not framed: delivery work needs an accepted charter (K1), "
                      "or the out-of-cycle label with its justification (K4)")
+    elif cycle is None:
+        # The charter is accepted: only the next cycle is missing (D47).
+        steps.append("No accepted cycle: delivery work needs one (K1), or the out-of-cycle label "
+                     "with its justification (K4)")
     else:
         steps.append(f"Delivery work names a ready deliverable of {cycle[0].name} (K3), "
                      "or carries the out-of-cycle label with its justification (K4)")
@@ -129,9 +135,40 @@ def next_steps(root: Path, name: str, criticality: str, user_facing: bool) -> li
     return steps
 
 
-def listing(root: Path, base: str | None = None) -> list[dict[str, str]] | None:
-    """Every module — a folder holding a MANIFEST.yaml, contracts/ and platform/ included —
-    or, given a base, those with a file changed since it; None when the base is unknown."""
+def _load(manifest: Path) -> dict:
+    try:
+        data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError:
+        return {}  # reported by nstack manifests (M2)
+    return data if isinstance(data, dict) else {}
+
+
+def _contract_sides(root: Path, changed: list[str]) -> set[str]:
+    """The folders of the modules on either side of a contract version the change touches: the
+    module that provides it, and those that declare it in consumes. The handbook asks for the
+    checks of both sides (docs/os/03-contracts.md §5); the declared graph says who they are, so
+    one repository needs no broker to know (D53)."""
+    provided: dict[tuple[str, str], tuple[str, str]] = {}
+    declared: list[tuple[str, list[dict]]] = []
+    for manifest in find_manifests(root):
+        data = _load(manifest)
+        folder = manifest.parent.relative_to(root).as_posix()
+        for entry in contract_entries(data, "provides"):
+            key, path = (entry.get("contract"), entry.get("version")), entry.get("path")
+            if isinstance(path, str) and all(isinstance(part, str) for part in key):
+                provided[key] = (path.strip("/"), folder)
+        declared.append((folder, contract_entries(data, "consumes")))
+    touched = {key: folder for key, (path, folder) in provided.items()
+               if any(file == path or file.startswith(f"{path}/") for file in changed)}
+    return set(touched.values()) | {folder for folder, consumes in declared for entry in consumes
+                                    if (entry.get("contract"), entry.get("version")) in touched}
+
+
+def listing(root: Path, base: str | None = None,
+            with_contract_sides: bool = False) -> list[dict[str, str]] | None:
+    """Every module — a folder holding a MANIFEST.yaml, contracts/ and platform/ included — or,
+    given a base, those with a file changed since it, and with `with_contract_sides` both sides
+    of a contract version the change touches (D53); None when the base is unknown."""
     found = [{"name": manifest.parent.name, "folder": manifest.parent.relative_to(root).as_posix()}
              for manifest in find_manifests(root)]
     if base is None:
@@ -140,7 +177,11 @@ def listing(root: Path, base: str | None = None) -> list[dict[str, str]] | None:
                       capture_output=True).returncode:
         return None
     changed = changed_files(root, base)
-    return [module for module in found if any(path.startswith(f"{module['folder']}/") for path in changed)]
+    folders = {module["folder"] for module in found
+               if any(path.startswith(f"{module['folder']}/") for path in changed)}
+    if with_contract_sides:
+        folders |= _contract_sides(root, changed)
+    return [module for module in found if module["folder"] in folders]
 
 
 def _modules(root: Path) -> dict[str, Path]:

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/project.py

@@ -55,8 +55,12 @@ def _explain(exc: Exception, command: str, where: Path, source: str, ref: str) -
         return (f"FAIL [{command}] Working tree modified in {where}: an update starts from a "
                 f"committed state (PDR-0001).\n{action}commit or stash (git stash), then run again.")
     if match := DOWNGRADE.search(text):
+        # The action is a command, not a description of one: an install pinned to an exact
+        # version is not moved by `uv tool upgrade`, which is what a reader tries first.
         return (f"FAIL [{command}] Target version {match[2]} older than the project version ({match[1]}): "
-                f"no going back (PDR-0001).\n{action}use nstack {match[1]} or newer.")
+                f"no going back (PDR-0001).\n{action}move this workstation forward first — "
+                'uv tool install "napkinstack@latest" --with-executables-from pre-commit — '
+                f"or pin the version you want, {match[1]} or newer.")
     if text.startswith("Updating is only supported in git-tracked subprojects"):
         return (f"FAIL [{command}] {where} is not a git repository: the merge relies on "
                 f"history.\n{action}git init, commit, then run again.")
@@ -64,9 +68,17 @@ def _explain(exc: Exception, command: str, where: Path, source: str, ref: str) -
         return (f"FAIL [{command}] The project does not come from a published version (_commit in {ANSWERS}): "
                 f"no merge base.\n{action}create the project from a vX.Y.Z tag.")
     if isinstance(exc, OSError) or text == "Local template must be a directory.":
-        detail = [line.split("|", 1)[-1].strip() for line in text.splitlines() if line.strip()][-1]
+        lines = [line.split("|", 1)[-1].strip() for line in text.splitlines() if line.strip()]
+        # git writes the cause on an `error:` line and the outcome on a `fatal:` one; keeping
+        # the last line alone drops the only one that says what happened (D54).
+        detail = " — ".join(line for line in lines if line.startswith(("error:", "fatal:"))) or lines[-1]
+        # A git `error:` line means git refused something local, so the action is local too:
+        # Copier copies the template's uncommitted state into its clone before reading it.
+        local = ("git refused a file of the template's working tree, which Copier copies as it "
+                 "is: commit or stash it, or remove the file git names above.")
+        remote = "check --source and --ref (a vX.Y.Z tag), and network access."
         return (f"FAIL [{command}] Template {source} at version {ref} unreachable: {detail}\n"
-                f"{action}check --source and --ref (a vX.Y.Z tag), and network access.")
+                + action + (local if detail.startswith("error:") else remote))
     return f"FAIL [{command}] Copier: {text}"
 
 

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/provenance.py

@@ -3,7 +3,9 @@ Which framework judges a project (PDR-0005): a published version, or something n
 published — said out loud on every run that judges, never only in a file.
 
 The engine's origin is what its installer recorded (PEP 610, direct_url.json): nothing for a
-version from the registry; a repository and a commit, or a local checkout, otherwise.
+version from the registry; a repository with the ref it was asked for and the commit that ref
+resolved to, or a local checkout, otherwise. A repository is a supported channel and never a
+published one: a tag can be moved, and carries no attestation (ADR-0002).
 """
 
 from __future__ import annotations
@@ -30,7 +32,13 @@ def engine() -> tuple[str, str | None]:
         return distribution.version, None
     data = json.loads(record)
     if "vcs_info" in data:
-        return distribution.version, f"{data['url']}@{str(data['vcs_info'].get('commit_id', ''))[:12]}"
+        # The installer records the ref it was asked for beside the commit (PEP 610). Naming it
+        # says more than a bare sha — and no less: a tag can be moved, so this is still not the
+        # published artefact (ADR-0002, clarified 2026-09-20).
+        commit = str(data["vcs_info"].get("commit_id", ""))[:12]
+        wanted = str(data["vcs_info"].get("requested_revision") or "")
+        return distribution.version, (f"{data['url']} at {wanted} (commit {commit})" if wanted
+                                      else f"{data['url']}@{commit}")
     if "archive_info" in data:
         return distribution.version, "an archive, not the registry"
     path = Path(url2pathname(urlparse(data.get("url", "")).path))

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/pull_request.py

@@ -11,7 +11,8 @@ Rules:
   T3  no scenario passed without its evidence and the commit it was verified on
   T4  evidence produced on the pull request's head commit: the others are to run again
   T5  no scenario failed; none left not verified, unless it is human only
-  K1  delivery work needs an accepted charter and an accepted cycle
+  K1  delivery work needs an accepted charter and an accepted cycle, and says which of
+      the two is missing
   K2  delivery work stops once the cycle is past its end date: the circuit breaker
   K3  delivery work names a ready or in-progress deliverable of the cycle
   K4  the out-of-cycle label carries its justification
@@ -257,11 +258,18 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
                        "\"Out of cycle: <reason>\" to the description — an incident, a production defect.")
         return
     cycle = plan.accepted_cycle(root)
-    if not plan.charter_accepted(root) or cycle is None:
-        fail("K1", "the project is not framed: no accepted charter and cycle in docs/project/.\n"
+    if not plan.charter_accepted(root):
+        fail("K1", "the project is not framed: no accepted charter in docs/project/.\n"
                    "      Action: frame it with your agent (playbooks/framing.md), or add the "
                    f"{LABEL} label with a justification.")
         return
+    if cycle is None:
+        # The charter is accepted: sending the reader back to framing would be false (D47).
+        fail("K1", "no accepted cycle: the charter is accepted, and no cycle is open.\n"
+                   "      Action: open the next cycle with your agent "
+                   "(docs/project/cycles/_TEMPLATE.md), or add the "
+                   f"{LABEL} label with a justification.")
+        return
     path, data = cycle
     end = plan.as_date(data.get("end"))
     if end is not None and today > end:

{napkinstack-0.4.0 → napkinstack-0.6.0}/src/napkinstack/templates/module/MANIFEST.yaml

@@ -71,12 +71,6 @@ commands:
 #  run:                          # optional: local start, with doubles for the dependencies
 #  e2e:                          # optional: end-to-end scenarios; evidence written to .evidence/
 
-# Review budget. Inherited from the project when absent (docs/os/05-workflow.md §4).
-review_budget:
-  max_lines: 400
-  max_files: 15
-  max_modules: 1                 # not adjustable
-
 docs:
   readme: README.md
   agents: AGENTS.md