napkinstack 0.7.6__tar.gz → 0.7.7__tar.gz

{napkinstack-0.7.6 → napkinstack-0.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.7.6
+Version: 0.7.7
 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.7.6, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.7.7, 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.7.6" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.6"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.7.7" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.7"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a

{napkinstack-0.7.6 → napkinstack-0.7.7}/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.7.6, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.7.7, 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.7.6" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.6"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.7.7" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.7"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a

{napkinstack-0.7.6 → napkinstack-0.7.7}/pyproject.toml

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

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

@@ -8,7 +8,7 @@ import sys
 from pathlib import Path
 
 from napkinstack import assurance
-from napkinstack import (__version__, compat, discovery, doctor, landed, modules, provenance, settings,
+from napkinstack import (compat, discovery, doctor, landed, modules, provenance, settings,
                          pull_request, skills)
 from napkinstack.fitness import boundaries, hygiene, manifests, plan, pr_scope
 
@@ -59,9 +59,19 @@ def _update(args: argparse.Namespace) -> int:
     return project.update(args.root, args.ref or project.default_ref())
 
 
+class _Version(argparse.Action):
+    """The version, as the first line of a judging run says it: a version installed from
+    anywhere but the registry is no published version (PDR-0005)."""
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        version, origin = provenance.engine()
+        print(f"nstack {version}" + (f" — UNPUBLISHED: {origin}" if origin else ""))
+        parser.exit()
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="nstack", description="NapkinStack engine.")
-    parser.add_argument("--version", action="version", version=f"nstack {__version__}")
+    parser.add_argument("--version", action=_Version, nargs=0, help="the engine's version, and where it came from")
     sub = parser.add_subparsers(dest="command", required=True, metavar="command")
     _add(sub, "manifests", "manifests, lifecycles, deprecations (M1-M10)",
          lambda a: manifests.run(a.root))
@@ -96,16 +106,19 @@ def build_parser() -> argparse.ArgumentParser:
     for verb, help_text in (("bootstrap", "prepares one module, or all of them (commands.bootstrap)"),
                             ("check", "format, lint, types of one module, or all (commands.check)"),
                             ("test", "tests of one module, or of all of them (commands.test)"),
-                            ("e2e", "end-to-end scenarios of one module, or of all (commands.e2e)")):
+                            ("e2e", "end-to-end scenarios of one module, or of all (commands.e2e)"),
+                            ("clean", "removes what one module's commands left in its folder, or all "
+                                      "modules' (commands.clean)")):
         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(sub, "run", "starts a module locally (commands.run), with what follows passed to it",
+              lambda a: _run(a))
     rn.add_argument("module")
+    rn.add_argument("arguments", nargs=argparse.REMAINDER, help="passed to the module's command")
     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",
@@ -137,11 +150,11 @@ def build_parser() -> argparse.ArgumentParser:
     ini.add_argument("--owner-team", help="owner of the foundation: organisation/team, or a user "
                                           "when the project has no organisation (asked when absent)")
     ini.add_argument("--source", help="template: URL or path (default: the NapkinStack repository)")
-    ini.add_argument("--ref", help="skeleton version, tag vX.Y.Z (default: the one of nstack)")
+    ini.add_argument("--ref", help="skeleton version: a tag vX.Y.Z, or a commit (default: the one of nstack)")
     ini.set_defaults(func=_init)
     up = _add(sub, "update", "merges a NapkinStack version onto a branch to review",
               _update)
-    up.add_argument("--ref", help="target version, tag vX.Y.Z (default: the one of nstack)")
+    up.add_argument("--ref", help="target version: a tag vX.Y.Z, or a commit (default: the one of nstack)")
     return parser
 
 
@@ -160,6 +173,16 @@ def _named_root(argv: list[str]) -> Path:
     return Path(".")
 
 
