napkinstack 0.19.2__tar.gz → 0.19.4__tar.gz

{napkinstack-0.19.2 → napkinstack-0.19.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.19.2
+Version: 0.19.4
 Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
 License-Expression: MIT
 License-File: LICENSE
@@ -21,7 +21,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.19.2, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.19.4, 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).
 
@@ -85,8 +85,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.19.2" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.2"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.19.4" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.4"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -127,8 +127,8 @@ Each project then pins its version and changes it through `nstack update`.
 
 **Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
 or on a private one under the Team or Pro plan; on a private repository on the Free plan
-CI informs without blocking
-([a clarification of PDR-0001](docs/pdr/0001-create-a-project-and-receive-updates.md)).
+CI informs without blocking, and `doctor` says the repository *unguarded*
+([PDR-0006](docs/pdr/0006-work-where-the-forge-cannot-guard.md)).
 Off GitHub (GitLab, Forgejo, Gitea, another forge or none), the checks are attested on the
 workstation and every command says what it cannot verify ([PDR-0018](docs/pdr/0018-git-is-required-the-forge-is-the-project-s-choice.md)).
 

{napkinstack-0.19.2 → napkinstack-0.19.4}/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.19.2, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.19.4, 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.19.2" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.2"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.19.4" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.4"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -111,8 +111,8 @@ Each project then pins its version and changes it through `nstack update`.
 
 **Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
 or on a private one under the Team or Pro plan; on a private repository on the Free plan
-CI informs without blocking
-([a clarification of PDR-0001](docs/pdr/0001-create-a-project-and-receive-updates.md)).
+CI informs without blocking, and `doctor` says the repository *unguarded*
+([PDR-0006](docs/pdr/0006-work-where-the-forge-cannot-guard.md)).
 Off GitHub (GitLab, Forgejo, Gitea, another forge or none), the checks are attested on the
 workstation and every command says what it cannot verify ([PDR-0018](docs/pdr/0018-git-is-required-the-forge-is-the-project-s-choice.md)).
 

{napkinstack-0.19.2 → napkinstack-0.19.4}/pyproject.toml

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

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

