napkinstack 0.18.0__tar.gz → 0.19.0__tar.gz

{napkinstack-0.18.0 → napkinstack-0.19.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.18.0
+Version: 0.19.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
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: copier==9.18.2
+Requires-Dist: pathspec>=0.12
 Requires-Dist: pre-commit==4.6.2
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/NapkinStack/engineering-os
@@ -20,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.18.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.19.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 +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.18.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.18.0"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.19.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -111,16 +112,16 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
 | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
-| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures; then the project across its cycles, and who holds what |
+| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures, and the decisions due at a closure; then the project across its cycles, and who holds what |
 | `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
 | `nstack pr-scope` | One PR = one module, review budget |
 | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
 | `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 e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
 | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
 | `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 attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks` |
+| `nstack attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks`; attesting the same commit again keeps the module checks it passed (`--again` runs them) |
 | `nstack skills` | Exposes the playbooks as skills for the agent |
 | `nstack update [--session <id>] [--forge <name>]` | Lays the new version on a branch to review; an agent's session as the commit's `Agent-Session` trailer; `--forge` moves the project to another forge, its own lines kept |
 

{napkinstack-0.18.0 → napkinstack-0.19.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.18.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.19.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.18.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.18.0"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.19.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -96,16 +96,16 @@ Each project then pins its version and changes it through `nstack update`.
 | `nstack new-contract <name>` | Creates a contract and, the first time, the module that holds them all |
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
 | `nstack discover <idea-file>` | Starts a discovery for your agent: the idea kept, its document created |
-| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures; then the project across its cycles, and who holds what |
+| `nstack plan` | The discovery, the charter and the cycles: formats, one cycle at a time, closures, and the decisions due at a closure; then the project across its cycles, and who holds what |
 | `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: `manifests`, `boundaries`, `skills`, `plan`, `hygiene` |
 | `nstack pr-scope` | One PR = one module, review budget |
 | `nstack modules [--changed-since <base>]` | The project's modules, or those with a file changed since a base |
 | `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 e2e [module]` | Runs the module's end-to-end scenarios, when declared — one run at a time on a machine |
 | `nstack release [module] [args]` | Makes each module's artefacts into `dist/<module>/`, each after what it assembles; what follows a named module goes to its command |
 | `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 attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks` |
+| `nstack attest --base <base> --body-file <description>` | The CI's checks run here, on a clean head; the run recorded on the commit, in git (`refs/notes/nstack/checks`), and shown on GitHub as `nstack / local checks`; attesting the same commit again keeps the module checks it passed (`--again` runs them) |
 | `nstack skills` | Exposes the playbooks as skills for the agent |
 | `nstack update [--session <id>] [--forge <name>]` | Lays the new version on a branch to review; an agent's session as the commit's `Agent-Session` trailer; `--forge` moves the project to another forge, its own lines kept |
 

{napkinstack-0.18.0 → napkinstack-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.18.0"
+version = "0.19.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"
@@ -9,6 +9,7 @@ readme = "README.md"
 dependencies = [
     "PyYAML>=6.0",
     "copier==9.18.2",
+    "pathspec>=0.12",
     "pre-commit==4.6.2",
 ]
 

{napkinstack-0.18.0 → napkinstack-0.19.0}/pyproject.toml.orig

@@ -1,12 +1,12 @@
 [project]
 name = "napkinstack"
-version = "0.18.0"
+version = "0.19.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"
 license-files = ["LICENSE"]
 readme = "README.md"
-dependencies = ["PyYAML>=6.0", "copier==9.18.2", "pre-commit==4.6.2"]
+dependencies = ["PyYAML>=6.0", "copier==9.18.2", "pathspec>=0.12", "pre-commit==4.6.2"]
 
 [project.urls]
 Homepage = "https://github.com/NapkinStack/engineering-os"

{napkinstack-0.18.0 → napkinstack-0.19.0}/src/napkinstack/attest.py

@@ -78,15 +78,35 @@ def _git(root: Path, *args: str, check: bool = True) -> subprocess.CompletedProc
     return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True, check=check)
 
 
+MARK = 48  # bytes a cut's mark may take: `[… N bytes cut …]` and its newlines
+
+
+def _cut(data: bytes, room: int) -> str:
+    """Whole up to room bytes, else a quarter of it from the head, the rest from the tail."""
+    if len(data) <= room:
+        return data.decode("utf-8", "ignore")
+    head = max(room - MARK, 0) // 4
+    tail = max(room - MARK, 0) - head
+    return (data[:head].decode("utf-8", "ignore") + f"\n[… {len(data) - head - tail} bytes cut …]\n"
+            + (data[-tail:].decode("utf-8", "ignore") if tail else ""))
+
+
 def capped(text: str) -> str:
-    """A step's output as the record keeps it: whole up to KEPT bytes, else its head and its tail."""
+    """A step's output as the record keeps it: whole up to KEPT bytes, else cut log group by log
+    group — one per module in Module checks — so that each keeps its commands and its results,
+    the room a small one leaves going to the others (#295). No group: one head and one tail."""
     data = text.encode("utf-8", "replace")
     if len(data) <= KEPT:
         return text
-    half = KEPT // 2
-    cut = len(data) - KEPT
-    return (data[:half].decode("utf-8", "ignore") + f"\n[… {cut} bytes cut …]\n"
-            + data[-half:].decode("utf-8", "ignore"))
+    starts = [found.start() for found in re.finditer(rb"^::group::", data, re.M)]
+    bounds = [0, *(start for start in starts if start), len(data)]
+    parts = [data[start:end] for start, end in zip(bounds, bounds[1:])]
+    room, given = KEPT, {}
+    for index in sorted(range(len(parts)), key=lambda index: len(parts[index])):
+        share = room // (len(parts) - len(given))
+        given[index] = min(len(parts[index]), share)
+        room -= given[index]
+    return "".join(_cut(part, given[index]) for index, part in enumerate(parts))
 
 
 def unplaced(value, root: Path):

{napkinstack-0.18.0 → napkinstack-0.19.0}/src/napkinstack/cli.py

@@ -96,7 +96,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="nstack", description="NapkinStack engine.")
     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, what a release assembles (M1-M11)",
+    _add(sub, "manifests", "manifests, lifecycles, deprecations, what a release assembles, evidence, who approves (M1-M13)",
          lambda a: manifests.run(a.root))
     _add(sub, "boundaries", "declared graph against real graph, release artefacts included (B1-B9)",
          lambda a: boundaries.run(a.root))
@@ -143,7 +143,7 @@ def build_parser() -> argparse.ArgumentParser:
               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")
-    rl = _add(sub, "release", "makes one module's artefacts, or all of them, each into dist/<module> "
+    rl = _add(sub, "release", "makes one module's artefacts, or all of them, each into dist/<module>, emptied first "
                               "(commands.release), with what follows a named module passed to it",
               lambda a: _release(a))
     rl.add_argument("module", nargs="?", help="module name (default: all, each after what it assembles)")
@@ -165,7 +165,7 @@ def build_parser() -> argparse.ArgumentParser:
               lambda a: modules.create_contract(a.root, a.name, a.owner))
     nc.add_argument("name", help="the contract's name, kebab-case")
     nc.add_argument("--owner", help="owner of the contracts module (default: the foundation's owner)")
-    pc = _add(sub, "pr-check", "test sheet and cycle, read from the pull request description (T1-T5, K1-K5)",
+    pc = _add(sub, "pr-check", "test sheet, cycle and attested checks, read from the pull request description (T1-T5, K1-K5, A1-A2, C9)",
               lambda a: pull_request.run(a.root, a.base, a.body_file, a.labels))
     pc.add_argument("--base", default="origin/main")
     pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
@@ -191,7 +191,7 @@ def build_parser() -> argparse.ArgumentParser:
     cl.add_argument("--person", help="the person accountable, such as @alice (default: git's user)")
     cl.add_argument("--take-over", action="store_true",
                     help="take a hold nobody has worked on for hold_days — recorded, with its previous holder")
-    rs = _add(sub, "unclaim", "gives a held deliverable back: by its holder, the decider, or anyone once stale",
+    rs = _add(sub, "unclaim", "gives a held deliverable back: by its holder, the decider, or anyone once stale; a closed cycle's hold has ended",
               lambda a: hold.release(a.root, a.deliverable, a.session, a.person))
     rs.add_argument("deliverable", help="the deliverable's identifier, D<n>")
     rs.add_argument("--session", help="the agent's session, written on the release")

{napkinstack-0.18.0 → napkinstack-0.19.0}/src/napkinstack/doctor.py

@@ -37,9 +37,9 @@ Rules:
       known public forge is said, never judged: a mirror is a choice
   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-G20  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
+  G1-G21  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
+          repository, G21 outside `approval: agent`, and on a private one G1-G5, G12, G13, G17,
+          G18, G20 and G21 name the GitHub plan or option required
 
 Off GitHub (the project's `forge` answer, ADR-0010) no G rule is read: the forge-neutral
 PROTECTIONS are said as information — the same list as INSTALL.md's, bound by a test — and the
@@ -77,7 +77,7 @@ SOURCES = "SOURCES"  # a contributor's checkout holding the project's version: s
 OUT_OF_REACH = "OUT OF REACH"      # the plan forbids it: a state, not a fault (PDR-0006)
 # The settings that make the forge refuse a merge. A repository is guarded when they are
 # all in force; the others matter and none of them stops a merge.
-BLOCKING = ("G1", "G2", "G3", "G4", "G12", "G13")
+BLOCKING = ("G1", "G2", "G3", "G4", "G12", "G13", "G21")
 API_VERSION = "2026-03-10"
 JOBS = ("Fitness functions", "PR scope and review budget", "Hooks and secrets", "Test sheet and cycle",
         "Module checks")
@@ -154,13 +154,29 @@ 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
+    # 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"),
 ]
 
+# Asked of a project only on one of its answers: elsewhere not applicable, and said why.
+ANSWERED = {"G21": ("approval", "agent", "the project's approval is human: a code owner approves every change")}
+
+
+def unasked(rule: str, answers: dict) -> str | None:
+    """Why a rule is not asked of this project, or None when it is."""
+    if rule not in ANSWERED:
+        return None
+    key, value, reason = ANSWERED[rule]
+    return None if answers.get(key) == value else reason
+
+
 # Settings specific to public repositories, and settings a private one pays for
 # (GitHub documentation, 2026-09-15).
 PUBLIC_ONLY = {"G6": "private vulnerability reporting only exists for a public repository; "
                      "state an internal channel in SECURITY.md"}
-PRIVATE_PLAN = dict.fromkeys(("G1", "G2", "G3", "G4", "G12", "G13", "G17", "G18", "G20"),
+PRIVATE_PLAN = dict.fromkeys(("G1", "G2", "G3", "G4", "G12", "G13", "G17", "G18", "G20", "G21"),
                              "Private repository: rulesets require the GitHub Team plan (organisation) "
                              "or Pro (personal account); without it, nothing blocks the merge.")
 PRIVATE_PLAN["G5"] = ("Private repository: Secret Protection is a paid option; without it, only the "
@@ -339,19 +355,25 @@ CHECKS: dict[str, Callable[[GitHub], bool]] = {
     "G18": lambda c: _rule(c, "non_fast_forward") is not None,
     "G19": lambda c: _merges(c, "default_branch").get("default_branch") == "main",
     "G20": _holds_kept,
+    "G21": lambda c: _parameters(c, "pull_request").get("require_last_push_approval") is True,
 }
 
 
 def _default_owner(root: Path) -> tuple[str, str]:
-    """L6: `*` first, so that the code owner review covers every path (ADR-0004)."""
-    from napkinstack.project import forge, ownership
+    """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
+    no default owner, so that the rest is the agents'."""
+    from napkinstack.project import answer, forge, ownership
 
     path = ownership(root)  # where the project's forge reads it (ADR-0010)
     shown = path.relative_to(root).as_posix()
+    agent = answer(root, "approval") == "agent"
     if not path.is_file():
-        return GAP, f"{shown} missing.\nAction: create it, starting with `*  @<owner>`."
+        return GAP, f"{shown} missing.\nAction: create it" + ("." if agent else ", starting with `*  @<owner>`.")
     rules = [line.split() for line in path.read_text(encoding="utf-8").splitlines()
              if line.strip() and not line.lstrip().startswith("#")]
+    if agent:
+        return _kept_for_a_human(root, shown, path.read_text(encoding="utf-8"))
     if rules and rules[0][0] == "*" and len(rules[0]) > 1:
         name = forge(root)
         if name in UNREAD_OWNERSHIP:
@@ -364,6 +386,28 @@ 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 _kept_for_a_human(root: Path, shown: str, text: str) -> tuple[str, str]:
+    """L6 on `approval: agent`: no default owner, and every path a human must approve ends on a
+    rule with an owner (`owners.py`; in CI, rule M13)."""
+    from napkinstack import owners
+    from napkinstack.project import forge
+
+    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 "
+                     "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)
+                     + ": on approval agent, a human approves them.\nAction: end each on a line "
+                     "`/<path>  @<owner>`, the owner a team of people (.nstack/handbook/07-governance.md §7).")
+    name = forge(root)
+    if name in UNREAD_OWNERSHIP or name == "none":
+        return OK, ("No forge reads it here: who approves what is for people to read, and nothing refuses "
+                    "an agent's approval of the rest.")
+    return OK, ""
+
+
 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."""
@@ -448,7 +492,9 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
         l3 = (OK, "") if installed else (GAP, "Action: pre-commit install")
     results.append(("L3", "pre-commit hooks installed", *l3))
 
-    results.append(("L6", "CODEOWNERS starts with a default owner", *_default_owner(root)))
+    results.append(("L6", "CODEOWNERS names a human where one approves (approval: agent)"
+                     if answers.get("approval") == "agent" else "CODEOWNERS starts with a default owner",
+                     *_default_owner(root)))
 
     source = str(answers.get("_src_path") or "")
     local = not REMOTE.match(source)
@@ -540,6 +586,7 @@ def _state(results: list[tuple[str, str, str, str]]) -> None:
     be read (PDR-0006)."""
     status_of = {rule: status for rule, _, status, _ in results}
     blocking = [status_of.get(rule, UNKNOWN) for rule in BLOCKING]
+    blocking = [status for status in blocking if status != NOT_APPLICABLE]  # G21 off `approval: agent`
     if any(status == UNKNOWN for status in blocking):
         print("\nThis repository: not verified — what cannot be read is never reported as guarded.")
         return
@@ -629,7 +676,9 @@ def run(root: Path) -> int:
               "Administration: read permission, then run again.")
     private = client is not None and _private(client)
     for rule, setting, action in CHECKLIST:
-        if client is None:
+        if unasked(rule, answers):
+            status, detail = NOT_APPLICABLE, f"Reason: {unasked(rule, answers)}."
+        elif client is None:
             status, detail = UNKNOWN, ""
         elif private and rule in PUBLIC_ONLY:
             status, detail = NOT_APPLICABLE, f"Reason: {PUBLIC_ONLY[rule]}."

{napkinstack-0.18.0 → napkinstack-0.19.0}/src/napkinstack/fitness/manifests.py

@@ -21,6 +21,9 @@ Rules:
       (.nstack/handbook/09-platform.md §2, D127)
   M12 evidence declares what the module's end-to-end scenarios provoke: patterns that compile and
       check something, a level, a scenario (ADR-0009)
+  M13 on `approval: agent`, the code owners file names a human for every module neither
+      `prototype` nor `standard`, and for the project's rules, with no default owner (PDR-0021) —
+      in the same pull request that raises a module's criticality
 
 Usage :  nstack manifests [--root ROOT]
 Output:  0 if everything passes, 1 otherwise. Every failure explains the rule broken.
@@ -467,13 +470,39 @@ def assembled(manifests: list[Path], root: Path) -> None:
                               "      Action: one of them stops assembling the other.", places[name])
 
 
+def kept_for_a_human(root: Path) -> None:
+    """M13: where another contributor's 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
+    from napkinstack.project import answer, ownership
+
+    if answer(root, "approval") != "agent":
+        return
+    path = ownership(root)
+    shown = path.relative_to(root).as_posix()
+    action = ("Action: end each on a line `/<path>  @<owner>`, the owner a team of people, in this pull request "
+              "(.nstack/handbook/07-governance.md §7).")
+    if not path.is_file():
+        fail("code owners", "M13", f"{shown} missing: on approval agent, nothing keeps a change for a human.\n      {action}")
+        return
+    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 kept in missing:
+        fail("code owners", "M13", f"{shown} ends `{kept}` on no owner: on approval agent, a human "
+                                   f"approves it.\n      {action}")
+
+
 def run(root: Path) -> int:
     failures.clear()
     warnings.clear()
     today = datetime.date.today()
     manifests = find_manifests(root)
     orphans = find_orphans(root)
-    if not manifests and not orphans:
+    kept_for_a_human(root)
+    if not manifests and not orphans and not failures:
         print("No MANIFEST.yaml found. Nothing to validate.")
         return 0
     for orphan in orphans:

{napkinstack-0.18.0 → napkinstack-0.19.0}/src/napkinstack/modules.py

@@ -20,7 +20,7 @@ from pathlib import Path
 import yaml
 
 from napkinstack import assurance
-from napkinstack.project import forge, ownership
+from napkinstack.project import answer, forge, ownership
 from napkinstack.fitness.manifests import (changed_files, contract_entries, find_manifests,
                                            module_content)
 
@@ -102,7 +102,11 @@ def create(root: Path, name: str, owner: str, criticality: str, user_facing: boo
 
     codeowners = ownership(root)
     line = f"/modules/{name}/"
-    if codeowners.is_file():
+    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 "
+              f"{criticality} module.")
+    elif codeowners.is_file():
         content = codeowners.read_text(encoding="utf-8")
         if not any(existing.split()[:1] == [line] for existing in content.splitlines()):
             codeowners.write_text(content.rstrip("\n") + f"\n{line:<31}@{owner}\n", encoding="utf-8")

napkinstack-0.19.0/src/napkinstack/owners.py

@@ -0,0 +1,78 @@
+"""
+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
+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
+syntax the forge documents for the file, and the last rule that matches a path decides it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pathspec
+import yaml
+
+# What a human approves whatever the project answers: its rules, its barriers, its records, its answers.
+KEPT_FOR_A_HUMAN = ("AGENTS.md", "CONTRIBUTING.md", ".nstack/", ".copier-answers.yml", "docs/",
+                    ".pre-commit-config.yaml", ".yamllint.yaml", "SECURITY.md")
+FORGE_FOLDER = {"github": ".github/", "gitlab": ".gitlab/", "forgejo": ".gitea/", "gitea": ".gitea/"}
+NOBODY = "nstack-no-file-is-named-so"  # a path no rule names but a default owner
+
+
+def rules(text: str) -> list[tuple[pathspec.PathSpec | None, list[str]]]:
+    """Each rule of the file, in order: its pattern and its owners — none after a `#`."""
+    found = []
+    for line in text.splitlines():
+        words = line.split("#", 1)[0].split()
+        if not words:
+            continue
+        try:
+            spec = pathspec.PathSpec.from_lines("gitignore", [words[0]])
+        except (ValueError, TypeError):
+            spec = None  # a pattern the forge would refuse covers nothing
+        found.append((spec, words[1:]))
+    return found
+
+
+def owned(read: list[tuple[pathspec.PathSpec | None, list[str]]], path: str) -> bool:
+    """Whether the last rule matching the path names an owner."""
+    last = [owners for spec, owners in read if spec is not None and spec.match_file(path)]
+    return bool(last and last[-1])
+
+
+def wanted(root: Path) -> list[str]:
+    """The paths a human must approve on `approval: agent`, folders ending with `/`."""
+    from napkinstack.fitness.manifests import find_manifests
+    from napkinstack.project import forge, ownership
+
+    paths = [*KEPT_FOR_A_HUMAN, ownership(root).relative_to(root).as_posix()]
+    if forge(root) in FORGE_FOLDER:
+        paths.append(FORGE_FOLDER[forge(root)])
+    for manifest in find_manifests(root):
+        try:
+            data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
+        except (OSError, yaml.YAMLError):
+            data = {}
+        module = data.get("module") if isinstance(data, dict) else None
+        # A value the engine does not know, or a manifest it cannot read, is judged as critical.
+        if not isinstance(module, dict) or module.get("criticality") not in ("prototype", "standard"):
+            paths.append(manifest.parent.relative_to(root).as_posix() + "/")
+    return list(dict.fromkeys(paths))
+
+
+def unowned(root: Path, text: str) -> tuple[bool, list[str]]:
+    """Whether the file names a default owner, and the paths a human must approve that end on a
+    rule with none — a folder by its own name and by every file it holds."""
+    read = rules(text)
+    missing = []
+    for path in wanted(root):
+        probes = [path + NOBODY] if path.endswith("/") else [path]
+        folder = root / path
+        if path.endswith("/") and folder.is_dir():
+            probes += [file.relative_to(root).as_posix() for file in folder.rglob("*") if file.is_file()]
+        if not all(owned(read, probe) for probe in probes):
+            missing.append(path)
+    return owned(read, NOBODY), missing

{napkinstack-0.18.0 → napkinstack-0.19.0}/src/napkinstack/project.py

@@ -201,7 +201,7 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
     import copier
     from copier.errors import CopierError
 
-    from napkinstack.doctor import CHECKLIST
+    from napkinstack.doctor import CHECKLIST, unasked
 
     destination = destination.resolve()
     if destination.exists() and not destination.is_dir():
@@ -235,6 +235,7 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
     # was asked by Copier itself.
     data.setdefault("checks", "forge" if named == "github" else "attested")
     data.setdefault("hold_days", 7)  # a hold goes stale after a week without work (ADR-0007)
+    data.setdefault("approval", "human")  # a code owner approves, until the decider says otherwise (PDR-0021)
     try:
         copier.run_copy(source, destination, data=data, vcs_ref=ref, quiet=True, unsafe=False)
     except (CopierError, ValueError, OSError) as exc:
@@ -261,8 +262,9 @@ def init(destination: Path, answers: dict[str, str | None], source: str, ref: st
     if named == "github":
         print(f"  2. Create the GitHub repository {created.get('github_repo')}, push main to it, then apply "
               "these settings:")
-        for _, setting, _ in CHECKLIST:
-            print(f"     - [ ] {setting}")
+        for rule, setting, _ in CHECKLIST:
+            if not unasked(rule, created):  # G21 on `approval: agent` alone
+                print(f"     - [ ] {setting}")
         print("  3. Check the workstation and GitHub, read-only: nstack doctor (token: see .nstack/handbook/INSTALL.md)")
         return 0
     where = (f"Create the repository {created.get('repository')} at {named}, push main to it"

{napkinstack-0.18.0 → napkinstack-0.19.0}/src/napkinstack/settings.py

@@ -46,8 +46,8 @@ from napkinstack.project import ANSWERS
 
 RULESET_NAME = "nstack-checklist"
 HOLDS_RULESET = "nstack-holds"  # the holds of deliverables: never forced, never deleted (G20)
-IN_RULESET = ("G1", "G2", "G3", "G4", "G13", "G17", "G18")
-PULL_REQUEST = ("G1", "G2", "G3", "G13")
+IN_RULESET = ("G1", "G2", "G3", "G4", "G13", "G17", "G18", "G21")
+PULL_REQUEST = ("G1", "G2", "G3", "G13", "G21")
 LABEL_COLOURS = {"cross-module": "d93f0b", "over-budget": "fbca04", "out-of-cycle": "5319e7",
                  "request": "0e8a16", "bug": "d73a4a", "architecture": "1d76db", "debt": "c5def5",
                  "acceptance": "bfdadc"}
@@ -74,7 +74,7 @@ def ruleset(missing: set[str]) -> dict:
     if missing & set(PULL_REQUEST):
         rules.append({"type": "pull_request", "parameters": {
             "required_approving_review_count": 1, "require_code_owner_review": True,
-            "dismiss_stale_reviews_on_push": True, "require_last_push_approval": False,
+            "dismiss_stale_reviews_on_push": True, "require_last_push_approval": "G21" in missing,
             "required_review_thread_resolution": False}})
     if "G4" in missing:
         rules.append({"type": "required_status_checks", "parameters": {
@@ -329,7 +329,7 @@ def run(root: Path, apply: bool = False) -> int:
     if client is None:
         # G12 is not planned blind: the ruleset planned below has nobody on its bypass list, and
         # an older one that has is a step by hand, which only a read can find.
-        missing = {rule for rule, _, _ in doctor.CHECKLIST} - {"G12"}
+        missing = {rule for rule, _, _ in doctor.CHECKLIST if not doctor.unasked(rule, answers)} - {"G12"}
         print(f"Settings of {repo}: not read — no token (GH_TOKEN or GITHUB_TOKEN). The whole checklist is "
               "planned below; a call for a setting already in place changes nothing, except a ruleset's: "
               f"skip it if a ruleset named {RULESET_NAME} exists, and the G20 one if {HOLDS_RULESET} does.\n"
@@ -346,7 +346,7 @@ def run(root: Path, apply: bool = False) -> int:
                   "a token to print the whole checklist.")
             return 1
         for rule, _, _ in doctor.CHECKLIST:
-            if private and rule in doctor.PUBLIC_ONLY:
+            if private and rule in doctor.PUBLIC_ONLY or doctor.unasked(rule, answers):
                 continue
             try:
                 compliant = doctor.CHECKS[rule](client)