+def _run(a) -> int:
+    """`run` passes what follows the module to its command; `--root`, written there as the
+    other verbs take it, is still the root."""
+    root, arguments = a.root, list(a.arguments)
+    if "--root" in arguments[:-1]:
+        at = arguments.index("--root")
+        root, arguments = _root(arguments[at + 1]), arguments[:at] + arguments[at + 2:]
+    return modules.run_verb(root, "run", a.module, arguments)
+
+
 def main(argv: list[str] | None = None) -> int:
     argv = sys.argv[1:] if argv is None else argv
     if late := provenance.behind(_named_root(argv)):

{napkinstack-0.7.6 → napkinstack-0.7.7}/src/napkinstack/doctor.py

@@ -6,7 +6,10 @@ project. CHECKLIST is printed by nstack init, checked here, and repeated word fo
 the foundation manual, skeleton/.nstack/handbook/INSTALL.md.jinja (a test verifies it).
 
 The registry is asked one question, without a token: which version is the latest published
-(NSTACK_REGISTRY_URL, otherwise https://pypi.org). An answer changes no exit code.
+(NSTACK_REGISTRY_URL, otherwise https://pypi.org). An answer changes no exit code. For a project
+pinned to an unpublished commit, the framework's repository is asked another, without a token
+either: whether its default branch holds that commit (GITHUB_API_URL, otherwise
+https://api.github.com). No answer leaves L1 as it is.
 
 GitHub is read with a token supplied by a human (GH_TOKEN, otherwise GITHUB_TOKEN):
 fine-grained, limited to the repository, Administration: read permission. Without a token,
@@ -14,7 +17,9 @@ or when the API refuses a read, the setting is "not verified", never compliant.
 
 Rules:
   L1  nstack installed at the project version (_commit in .copier-answers.yml), both
-      published: an unpublished framework is a gap, never compliance (PDR-0005)
+      published: an unpublished framework is a gap, never compliance (PDR-0005) — and a pinned
+      commit the framework's default branch does not hold, a pull request's head, is said with
+      the gesture that moves the pin once it is merged
   L2  git and pre-commit available
   L3  pre-commit hooks installed
   L4  retired (D79): it refused a file named PRODUCT.md, which a product may write. The
@@ -67,6 +72,7 @@ THIRD_PARTY_ACTIONS = ("astral-sh/setup-uv",)  # non-GitHub actions of the skele
 LABELS = ("cross-module", "over-budget", "out-of-cycle")
 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)?/?$")
 
 RULESET = "Settings → Rules → Rulesets, main branch"
 SECURITY = "Settings → Advanced Security"
@@ -277,17 +283,54 @@ def _default_owner(root: Path) -> tuple[str, str]:
                  "its first rule: the code owner review then covers every path (.nstack/handbook/07-governance.md §7).")
 
 
+def _forge(path: str) -> dict | None:
+    """JSON of a public repository's page on the forge, read without a token; None when it does
+    not answer."""
+    api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/")
+    request = urllib.request.Request(f"{api}{path}", headers={
+        "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": API_VERSION,
+        "User-Agent": f"nstack/{__version__}"})
+    try:
+        with urllib.request.urlopen(request, timeout=5) as response:
+            data = json.load(response)
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _left_behind(answers: dict) -> str | None:
+    """The framework's default branch, when it does not hold the pinned commit; None when it
+    does, or when the forge could not say. A fix may be pinned while it is reviewed; its squash
+    then gives the default branch another commit, and leaves this one on no branch."""
+    commit = str(answers.get("_commit") or "")
+    repository = ON_GITHUB.match(str(answers.get("_src_path") or ""))
+    if "-g" not in commit or not repository:
+        return None
+    sha, repo = commit.rsplit("-g", 1)[1], repository.group(1)
+    branch = (_forge(f"/repos/{repo}") or {}).get("default_branch")
+    status = (_forge(f"/repos/{repo}/compare/{branch}...{sha}") or {}).get("status") if branch else None
+    return branch if status in ("ahead", "diverged") else None
+
+
 def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
     commit = str(answers.get("_commit") or "")
     project = commit.removeprefix("v")
-    install = f'uv tool install "napkinstack=={project}" --with-executables-from pre-commit'
+    install = (f'uv tool install "napkinstack=={project}" --with-executables-from pre-commit'
+               if PUBLISHED.fullmatch(commit) else "bash .nstack/install-engine.sh")
     results = []
 
     _, origin = provenance.engine()
     if not PUBLISHED.fullmatch(commit):
-        l1 = (GAP, f"The project is pinned to an unpublished framework ({commit or 'unknown'}): its "
-                   "verdicts come from rules nobody has published.\nAction: once the change it "
-                   "waits for is released, nstack update --ref vX.Y.Z.")
+        branch = _left_behind(answers)
+        if branch:
+            l1 = (GAP, f"The project is pinned to an unpublished framework ({commit}), a commit the "
+                       f"framework's {branch} does not hold: a pull request's head, which its squash leaves "
+                       f"on no branch.\nAction: once it is merged, nstack update --ref <the commit {branch} "
+                       "received for that change>, or --ref vX.Y.Z, a release that carries it.")
+        else:
+            l1 = (GAP, f"The project is pinned to an unpublished framework ({commit or 'unknown'}): its "
+                       "verdicts come from rules nobody has published.\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}).\nAction: {install}")
     elif project != __version__:

{napkinstack-0.7.6 → napkinstack-0.7.7}/src/napkinstack/fitness/hygiene.py

@@ -64,6 +64,16 @@ def tracked_files(root: Path) -> list[Path] | None:
     return [root / name for name in names if name]
 
 
+def untracked(root: Path) -> int:
+    """How many files git does not track yet and does not ignore."""
+    try:
+        listed = subprocess.run(["git", "ls-files", "-z", "--others", "--exclude-standard"], cwd=root,
+                                check=True, capture_output=True)
+    except (OSError, subprocess.CalledProcessError):
+        return 0
+    return len([name for name in listed.stdout.split(b"\0") if name])
+
+
 def run(root: Path) -> int:
     files = tracked_files(root)
     if files is None:
@@ -88,6 +98,11 @@ def run(root: Path) -> int:
                                 f"directory — {ACTION}")
 
     print(f"Hygiene: {read} tracked text file(s) read.")
