napkinstack 0.5.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.5.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,18 +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. 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).
+> 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
@@ -86,8 +89,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.4.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.4.0"
+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
@@ -118,6 +121,7 @@ Each project then pins its version and changes it through `nstack update`.
 | `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.5.0 → napkinstack-0.6.0}/README.md

@@ -5,18 +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. 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).
+> 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
@@ -71,8 +74,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.4.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.4.0"
+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
@@ -103,6 +106,7 @@ Each project then pins its version and changes it through `nstack update`.
 | `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.5.0 → napkinstack-0.6.0}/pyproject.toml

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

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

@@ -19,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.")
@@ -63,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)",
@@ -98,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))

{napkinstack-0.5.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.5.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.5.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.5.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-]*")
@@ -134,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:
@@ -145,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.5.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.5.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