napkinstack 0.3.1__tar.gz → 0.5.0__tar.gz

{napkinstack-0.3.1 → napkinstack-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.3.1
+Version: 0.5.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,11 +20,18 @@ 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.3.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): test sheet,
-> framing and bounded cycles. A first pilot project, private, starts from it and puts it to
-> the test before the rest. Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
+> **Status: v0.4.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. Proved on the project that exposed the defects: eight probes
+> replayed, each refused or accepted as announced. A first pilot project, private, starts from
+> v0.5.0, which closes a way around the contract check found while proving it (D44) and says
+> what holds on a repository no plan lets the forge guard (PDR-0006).
+> 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),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -75,10 +82,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.4.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.4.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
 
@@ -90,8 +112,10 @@ the commit of this repository
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
 | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
 | `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures |
-| `nstack fitness` | Manifests, boundaries between modules, skills, plan |
+| `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene |
 | `nstack pr-scope` | One PR = one module, review budget |
+| `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
+| `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 skills` | Exposes the playbooks as skills for the agent |

{napkinstack-0.3.1 → napkinstack-0.5.0}/README.md

@@ -5,11 +5,18 @@ 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.3.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): test sheet,
-> framing and bounded cycles. A first pilot project, private, starts from it and puts it to
-> the test before the rest. Tracking: [engine roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
+> **Status: v0.4.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. Proved on the project that exposed the defects: eight probes
+> replayed, each refused or accepted as announced. A first pilot project, private, starts from
+> v0.5.0, which closes a way around the contract check found while proving it (D44) and says
+> what holds on a repository no plan lets the forge guard (PDR-0006).
+> 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),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -60,10 +67,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.4.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.4.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
 
@@ -75,8 +97,10 @@ the commit of this repository
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
 | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
 | `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures |
-| `nstack fitness` | Manifests, boundaries between modules, skills, plan |
+| `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene |
 | `nstack pr-scope` | One PR = one module, review budget |
+| `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
+| `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 skills` | Exposes the playbooks as skills for the agent |

{napkinstack-0.3.1 → napkinstack-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.3.1"
+version = "0.5.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.3.1 → napkinstack-0.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.3.1"
+version = "0.5.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.3.1 → napkinstack-0.5.0}/src/napkinstack/cli.py

@@ -3,14 +3,12 @@
 from __future__ import annotations
 
 import argparse
-import os
-import subprocess
+import json
 from pathlib import Path
 
-from napkinstack import __version__, discovery, doctor, modules, pull_request, skills
-from napkinstack.fitness import boundaries, manifests, plan
-
-PACKAGE = Path(__file__).resolve().parent
+from napkinstack import (__version__, compat, discovery, doctor, landed, modules, provenance,
+                         pull_request, skills)
+from napkinstack.fitness import boundaries, hygiene, manifests, plan, pr_scope
 
 
 def _root(value: str) -> Path:
@@ -20,13 +18,19 @@ def _root(value: str) -> Path:
     return root
 
 
-def _script(relative: str, *args: str, root: Path) -> int:
-    env = {**os.environ, "NSTACK_ROOT": str(root)}
-    return subprocess.run(["bash", str(PACKAGE / relative), *args], cwd=root, env=env).returncode
+def _modules(args: argparse.Namespace) -> int:
+    found = modules.listing(args.root, args.changed_since)
+    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.")
+        return 1
+    print(json.dumps(found) if args.json else "\n".join(f"{m['name']}\t{m['folder']}" for m in found))
+    return 0
 
 
 def _fitness(root: Path) -> int:
-    results = [manifests.run(root), boundaries.run(root), skills.run(root, check_only=True), plan.run(root)]
+    results = [manifests.run(root), boundaries.run(root), skills.run(root, check_only=True),
+               plan.run(root), hygiene.run(root)]
     return 1 if any(results) else 0
 
 
@@ -57,15 +61,17 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="nstack", description="NapkinStack engine.")
     parser.add_argument("--version", action="version", version=f"nstack {__version__}")
     sub = parser.add_subparsers(dest="command", required=True, metavar="command")
-    _add(sub, "manifests", "manifests, lifecycles, deprecations (M1-M9)",
+    _add(sub, "manifests", "manifests, lifecycles, deprecations (M1-M10)",
          lambda a: manifests.run(a.root))
-    _add(sub, "boundaries", "declared graph against real graph (B1-B5)",
+    _add(sub, "boundaries", "declared graph against real graph (B1-B7)",
          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)",
               lambda a: skills.run(a.root, check_only=a.check))
     sk.add_argument("--check", action="store_true", help="check without writing")
-    _add(sub, "fitness", "manifests + boundaries + skills + plan",
+    _add(sub, "hygiene", "no path from one person's machine in a tracked file (H1)",
+         lambda a: hygiene.run(a.root))
+    _add(sub, "fitness", "manifests + boundaries + skills + plan + hygiene",
          lambda a: _fitness(a.root))
     _add(sub, "doctor", "diagnoses the workstation and the GitHub settings, read-only (PDR-0001)",
          lambda a: doctor.run(a.root))
@@ -83,16 +89,27 @@ def build_parser() -> argparse.ArgumentParser:
                             ("e2e", "end-to-end scenarios of one module, or of all (commands.e2e)")):
         vb = _add(sub, verb, help_text, lambda a, v=verb: modules.run_verb(a.root, v, a.module))
         vb.add_argument("module", nargs="?", help="module name (default: all)")
+    cp = _add(sub, "compat", "a frozen contract version changes only with a proof (V1, commands.compat)",
+              lambda a: compat.run(a.root, a.module, a.base))
+    cp.add_argument("module", nargs="?", help="module holding the contracts (default: all)")
+    cp.add_argument("--base", default="origin/main")
     rn = _add(sub, "run", "starts a module locally (commands.run)",
               lambda a: modules.run_verb(a.root, "run", a.module))
     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("--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: _script("fitness/pr_scope.sh", a.base, root=a.root))
+              lambda a: pr_scope.run(a.root, a.base))
     ps.add_argument("--base", default="origin/main")
     pc = _add(sub, "pr-check", "test sheet and cycle, read from the pull request description (T1-T5, K1-K4)",
               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")
@@ -111,6 +128,12 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+JUDGES = {"manifests", "boundaries", "plan", "skills", "hygiene", "fitness", "doctor", "pr-scope",
+          "pr-check", "compat", "landed"}  # the commands whose verdict depends on the framework's rules
+
+
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
+    if args.command in JUDGES:
+        print(provenance.judged_by(args.root), flush=True)
     return args.func(args)

napkinstack-0.5.0/src/napkinstack/compat.py

@@ -0,0 +1,188 @@
+"""
+Contract versions (D30): a merged version that someone relies on changes only with a proof
+that the change is additive (docs/os/03-contracts.md §3 and §4).
+
+Rule:
+  V1  a frozen contract version changes only when the compatibility command of the module
+      holding it, commands.compat, proves the change compatible
+
+A version is frozen when, at the base, a module consumes it or its producer declares it
+stable or deprecated. Both the freeze and the proof are read at the base: a pull request can
+neither thaw what it changes nor replace the command that judges it — a new proof is merged
+on its own first.
+An experimental version nobody consumes is free to change — nobody can break. Its files are
+those under provides[].path; a new version beside it changes nothing merged. A version still
+provided at the head is judged wherever it now lives: moving it is no removal (D36).
+
+The command is the project's (P1: no format assumed): an OpenAPI, protobuf or JSON Schema
+comparator, named in docs/tooling-profile.md. It runs from the holding module's folder with
+  NSTACK_CONTRACT   the contract's name                    catalog-api
+  NSTACK_VERSION    the version                            v1
+  NSTACK_BASE_PATH  the version as merged, extracted to a temporary folder
+  NSTACK_HEAD_PATH  the version as changed, in the working tree
+and exits 0 when the change is compatible.
+
+Usage :  nstack compat [module] [--root ROOT] [--base BASE]
+Output:  0 when every changed frozen version is proven compatible, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import subprocess
+import tarfile
+import tempfile
+from pathlib import Path
+
+import yaml
+
+from napkinstack.fitness.manifests import MODULE_DIRS, changed_files, contract_entries, find_manifests
+
+FROZEN_STABILITIES = {"stable", "deprecated"}
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+
+
+def _load(text: str) -> dict:
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def frozen_versions(root: Path, base: str) -> dict[tuple[str, str], tuple[str, str]]:
+    """(contract, version) -> (path, why it is frozen), from the manifests at the base."""
+    manifests = [_load(_git(root, "show", f"{base}:{path}").stdout)
+                 for path in _git(root, "ls-tree", "-r", "--name-only", base).stdout.split()
+                 if path.endswith("/MANIFEST.yaml") and path.split("/")[0] in MODULE_DIRS
+                 and len(path.split("/")) in (2, 3)]
+    consumers: dict[tuple[str, str], list[str]] = {}
+    for data in manifests:
+        name = (data.get("module") or {}).get("name") if isinstance(data.get("module"), dict) else None
+        for entry in contract_entries(data, "consumes"):
+            consumers.setdefault((entry.get("contract"), entry.get("version")), []).append(str(name))
+    frozen = {}
+    for data in manifests:
+        for entry in contract_entries(data, "provides"):
+            key, path = (entry.get("contract"), entry.get("version")), entry.get("path")
+            if not isinstance(path, str) or not all(isinstance(part, str) for part in key):
+                continue
+            if key in consumers:
+                frozen[key] = (path.strip("/"), f"consumed by {', '.join(sorted(consumers[key]))}")
+            elif entry.get("stability") in FROZEN_STABILITIES:
+                frozen[key] = (path.strip("/"), entry["stability"])
+    return frozen
+
+
+def provided_now(root: Path) -> dict[tuple[str, str], str]:
+    """(contract, version) -> path, from the manifests at the head."""
+    now = {}
+    for manifest in find_manifests(root):
+        for entry in contract_entries(_load(manifest.read_text(encoding="utf-8")), "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):
+                now[key] = path.strip("/")
+    return now
+
+
+def _holder(root: Path, path: str) -> tuple[str, Path] | None:
+    """The module whose folder holds `path`: its name and folder."""
+    for manifest in sorted(find_manifests(root), key=lambda m: -len(m.parent.parts)):
+        folder = manifest.parent.relative_to(root).as_posix()
+        if path == folder or path.startswith(f"{folder}/"):
+            return manifest.parent.name, manifest.parent
+    return None
+
+
+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
+
+
+def run(root: Path, module: str | None, base: str) -> int:
+    if _git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}").returncode:
+        print(f"FAIL [V1] base '{base}' not found: the merged contract versions cannot be read.\n"
+              "      Action: fetch the history (fetch-depth: 0), or pass an existing commit.")
+        return 1
+    fork = _git(root, "merge-base", base, "HEAD").stdout.strip() or base
+    changed = changed_files(root, fork)
+    now = provided_now(root)
+    failures, checked = [], []
+    for (contract, version), (path, why) in sorted(frozen_versions(root, fork).items()):
+        target = now.get((contract, version))
+        if not any(file == place or file.startswith(f"{place}/") for file in changed
+                   for place in {path, target} if place):
+            continue
+        label = f"{contract} {version} ({why})"
+        if target is None:
+            checked.append(f"{label}: no longer provided — its consumers are checked by B6")
+            continue
+        if target != path:
+            label += f", moved to {target}"
+        holder = _holder(root, target)
+        if holder is None:
+            failures.append(f"[V1] {label} changed at '{target}', which no module holds: nothing declares "
+                            "how its versions are compared.\n      Action: keep contracts under contracts/ "
+                            "(docs/os/03-contracts.md §2).")
+            continue
+        if module is not None and holder[0] != module:
+            continue
+        if not (root / target).exists():
+            failures.append(f"[V1] {label}: provided at '{target}', which holds no document (B7).\n"
+                            "      Action: commit the version there, or correct provides[].path.")
+            continue
+        if not _git(root, "ls-tree", "-r", "--name-only", fork, "--", path).stdout.strip():
+            checked.append(f"{label}: no document at the base, nothing merged to compare")
+            continue
+        name, folder = holder
+        where = f"{folder.relative_to(root).as_posix()}/MANIFEST.yaml"
+        commands = _load(_git(root, "show", f"{fork}:{where}").stdout).get("commands")
+        command = commands.get("compat") if isinstance(commands, dict) else None
+        if not command:
+            failures.append(f"[V1] {label} changed, and no merged compatibility command proves the "
+                            f"change compatible.\n      Action: declare commands.compat in {where} in a "
+                            "pull request of its own (docs/tooling-profile.md), or publish the change as "
+                            "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(tree / path), "NSTACK_HEAD_PATH": str(root / target)}
+            print(f"-> {name}: {command}", flush=True)
+            code = subprocess.run(command, shell=True, cwd=where_it_runs, env=env).returncode
+        if code:
+            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:
+        print(f"Contract version {line}.")
+    for failure in failures:
+        print(f"FAIL {failure}")
+    if failures:
+        return 1
+    if not checked:
+        print("No frozen contract version changed.")
+    return 0

{napkinstack-0.3.1 → napkinstack-0.5.0}/src/napkinstack/doctor.py

@@ -10,14 +10,16 @@ fine-grained, limited to the repository, Administration: read permission. Withou
 or when the API refuses a read, the setting is "not verified", never compliant. No write.
 
 Rules:
-  L1  nstack installed at the project version (_commit in .copier-answers.yml)
+  L1  nstack installed at the project version (_commit in .copier-answers.yml), both
+      published: an unpublished framework is a gap, never compliance (PDR-0005)
   L2  git and pre-commit available
   L3  pre-commit hooks installed
   L4  PRODUCT.md absent: that is NapkinStack's own development context (R6)
   L5  README personalised: the presentation sentence is written
   L6  CODEOWNERS starts with a default owner: the code owner review covers every path
-  G1-G12  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
-          repository, and on a private one G1-G5 and G12 name the GitHub plan or option required
+  L7  the template source reachable by anyone: a repository, not a path on one machine
+  G1-G13  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
+          repository, and on a private one G1-G5, G12 and G13 name the GitHub plan or option required
 
 Usage :  nstack doctor [--root ROOT]
 Output:  0 when everything is verified and compliant, 1 otherwise.
@@ -38,16 +40,22 @@ from pathlib import Path
 
 import yaml
 
-from napkinstack import __version__
+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")
+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")
-PUBLISHED = re.compile(r"v\d+(\.\d+)*((a|b|rc)\d+)?(\.post\d+)?(\.dev\d+)?")
+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
 
 RULESET = "Settings → Rules → Rulesets, main branch"
 SECURITY = "Settings → Advanced Security"
@@ -60,7 +68,8 @@ CHECKLIST = [  # (rule, setting, action)
     ("G2", "At least 1 approving review", f"{RULESET}: at least 1 approval required"),
     ("G3", "Code owner review required", f"{RULESET}: require Code Owners review"),
     ("G4", "Required checks: " + ", ".join(f"`{job}`" for job in JOBS),
-     f"{RULESET}: require these status checks"),
+     f"{RULESET}: require these status checks. GitHub offers a check only once it has run: "
+     "open a first pull request, then select them"),
     ("G5", "Secret Protection and push protection",
      f"{SECURITY}: enable Secret Protection and push protection"),
     ("G6", "Private vulnerability reporting, public repository (the `SECURITY.md` channel)",
@@ -76,13 +85,15 @@ CHECKLIST = [  # (rule, setting, action)
      "Issues → Labels: create " + ", ".join(LABELS[:-1]) + f" and {LABELS[-1]}"),
     ("G12", "Bypass list empty: nobody merges around the rules, administrators included",
      f"{RULESET}: remove every bypass actor"),
+    ("G13", "Stale approvals dismissed when new commits are pushed",
+     f"{RULESET}: dismiss stale pull request approvals when new commits are pushed"),
 ]
 
 # Settings specific to public repositories, and settings a private one pays for
 # (GitHub documentation, 2026-09-15).
 PUBLIC_ONLY = {"G6": "private vulnerability reporting only exists for a public repository; "
                      "state an internal channel in SECURITY.md"}
-PRIVATE_PLAN = dict.fromkeys(("G1", "G2", "G3", "G4", "G12"),
+PRIVATE_PLAN = dict.fromkeys(("G1", "G2", "G3", "G4", "G12", "G13"),
                              "Private repository: rulesets require the GitHub Team plan (organisation) "
                              "or Pro (personal account); without it, nothing blocks the merge.")
 PRIVATE_PLAN["G5"] = ("Private repository: Secret Protection is a paid option; without it, only the "
@@ -93,6 +104,10 @@ class NotVerified(Exception):
     """Setting unreadable: token, permission or network."""
 
 
+class Gap(Exception):
+    """Setting missing, with an action more precise than the checklist's."""
+
+
 class GitHub:
     """Reads of the GitHub REST API, cached; never a write."""
 
@@ -163,7 +178,8 @@ def _no_bypass(client: GitHub) -> bool:
     """G12: every ruleset applying to main has an empty bypass list (ADR-0004)."""
     rulesets = {rule["ruleset_id"] for rule in client.get("/rules/branches/main") if rule.get("ruleset_id")}
     if not rulesets:
-        return False
+        raise Gap(f"no ruleset applies to main, so there is no bypass list to empty. {RULESET}: "
+                  "create the ruleset first (G1)")
     for ruleset in sorted(rulesets):
         actors = client.get(f"/rulesets/{ruleset}?includes_parents=true").get("bypass_actors")
         if actors is None:
@@ -188,6 +204,7 @@ CHECKS: dict[str, Callable[[GitHub], bool]] = {
     "G10": _workflows,
     "G11": lambda c: all(c.get(f"/labels/{label}", missing=True) is not None for label in LABELS),
     "G12": _no_bypass,
+    "G13": lambda c: _parameters(c, "pull_request").get("dismiss_stale_reviews_on_push") is True,
 }
 
 
@@ -210,8 +227,13 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
     install = f'uv tool install "napkinstack=={project}" --with-executables-from pre-commit'
     results = []
 
+    _, origin = provenance.engine()
     if not PUBLISHED.fullmatch(commit):
-        l1 = (UNKNOWN, f"Reason: the project comes from an unpublished version ({commit or 'unknown'}).")
+        l1 = (GAP, f"The project is pinned to an unpublished framework ({commit or 'unknown'}): its "
+                   "verdicts come from rules nobody has published (PDR-0005).\nAction: once the change it "
+                   "waits for is released, nstack update --ref vX.Y.Z.")
+    elif origin is not None:
+        l1 = (GAP, f"The nstack running is unpublished ({origin}) (PDR-0005).\nAction: {install}")
     elif project != __version__:
         l1 = (GAP, f"nstack {__version__} installed, project on {project} (PDR-0001 R3).\nAction: {install}")
     else:
@@ -246,6 +268,12 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
                     "Action: write the sentence that presents the project." if untouched else ""))
 
     results.append(("L6", "CODEOWNERS starts with a default owner", *_default_owner(root)))
+
+    source = str(answers.get("_src_path") or "")
+    local = not REMOTE.match(source)
+    results.append(("L7", "Template source reachable by anyone", GAP if local else OK,
+                    f"The project was generated from '{source}', a path on one machine: nobody else can "
+                    "update it (PDR-0005).\nAction: nstack update, from the published source." if local else ""))
     return results
 
 
@@ -263,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 "
@@ -297,17 +354,22 @@ def run(root: Path) -> int:
                 status, detail = (OK, "") if CHECKS[rule](client) else (GAP, f"Action: {action}")
             except NotVerified as reason:
                 status, detail = UNKNOWN, f"Reason: {reason}"
+            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.")