+    # A file not yet added is read by nobody here and by everyone once committed: said, so
+    # that a check passed before `git add` is not taken for one passed on the commit.
+    waiting = untracked(root)
+    if waiting:
+        print(f"Hygiene: {waiting} file(s) not yet added to git, not read — add them and run it again.")
     for failure in failures:
         print(f"  FAIL {failure}")
     if failures:

{napkinstack-0.7.6 → napkinstack-0.7.7}/src/napkinstack/fitness/manifests.py

@@ -50,8 +50,21 @@ failures: list[str] = []
 warnings: list[str] = []
 
 
-def fail(module: str, rule: str, message: str) -> None:
-    failures.append(f"[{rule}] {module}\n      {message}")
+def fail(module: str, rule: str, message: str, at: str = "") -> None:
+    """A refusal: the rule, the module, the place — `file:line` — and, in the message, the action (P6)."""
+    failures.append(f"[{rule}] {module}" + (f" — {at}" if at else "") + f"\n      {message}")
+
+
+def line_of(text: str, *keys: str) -> int:
+    """The line of `keys`, each one searched below the one before; the deepest found, or 1."""
+    lines, found, start = text.splitlines(), 1, 0
+    for key in keys:
+        pattern = re.compile(rf"^\s*(?:-\s*)?{re.escape(key)}\s*:")
+        hit = next((index for index in range(start, len(lines)) if pattern.match(lines[index])), None)
+        if hit is None:
+            break
+        found, start = hit + 1, hit + 1
+    return found
 
 
 def warn(module: str, rule: str, message: str) -> None:
@@ -156,42 +169,59 @@ def parse_date(value) -> datetime.date | None:
         return None
 
 