@@ -154,7 +154,7 @@ CHECKLIST = [  # (rule, setting, action)
     ("G20", "Hold branches `nstack/hold/**/*` cannot be force-pushed nor deleted",
      "Settings → Rules → Rulesets, a ruleset on the branches nstack/hold/**/* — not nstack/hold/**, "
      "which stops at a slash — with nobody on its bypass list: block force pushes and restrict deletions"),
-    # G21: where another contributor's agent approves (PDR-0021), the one who pushed last never
+    # G21: where another agent approves (PDR-0021), the one who pushed last never
     # approves what they pushed — the author's own fix included.
     ("G21", "The most recent push approved by someone other than its pusher (approval: agent)",
      f"{RULESET}: require approval of the most recent reviewable push"),
@@ -361,7 +361,7 @@ CHECKS: dict[str, Callable[[GitHub], bool]] = {
 
 def _default_owner(root: Path) -> tuple[str, str]:
     """L6: `*` first, so that the code owner review covers every path (ADR-0004) — or, where
-    another contributor's agent approves (PDR-0021), a human named for what one must approve and
+    another agent approves (PDR-0021), a human named for what one must approve and
     no default owner, so that the rest is the agents'."""
     from napkinstack.project import answer, forge, ownership
 
@@ -395,7 +395,7 @@ def _kept_for_a_human(root: Path, shown: str, text: str) -> tuple[str, str]:
     default, missing = owners.unowned(root, text)
     if default:
         return GAP, (f"{shown} names a default owner: on approval agent, it leaves no change another "
-                     "contributor's agent may approve.\nAction: remove the `*` rule; name a human for what "
+                     "agent may approve.\nAction: remove the `*` rule; name a human for what "
                      "one must approve (.nstack/handbook/07-governance.md §7).")
     if missing:
         return GAP, (f"{shown} names no owner for " + ", ".join(f"`{path}`" for path in missing)
@@ -409,7 +409,7 @@ def _kept_for_a_human(root: Path, shown: str, text: str) -> tuple[str, str]:
     if len(agents) < 2:
         return OK, (f"The history shows {len(agents) or 'no'} agent identit{'y' if len(agents) == 1 else 'ies'}"
                     + (f" ({agents[0]})" if agents else "") + ": an agent never approves what its own identity "
-                    "pushed, so until another contributor's agent works under an identity of its own, every "
+                    "pushed, so until another agent works under an identity of its own, every "
                     "change waits for a human, as on approval human.")
     return OK, ""
 

{napkinstack-0.19.2 → napkinstack-0.19.4}/src/napkinstack/fitness/manifests.py

@@ -471,7 +471,7 @@ def assembled(manifests: list[Path], root: Path) -> None:
 
 
 def kept_for_a_human(root: Path) -> None:
-    """M13: where another contributor's agent approves, what a human must approve is named in the
+    """M13: where another agent approves, what a human must approve is named in the
     code owners file. The forge reads that file from the base branch, so a pull request raising a
     module's criticality without its line would be approved by an agent: refused here, in CI."""
     from napkinstack import owners
@@ -489,7 +489,7 @@ def kept_for_a_human(root: Path) -> None:
     default, missing = owners.unowned(root, path.read_text(encoding="utf-8"))
     if default:
         fail("code owners", "M13", f"{shown} names a default owner: on approval agent, no change is left "
-                                   "for another contributor's agent.\n      Action: remove the `*` rule.")
+                                   "for another agent.\n      Action: remove the `*` rule.")
     for kept in missing:
         fail("code owners", "M13", f"{shown} ends `{kept}` on no owner: on approval agent, a human "
                                    f"approves it.\n      {action}")

{napkinstack-0.19.2 → napkinstack-0.19.4}/src/napkinstack/modules.py

@@ -103,8 +103,8 @@ def create(root: Path, name: str, owner: str, criticality: str, user_facing: boo
     codeowners = ownership(root)
     line = f"/modules/{name}/"
     if answer(root, "approval") == "agent" and criticality in ("prototype", "standard"):
-        # Another contributor's agent approves it (PDR-0021): no code owner, whose review a human's alone satisfies.
-        print(f"No code owner line for {line}: on approval agent, another contributor's agent approves a "
+        # Another agent approves it (PDR-0021): no code owner, whose review a human's alone satisfies.
+        print(f"No code owner line for {line}: on approval agent, another agent approves a "
               f"{criticality} module.")
     elif codeowners.is_file():
         content = codeowners.read_text(encoding="utf-8")

{napkinstack-0.19.2 → napkinstack-0.19.4}/src/napkinstack/owners.py

@@ -1,7 +1,7 @@
 """
 Who must approve a change, read from the code owners file as the forge reads it (PDR-0021).
 
-On `approval: agent`, another contributor's agent approves what the code owners file names no
+On `approval: agent`, another agent approves what the code owners file names no
 owner for; a human, what it names. So every path a human must approve — the project's rules,
 its records, its answers, the code owners file itself, every module neither `prototype` nor
 `standard` — must end on a rule with an owner. A pattern is read as a gitignore pattern, the

{napkinstack-0.19.2 → napkinstack-0.19.4}/src/napkinstack/pull_request.py

@@ -400,10 +400,20 @@ def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, f
     elif not plan.one_of(states[match[1]], {"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.")
+    elif states[match[1]] == "ready" and not _held(root, match[1]):
+        # Said, not refused. The hold says the work started; the cycle file stays the decider's
+        # record, never changed by a delivery — under `docs/`, a human would have to approve it.
+        warn(f"[K3] deliverable {match[1]} is still 'ready' and nobody holds it while this pull request "
+             f"delivers it.\n      Action: nstack claim {match[1]} — the hold says it is in progress; "
+             f"{path.name} changes in the plan's own pull requests, never in a delivery's.")
+
+
+def _held(root: Path, ident: str) -> bool:
+    """Whether someone holds the deliverable; holds that cannot be read count as none (K5 says so)."""
+    from napkinstack import hold
+
+    found = hold.judge(root, ident)
+    return found is not None and not isinstance(found, str)
 
 
 def identities(root: Path, base: str, head: str) -> set[str]: