napkinstack 0.7.7__tar.gz → 0.9.0__tar.gz

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

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

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

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

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

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

@@ -30,7 +30,7 @@ Rules:
   L7  the template source reachable by anyone: a repository, not a path on one machine
   N1  information, never a gap (D91): a published version newer than the project's, read from
       the registry — the one place a project learns of it. No other command opens a connection
-  G1-G18  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
+  G1-G19  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
           repository, and on a private one G1-G5, G12, G13, G17 and G18 name the GitHub plan
           or option required
 
@@ -117,6 +117,10 @@ CHECKLIST = [  # (rule, setting, action)
     # main, and said nothing of main being deleted or rewritten under them.
     ("G17", "Main branch cannot be deleted", f"{RULESET}: restrict deletions"),
     ("G18", "Main branch history cannot be rewritten: no force push", f"{RULESET}: block force pushes"),
+    # G19: every workflow and ruleset here watches `main`. A repository whose default branch is
+    # another one triggers none of them, and its record of commits on main never runs.
+    ("G19", "Default branch `main`: the branch every workflow and ruleset here watches",
+     "Settings → General → Default branch: rename it main"),
 ]
 
 # Settings specific to public repositories, and settings a private one pays for
@@ -267,6 +271,7 @@ CHECKS: dict[str, Callable[[GitHub], bool]] = {
     "G16": lambda c: _merges(c, "delete_branch_on_merge").get("delete_branch_on_merge") is True,
     "G17": lambda c: _rule(c, "deletion") is not None,
     "G18": lambda c: _rule(c, "non_fast_forward") is not None,
+    "G19": lambda c: _merges(c, "default_branch").get("default_branch") == "main",
 }
 
 

{napkinstack-0.7.7 → napkinstack-0.9.0}/src/napkinstack/landed.py

@@ -14,6 +14,10 @@ It says nothing about what predates it: the commit that created the repository,
 everything the repository already held when the record arrived, are not reported. A record
 that greets a project by failing on its own arrival teaches people to ignore it.
 
+It reads from the last commit it recorded, not from the push alone: a push whose run never
+started — CI out of minutes, a runner down — is read by the next run that does. Its last
+success is read from the forge (actions: read); a record that never succeeded reads the push.
+
 The forge is read with a token supplied by the run (GH_TOKEN, otherwise GITHUB_TOKEN), which
 needs no write access of any kind: the project's automation token stays read-only (G10).
 Without a token, or when the span cannot be read, nothing is claimed.
@@ -73,8 +77,28 @@ def _described(root: Path, commit: str) -> str:
     return _git(root, "show", "-s", "--format=%h (%an, %ad)", "--date=short", commit).stdout.strip()
 
 
+def _since_last_record(root: Path, span: str, forge: GitHub) -> tuple[str, str | None]:
+    """The span widened to start at the last commit the record recorded, and that commit; the
+    span as given, and None, when the push already starts there or the forge cannot say."""
+    try:
+        runs = forge.get(f"/actions/workflows/{Path(RECORD).name}/runs?branch=main&status=success&per_page=1")
+    except NotVerified:
+        return span, None
+    found = (runs or {}).get("workflow_runs") or []
+    last = str(found[0].get("head_sha") or "") if found else ""
+    before, _, after = span.partition("..")
+    if not last or not after or last == before or _git(root, "cat-file", "-e", f"{last}^{{commit}}").returncode:
+        return span, None
+    if _git(root, "merge-base", "--is-ancestor", last, after).returncode:
+        return span, None                     # history rewritten: the push is all that is known
+    if before not in ("", EMPTY) and _git(root, "merge-base", "--is-ancestor", before, last).returncode == 0:
+        return span, None                     # the push starts after the last record already
+    return f"{last}..{after}", last
+
+
 def run(root: Path, span: str, forge: GitHub | None) -> int:
-    commits = _commits(root, span)
+    pushed = _commits(root, span)
+    commits = pushed
     if commits is None:
         print(f"[W1] the commits of '{span}' cannot be read: not verified.\n"
               "      Action: fetch the history (fetch-depth: 0), or pass an existing range.")
@@ -83,6 +107,11 @@ def run(root: Path, span: str, forge: GitHub | None) -> int:
         print("[W1] no token (GH_TOKEN or GITHUB_TOKEN): how each commit arrived is not verified.\n"
               "      Action: supply a token with read access to the repository's pull requests.")
         return 0
+    span, last = _since_last_record(root, span, forge)
+    if last:
+        commits = _commits(root, span) or pushed
+        print(f"Read since the last commit it recorded, {last[:12]}: {len(commits) - len(pushed)} commit(s) "
+              "no run had read.")
     beginning = _beginning(root)
     outside, checked = [], 0
     for commit in commits:

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

@@ -218,7 +218,8 @@ def next_steps(root: Path, name: str, criticality: str, user_facing: bool) -> li
     """What the module's first pull requests will be asked, from facts nstack holds (D33)."""
     from napkinstack.fitness import plan  # here: plan reads HANDLE from this module
 