-def check_manifest(path: Path, today: datetime.date) -> None:
+def check_manifest(path: Path, today: datetime.date, root: Path | None = None) -> None:
     rel = path.parent.name
+    folder = path.parent.relative_to(root).as_posix() if root else rel
+    text = path.read_text(encoding="utf-8")
+
+    def at(*keys: str) -> str:
+        return f"{folder}/MANIFEST.yaml:{line_of(text, *keys)}"
+
     try:
-        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        data = yaml.safe_load(text) or {}
     except yaml.YAMLError as exc:
-        fail(rel, "M2", f"MANIFEST.yaml unreadable: {exc}")
+        mark = getattr(exc, "problem_mark", None)
+        fail(rel, "M2", f"MANIFEST.yaml unreadable: {exc}\n      Action: correct the YAML at that line.",
+             f"{folder}/MANIFEST.yaml:{mark.line + 1 if mark else 1}")
         return
     if not isinstance(data, dict):
-        fail(rel, "M2", "MANIFEST.yaml must be a YAML mapping (sections module, commands, docs...).")
+        fail(rel, "M2", "MANIFEST.yaml must be a YAML mapping (sections module, commands, docs...).\n"
+                        "      Action: rewrite it as a mapping — nstack new-module writes one to copy.",
+             f"{folder}/MANIFEST.yaml:1")
         return
     for section, expected_type in SECTIONS.items():
         if data.get(section) is not None and not isinstance(data[section], expected_type):
             fail(rel, "M2", f"section {section}: expected a {TYPES[expected_type]}, "
-                            f"found {type(data[section]).__name__}.")
+                            f"found {type(data[section]).__name__}.\n"
+                            f"      Action: write {section} as a {TYPES[expected_type]}.", at(section))
             data[section] = expected_type()
 
     mod = data.get("module") or {}
     for field in ("name", "code_name"):
         if field in mod and not isinstance(mod[field], str):
-            fail(rel, "M2", f"module.{field} {mod[field]!r} must be text.")
+            fail(rel, "M2", f"module.{field} {mod[field]!r} must be text.\n      Action: write it quoted.",
+                 at("module", field))
     owns = (data.get("data") or {}).get("owns")
     if isinstance(owns, list) and not all(isinstance(table, str) for table in owns):
-        fail(rel, "M2", "data.owns: every entry names a table, as text.")
+        fail(rel, "M2", "data.owns: every entry names a table, as text.\n"
+                        "      Action: write each table's name, quoted.", at("data", "owns"))
 
     # M2 - required fields
     for field in REQUIRED_FIELDS:
         if not mod.get(field):
-            fail(rel, "M2", f"required field missing: module.{field}")
+            fail(rel, "M2", f"required field missing: module.{field}\n"
+                            f"      Action: add {field}: under module:.", at("module", field))
 
     # M3 - valid values
     lifecycle = mod.get("lifecycle")
     if lifecycle and lifecycle not in LIFECYCLES:
-        fail(rel, "M3", f"invalid lifecycle: '{lifecycle}'. Expected one of: {sorted(LIFECYCLES)}")
+        fail(rel, "M3", f"invalid lifecycle: '{lifecycle}'. Expected one of: {sorted(LIFECYCLES)}\n"
+                        "      Action: write one of them.", at("module", "lifecycle"))
     criticality = mod.get("criticality")
     if criticality and criticality not in CRITICALITIES:
-        fail(rel, "M3", f"invalid criticality: '{criticality}'. Expected one of: {sorted(CRITICALITIES)}")
+        fail(rel, "M3", f"invalid criticality: '{criticality}'. Expected one of: {sorted(CRITICALITIES)}\n"
+                        "      Action: write one of them — what each one costs: .nstack/handbook/05-workflow.md §7.",
+             at("module", "criticality"))
 
     # M4 - responsibility in one sentence
     resp = (mod.get("responsibility") or "").strip()
@@ -207,10 +237,13 @@ def check_manifest(path: Path, today: datetime.date) -> None:
         dep = dep if isinstance(dep, dict) else {}
         removal = parse_date(dep.get("removal_date"))
         if not removal:
-            fail(rel, "M5", "module deprecated without a valid module.deprecation.removal_date (YYYY-MM-DD)")
+            fail(rel, "M5", "module deprecated without a valid module.deprecation.removal_date (YYYY-MM-DD)\n"
+                            "      Action: add deprecation: with removal_date: YYYY-MM-DD under module:.",
+                 at("module", "deprecation", "removal_date"))
         elif removal < today:
-            fail(rel, "M5", f"removal date passed ({removal}). Permanent intermediate state - "
-                            "remove the module or supersede the decision.")
+            fail(rel, "M5", f"removal date passed ({removal}). Permanent intermediate state.\n"
+                            "      Action: remove the module, or supersede the decision that deprecated it.",
+                 at("module", "deprecation", "removal_date"))
 
     # M2 - the contract entries the boundaries and the versions are judged on (D36)
     for section, fields in CONTRACT_FIELDS.items():
@@ -219,25 +252,30 @@ def check_manifest(path: Path, today: datetime.date) -> None:
                 continue  # reported below for provides; ignored by the checks that read them
             for field in fields:
                 if field in entry and not isinstance(entry[field], str):
-                    fail(rel, "M2", f"{section}: {field} {entry[field]!r} must be text — "
-                                    f"write it quoted, for example \"v1\".")
+                    fail(rel, "M2", f"{section}: {field} {entry[field]!r} must be text.\n"
+                                    f"      Action: write it quoted, for example \"v1\".", at(section, field))
             if section == "provides" and entry.get("stability", "experimental") not in STABILITIES:
                 fail(rel, "M2", f"provides: stability {entry.get('stability')!r}, expected one of "
-                                f"{sorted(STABILITIES)}: a stable or deprecated version is frozen (V1).")
+                                f"{sorted(STABILITIES)}: a stable or deprecated version is frozen (V1).\n"
+                                "      Action: write one of them.", at("provides", "stability"))
 
     # M6 - deprecation of provided contracts
     for provided in data.get("provides") or []:
         if not isinstance(provided, dict):
-            fail(rel, "M2", "entry of provides: expected a mapping (contract, version, stability).")
+            fail(rel, "M2", "entry of provides: expected a mapping (contract, version, stability).\n"
+                            "      Action: write the entry as contract:, version: and stability:.", at("provides"))
             continue
         if provided.get("stability") == "deprecated":
             name = f"{provided.get('contract')}@{provided.get('version')}"
             removal = parse_date(provided.get("removal_date"))
             if not removal:
-                fail(rel, "M6", f"deprecated contract {name} without a removal_date")
+                fail(rel, "M6", f"deprecated contract {name} without a removal_date\n"
+                                "      Action: add removal_date: YYYY-MM-DD to that entry of provides.",
+                     at("provides", "stability"))
             elif removal < today:
-                fail(rel, "M6", f"contract {name}: removal date passed ({removal}). "
-                                "Finish the contraction (.nstack/handbook/03-contracts.md §4).")
+                fail(rel, "M6", f"contract {name}: removal date passed ({removal}).\n"
+                                "      Action: finish the contraction (.nstack/handbook/03-contracts.md §4).",
+                     at("provides", "removal_date"))
 
     commands = data.get("commands") or {}
     content = module_content(path.parent)
@@ -248,14 +286,14 @@ def check_manifest(path: Path, today: datetime.date) -> None:
     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 (.nstack/handbook/02-modules.md §5).")
+                        "in MANIFEST.yaml (.nstack/handbook/02-modules.md §5).", at("module", "responsibility"))
 
     # 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 "
                             f"than its description ({content[0]}).\n      Action: declare its stack's "
-                            "command in the manifest (.nstack/handbook/09-platform.md §2).")
+                            "command in the manifest (.nstack/handbook/09-platform.md §2).", at("commands"))
 
     # M8 - what the criticality requires, read from the matrix of 05-workflow.md §7 and
     # never from a threshold copied here (D67). Each refusal names the value that produced it and
@@ -269,20 +307,54 @@ def check_manifest(path: Path, today: datetime.date) -> None:
             fail(rel, "M8", f"{declared} requires an existing runbook "
                             "(.nstack/handbook/05-workflow.md §7; what it holds: .nstack/playbooks/operations.md)"
                             f"{_relief(criticality, 'runbook')}\n      Action: declare docs.runbook "
-                            "in MANIFEST.yaml and create that file — nstack new-module writes one.")
+                            "in MANIFEST.yaml and create that file — nstack new-module writes one.",
+                 at("docs", "runbook") if "runbook" in (data.get("docs") or {}) else at("docs"))
 
     # M9 - file envelope
     for expected in ["AGENTS.md", "README.md"]:
         if not (path.parent / expected).is_file():
-            fail(rel, "M9", f"envelope file missing: {expected}")
+            fail(rel, "M9", f"envelope file missing: {expected}\n      Action: create it — "
+                            "what it holds: .nstack/handbook/02-modules.md.", f"{folder}/{expected}")
     if not (path.parent / "tests").is_dir() and criticality != "prototype":
-        fail(rel, "M9", "tests/ folder missing")
+        fail(rel, "M9", "tests/ folder missing\n      Action: create it, with the module's first test.",
+             f"{folder}/tests/")
 
     # M10 - a user-visible surface declared: it decides the test sheet (.nstack/handbook/05-workflow.md §7)
     if not isinstance(mod.get("user_facing"), bool):
         fail(rel, "M10", "module.user_facing must be true or false: does a user see this module? "
                          "true requires a test sheet on its pull requests from standard up "
-                         "(.nstack/handbook/05-workflow.md §7)")
+                         "(.nstack/handbook/05-workflow.md §7)\n"
+                         "      Action: write user_facing: true or false under module:.",
+             at("module", "user_facing"))
+
+
+def comparator_owed(root: Path, manifests: list[Path]) -> None:
+    """V1, said when it can still be met: once a contract is consumed, a change to it is
+    refused unless the contracts module's merged comparator proves it compatible — a
+    corrected example as much as a renamed field."""
+    folder = root / "contracts" / "MANIFEST.yaml"
+    if not folder.is_file():
+        return
+    try:
+        commands = (yaml.safe_load(folder.read_text(encoding="utf-8")) or {}).get("commands") or {}
+    except yaml.YAMLError:
+        return
+    if not isinstance(commands, dict) or commands.get("compat"):
+        return
+    consumers = []
+    for manifest in manifests:
+        try:
+            data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            continue
+        if contract_entries(data, "consumes"):
+            consumers.append(manifest.parent.relative_to(root).as_posix())
+    if consumers:
+        warn("contracts", "V1", f"contracts are consumed ({', '.join(sorted(consumers))}) and "
+                                "contracts/MANIFEST.yaml declares no commands.compat: from now on a change "
+                                "to a consumed version — a corrected example as much as a renamed field — "
+                                "is refused. Declare the comparator first, in a pull request of its own "
+                                "(.nstack/handbook/03-contracts.md §3).")
 
 
 def run(root: Path) -> int:
@@ -299,7 +371,8 @@ def run(root: Path) -> int:
                                 "Action: create it, or create the module with nstack new-module.")
 
     for manifest in manifests:
-        check_manifest(manifest, today)
+        check_manifest(manifest, today, root)
+    comparator_owed(root, manifests)
 
     print(f"Manifests checked: {len(manifests)}")
     for w in warnings:

{napkinstack-0.7.6 → napkinstack-0.7.7}/src/napkinstack/modules.py

