napkinstack 0.8.0__tar.gz → 0.9.1__tar.gz

{napkinstack-0.8.0 → napkinstack-0.9.1}/PKG-INFO

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

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

{napkinstack-0.8.0 → napkinstack-0.9.1}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.8.0"
+version = "0.9.1"
 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.8.0 → napkinstack-0.9.1}/src/napkinstack/pull_request.py

@@ -322,7 +322,8 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
     return human_only
 
 
-def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, fail: Fail) -> None:
+def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, fail: Fail,
+                warn: Callable[[str], None] = lambda message: None) -> None:
     """K1 to K4, for delivery work."""
     if LABEL in labels:
         if not JUSTIFICATION.search(body):
@@ -364,6 +365,10 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
     elif states[match[1]] not in {"ready", "in-progress"}:
         fail("K3", f"deliverable {match[1]} is '{states[match[1]]}': work starts on a ready "
                    "deliverable (definition of ready).")
+    elif states[match[1]] == "ready":
+        # Said, not refused: the state is the decider's record, and this pull request knows (PDR-0002).
+        warn(f"[K3] deliverable {match[1]} is still 'ready' while this pull request delivers it.\n"
+             f"      Action: set its state: in-progress in {path.name}, in this pull request.")
 
 
 def charter_without_pdr(root: Path, base: str, files: list[str]) -> list[str]:
@@ -417,7 +422,7 @@ def run(root: Path, base: str, body_file: Path | None = None) -> int:
     human_only = check_sheet(body, head, reasons, fail, authorship, rerun_at_head(modules),
                              lambda commit: bool(tree_of(commit)) and tree_of(commit) == tree_of(head))
     if modules:
-        check_cycle(root, body, labels, datetime.date.today(), fail)
+        check_cycle(root, body, labels, datetime.date.today(), fail, warnings.append)
 
     print(f"Modules touched : {len(modules)}" + "".join(f"\n  - {folder}" for folder in modules))
     print(f"Test sheet      : {'required' if reasons else 'not required'}")

{napkinstack-0.8.0 → napkinstack-0.9.1}/src/napkinstack/skills.py

@@ -48,11 +48,24 @@ def normalise(text: str) -> str:
     return " ".join(text.split())
 
 
+def trigger(playbook: str) -> str:
+    """A playbook's trigger, as its header says it — the kernel's words (§4), on one line."""
+    match = re.search(r"^> \*\*Trigger\.\*\* (.+?)(?=\n>\s*\n|\n\n|\Z)", playbook, re.S | re.M)
+    return normalise(match.group(1).replace("\n> ", " ")) if match else ""
+
+
+def described(entry: dict, playbook: str) -> str:
+    """What the skill holds, from the mapping, and when it loads, from its playbook: one list of
+    triggers, the kernel's, which the playbook's header says again word for word."""
+    when = trigger(playbook)
+    return normalise(entry["description"]) + (f" {when}" if when else "")
+
+
 def build(root: Path, name: str, entry: dict) -> tuple[Path, str]:
     body = (root / entry["source"]).read_text(encoding="utf-8")
     # Serialised, never concatenated: a ":" or "#" in a description would break the YAML.
     frontmatter = yaml.safe_dump(
-        {"name": name, "description": normalise(entry["description"])},
+        {"name": name, "description": described(entry, body)},
         allow_unicode=True, sort_keys=False, width=float("inf"),
     )
     content = "---\n" + frontmatter + "---\n\n" + BANNER.format(source=entry["source"]) + "\n\n" + body

{napkinstack-0.8.0 → napkinstack-0.9.1}/src/napkinstack/templates/contracts/AGENTS.md

@@ -22,5 +22,6 @@ contract tests do.
 
 ## Before changing anything
 
-Check the consumer matrix, generated from the manifests. A version is only removed once
+Check who consumes it, read from the manifests: `nstack modules --with-contract-sides`, and
+B6 for a version consumed and provided by nobody. A version is only removed once
 `consumers = 0`.

{napkinstack-0.8.0 → napkinstack-0.9.1}/src/napkinstack/templates/module/AGENTS.md

@@ -8,7 +8,7 @@
 
 ## Responsibility
 
-<One sentence. The same as the one in the MANIFEST.>
+The one sentence of `MANIFEST.yaml` (`module.responsibility`); not repeated here.
 
 ## What this module does not do
 
@@ -24,8 +24,8 @@
 
 ## Known traps
 
-<What has already broken here. Every entry should become a test - see
-.nstack/handbook/10-measurement.md §4.>
+<One line per trap — the situation, then what to do. Every entry becomes a test
+(.nstack/handbook/10-measurement.md §4); a story of what happened goes to the log issue.>
 
 ## Areas not to change without approval
 

{napkinstack-0.8.0 → napkinstack-0.9.1}/src/napkinstack/templates/module/README.md

@@ -1,17 +1,14 @@
 # {{MODULE_NAME}}
 
-<One sentence: what this module is for.>
-
-- **Owner**: {{OWNER}}
-- **Criticality**: {{CRITICALITY}}
-- **Manifest**: [MANIFEST.yaml](./MANIFEST.yaml)
+What this module is for, who owns it and how critical it is: its
+[MANIFEST.yaml](./MANIFEST.yaml), the one place they are written.
 
 <A diagram, with its legend: what this module provides, what it consumes, who uses it.>
 
 ## Getting started
 
-The standard verbs — `bootstrap`, `check`, `test`, `run` — are declared in the `commands`
-section of the [manifest](./MANIFEST.yaml), for this module's stack. What each one must do:
+The standard verbs are declared in the `commands` section of the [manifest](./MANIFEST.yaml),
+for this module's stack. Which they are, and what each one must do:
 `.nstack/handbook/09-platform.md` §2.
 
 ## Contracts