-    steps = ["Creation ADR in docs/adr/: capability, boundary, alternatives — and the criticality "
+    steps = [f"Creation ADR in the project's docs/adr/, Scope: module {name}: capability, boundary, "
+             "alternatives — and the criticality "
              f"with one sentence saying why {criticality} and not the value below or above; it is "
              "the decider who settles it",
              "MANIFEST.yaml: the responsibility in ONE sentence",

{napkinstack-0.7.7 → napkinstack-0.9.0}/src/napkinstack/pull_request.py

@@ -52,6 +52,8 @@ from napkinstack import assurance
 from napkinstack.fitness.manifests import MODULE_DIRS, changed_files, find_manifests, is_description
 from napkinstack.modules import LOGIN
 
+CHARTER = plan.CHARTER.as_posix()  # docs/project/charter.md, as the diff names it
+
 LABEL = "out-of-cycle"
 DELIVERABLE = re.compile(r"^Deliverable:[ \t]*(D[1-9][0-9]*)\b", re.I | re.M)
 JUSTIFICATION = re.compile(r"^Out of cycle:[ \t]*(\S.*)$", re.I | re.M)
@@ -320,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):
@@ -362,6 +365,27 @@ 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]:
+    """C9: an accepted charter changes only through a PDR (it is the project's founding
+    decision). Said as a warning where the change is — a typo in it is not a decision — and
+    never while the charter is still proposed, which is when the framing writes it."""
+    if CHARTER not in files:
+        return []
+    before = _git(root, "show", f"{base}:{CHARTER}")
+    status = re.search(r"^status:\s*['\"]?(\w+)", before.stdout.split("\n---", 1)[0], re.M) if before.returncode == 0 else None
+    if not status or status.group(1) != "accepted":
+        return []
+    if any(path.startswith("docs/pdr/") and not path.endswith("README.md") for path in files):
+        return []
+    return [f"[C9] {CHARTER}: the accepted charter changes, and no decision record comes with it.\n"
+            "      Action: write the PDR that decides the change, and cite it in the charter; a "
+            "correction that decides nothing needs none (.nstack/playbooks/framing.md, Decisions)."]
 
 
 def run(root: Path, base: str, body_file: Path | None = None) -> int:
@@ -383,6 +407,7 @@ def run(root: Path, base: str, body_file: Path | None = None) -> int:
     labels = {label.strip() for label in os.environ.get("PR_LABELS", "").split(",") if label.strip()}
 
     failures: list[str] = []
+    warnings = charter_without_pdr(root, base, files)
 
     def fail(rule: str, message: str) -> None:
         failures.append(f"[{rule}] {message}")
@@ -397,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'}")
@@ -405,6 +430,8 @@ def run(root: Path, base: str, body_file: Path | None = None) -> int:
         print(line)
     for scenario in human_only:
         print(f"  For the approver, human only: {scenario}")
+    for warning in warnings:
+        print(f"WARNING {warning}")
     for failure in failures:
         print(f"FAIL {failure}")
     if failures:

{napkinstack-0.7.7 → napkinstack-0.9.0}/src/napkinstack/settings.py

@@ -142,6 +142,14 @@ def plan(client: doctor.GitHub | None, missing: set[str]) -> tuple[list[Call], l
         merges["delete_branch_on_merge"] = True
     if merges:
         calls.append((", ".join(rule for rule in ("G14", "G15", "G16") if rule in missing), "PATCH", "", merges))
+    if "G19" in missing:
+        current = "<the default branch>"
+        if client is not None:
+            try:
+                current = str(client.get("").get("default_branch") or current)
+            except doctor.NotVerified:
+                pass
+        calls.append(("G19", "POST", f"/branches/{current}/rename", {"new_name": "main"}))
     return calls, notes
 
 

{napkinstack-0.7.7 → napkinstack-0.9.0}/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.7.7 → napkinstack-0.9.0}/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.7.7 → napkinstack-0.9.0}/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.7.7 → napkinstack-0.9.0}/src/napkinstack/templates/module/MANIFEST.yaml

@@ -79,5 +79,4 @@ commands:
 docs:
   readme: README.md
   agents: AGENTS.md
-  adr: docs/adr/
   # runbook: docs/runbook.md     # required when criticality >= high

napkinstack-0.9.0/src/napkinstack/templates/module/README.md

@@ -0,0 +1,21 @@
+# {{MODULE_NAME}}
+
+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 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
+
+- Provided: see `provides` in the MANIFEST
+- Consumed: see `consumes` in the MANIFEST
+
+## Decisions
+
+In the project's `docs/adr/` and `docs/pdr/`, marked `Scope: module {{MODULE_NAME}}`.

napkinstack-0.7.7/src/napkinstack/templates/module/README.md

@@ -1,24 +0,0 @@
-# {{MODULE_NAME}}
-
-<One sentence: what this module is for.>
-
-- **Owner**: {{OWNER}}
-- **Criticality**: {{CRITICALITY}}
-- **Manifest**: [MANIFEST.yaml](./MANIFEST.yaml)
-
-<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:
-`.nstack/handbook/09-platform.md` §2.
-
-## Contracts
-
-- Provided: see `provides` in the MANIFEST
-- Consumed: see `consumes` in the MANIFEST
-
-## Decisions
-
-See `docs/adr/`.