@@ -1,6 +1,6 @@
 """
 A project's modules: creation (nstack new-module) and standard verbs (nstack bootstrap,
-check, test, run), with no imposed stack (PRODUCT.md P1, PDR-0001 R5).
+check, test, run, e2e, clean), with no imposed stack (PRODUCT.md P1, PDR-0001 R5).
 
 Each verb runs the command declared in the `commands` section of the module's
 MANIFEST.yaml, from its folder, through the system shell. NapkinStack never assumes a
@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import re
 import shutil
+import shlex
 import subprocess
 from pathlib import Path
 
@@ -29,7 +30,7 @@ HANDLE = r"(?=[A-Za-z0-9-]{1,39}$)[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*"
 LOGIN = r"[A-Za-z0-9](?:-?[A-Za-z0-9]){0,38}"  # the same rule, unanchored: a handle inside a sentence
 OWNER = re.compile(  # same rule as copier.yml: organisation/team, or a GitHub user
     rf"[A-Za-z0-9-]+/[A-Za-z0-9._-]+|{HANDLE}")
-OPTIONAL = {"bootstrap": "nothing to prepare", "e2e": "no end-to-end scenario"}  # undeclared: skipped
+OPTIONAL = {"bootstrap": "nothing to prepare", "e2e": "no end-to-end scenario", "clean": "nothing to clean"}  # undeclared: skipped
 # What a criticality requires is the matrix of .nstack/handbook/05-workflow.md §7, read once (assurance).
 
 RUNBOOK = """# Runbook - {name}
@@ -299,7 +300,7 @@ def _modules(root: Path) -> dict[str, Path]:
     return {manifest.parent.name: manifest.parent for manifest in find_manifests(root)}
 
 
-def run_verb(root: Path, verb: str, name: str | None) -> int:
+def run_verb(root: Path, verb: str, name: str | None, arguments: list[str] | None = None) -> int:
     known = _modules(root)
     if name is not None and name not in known:
         print(f"FAIL [{verb}] module '{name}' not found in {root}: no MANIFEST.yaml under that name.\n"
@@ -327,6 +328,8 @@ def run_verb(root: Path, verb: str, name: str | None) -> int:
             print(f"FAIL [{verb}] module '{target}': commands.{verb} not declared in {manifest}.\n"
                   "      Action: declare the module stack's command there (.nstack/handbook/09-platform.md §2).")
             return 1
+        if arguments:
+            command = " ".join([command, *map(shlex.quote, arguments)])
         print(f"-> {target}: {command}", flush=True)
         code = subprocess.run(command, shell=True, cwd=known[target]).returncode
         if code:

{napkinstack-0.7.6 → napkinstack-0.7.7}/src/napkinstack/templates/contracts/MANIFEST.yaml

@@ -15,9 +15,11 @@ data:
   shared: []
 dependencies: []
 
-# Declared with the first contract: check and test are required once this folder holds one
-# (fitness M7), and compat once a version is consumed or stable (nstack compat, V1). The
-# tools are the project's, named in .nstack/tooling-profile.md.
+# compat before any version is consumed: from then on a change to a consumed version — a
+# corrected example as much as a renamed field — passes only with this command as merged
+# (nstack compat, V1), and `nstack manifests` warns while it is missing. check and test are
+# required once this module holds code (fitness M7). The tools are the project's, named in
+# .nstack/tooling-profile.md.
 commands:
 #  check:     # validates every contract document against its format
 #  test:      # the contract tests, run on both sides (.nstack/handbook/03-contracts.md §5)

{napkinstack-0.7.6 → napkinstack-0.7.7}/src/napkinstack/templates/module/MANIFEST.yaml

@@ -73,6 +73,8 @@ commands:
 #  bootstrap:                    # optional: make the module usable from a fresh clone
 #  run:                          # optional: local start, with doubles for the dependencies
 #  e2e:                          # optional: end-to-end scenarios; evidence written to .evidence/
+#  clean:                        # optional: remove what the commands above leave in this folder
+#                                # (build outputs); CI runs it after every job on a self-hosted runner
 
 docs:
   readme: README.md