napkinstack 0.6.2__tar.gz → 0.7.0__tar.gz

{napkinstack-0.6.2 → napkinstack-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.6.2
+Version: 0.7.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.6.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): what the
+> **Status: v0.6.2, published** ([PyPI](https://pypi.org/project/napkinstack/)): what the
 > framework announces, it refuses — and what it cannot refuse, it says. The boundaries read the
 > contracts a module uses, a contract version someone relies on changes only with a proof that
 > runs in the base's tree, the module checks and stale approvals are enforced, a verifier is not
@@ -28,8 +28,10 @@ Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 > holding its template's words is refused, a deprecated module's consumers are named with their
 > removal date, and a contract change runs the checks of both sides — the producer and every
 > declared consumer. The diagnosis says whether anything refuses at all; a record names what
-> reached the default branch outside a pull request, and never refuses it. A first pilot
-> project, private, starts from here.
+> reached the default branch outside a pull request, and never refuses it. Since v0.6.2, each
+> version's notes are published, engine and project apart, and an update names every version it
+> crosses. A first real project, public, has run two cycles on it; **M11**, in progress, makes
+> the framework charge what a failure costs, and nothing more ([PDR-0011](docs/pdr/0011-ceremony-follows-consequence.md)).
 > 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),
@@ -37,6 +39,7 @@ Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 > [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),
 > [what is announced refuses](docs/governance/plans/2026-09-20-v0.6.0-what-is-announced-refuses.md),
+> [ceremony follows consequence](docs/governance/plans/2026-09-23-m11-ceremony-follows-consequence.md),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -62,6 +65,14 @@ flowchart LR
 The project owns its skeleton and adapts it freely. Every new version reaches it on
 demand, merged with its adaptations; the conflicts are left to the team.
 
+Five files are never merged again, because their content is the product's: the front page
+`README.md`, the security policy, the module map and the two decision indexes. `nstack init`
+writes them as a form — headings and the place of a diagram — and each is asked for when its
+moment comes, never before: the sentence at the discovery's go, the page at the charter's
+acceptance, the map at a module's first code. The foundation's manual sits one click away,
+in `.nstack/handbook/INSTALL.md`
+([PDR-0010](docs/pdr/0010-the-framework-imposes-the-form.md)).
+
 ```mermaid
 flowchart LR
     V1["Skeleton v0.1<br/>common base"]:::ref --> F{"Three-way<br/>merge"}
@@ -91,8 +102,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.5.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.5.0"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.6.2" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.6.2"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -155,8 +166,8 @@ generation; dotted: a versioned dependency.
 
 | Path | Role |
 |---|---|
-| `skeleton/` | What every project receives: kernel, playbooks, handbook, CI, hooks |
-| `copier.yml` | The questions asked at creation (a Copier template, ADR-0001) |
+| `skeleton/` | What every project receives: kernel, playbooks, handbook and its manual, CI, hooks — and five forms the project writes |
+| `copier.yml` | The questions asked at creation, and the files no update touches again (a Copier template, ADR-0001) |
 | `src/napkinstack/` | The engine, the `nstack` command |
 | `platform/` | The engine module's envelope: manifest, runbook, tests |
 | `PRODUCT.md`, `docs/governance/` | The working context for NapkinStack itself |

{napkinstack-0.6.2 → napkinstack-0.7.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.6.0, published** ([PyPI](https://pypi.org/project/napkinstack/)): what the
+> **Status: v0.6.2, published** ([PyPI](https://pypi.org/project/napkinstack/)): what the
 > framework announces, it refuses — and what it cannot refuse, it says. The boundaries read the
 > contracts a module uses, a contract version someone relies on changes only with a proof that
 > runs in the base's tree, the module checks and stale approvals are enforced, a verifier is not
@@ -13,8 +13,10 @@ Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 > holding its template's words is refused, a deprecated module's consumers are named with their
 > removal date, and a contract change runs the checks of both sides — the producer and every
 > declared consumer. The diagnosis says whether anything refuses at all; a record names what
-> reached the default branch outside a pull request, and never refuses it. A first pilot
-> project, private, starts from here.
+> reached the default branch outside a pull request, and never refuses it. Since v0.6.2, each
+> version's notes are published, engine and project apart, and an update names every version it
+> crosses. A first real project, public, has run two cycles on it; **M11**, in progress, makes
+> the framework charge what a failure costs, and nothing more ([PDR-0011](docs/pdr/0011-ceremony-follows-consequence.md)).
 > 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),
@@ -22,6 +24,7 @@ Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 > [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),
 > [what is announced refuses](docs/governance/plans/2026-09-20-v0.6.0-what-is-announced-refuses.md),
+> [ceremony follows consequence](docs/governance/plans/2026-09-23-m11-ceremony-follows-consequence.md),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -47,6 +50,14 @@ flowchart LR
 The project owns its skeleton and adapts it freely. Every new version reaches it on
 demand, merged with its adaptations; the conflicts are left to the team.
 
+Five files are never merged again, because their content is the product's: the front page
+`README.md`, the security policy, the module map and the two decision indexes. `nstack init`
+writes them as a form — headings and the place of a diagram — and each is asked for when its
+moment comes, never before: the sentence at the discovery's go, the page at the charter's
+acceptance, the map at a module's first code. The foundation's manual sits one click away,
+in `.nstack/handbook/INSTALL.md`
+([PDR-0010](docs/pdr/0010-the-framework-imposes-the-form.md)).
+
 ```mermaid
 flowchart LR
     V1["Skeleton v0.1<br/>common base"]:::ref --> F{"Three-way<br/>merge"}
@@ -76,8 +87,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.5.0" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.5.0"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.6.2" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.6.2"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -140,8 +151,8 @@ generation; dotted: a versioned dependency.
 
 | Path | Role |
 |---|---|
-| `skeleton/` | What every project receives: kernel, playbooks, handbook, CI, hooks |
-| `copier.yml` | The questions asked at creation (a Copier template, ADR-0001) |
+| `skeleton/` | What every project receives: kernel, playbooks, handbook and its manual, CI, hooks — and five forms the project writes |
+| `copier.yml` | The questions asked at creation, and the files no update touches again (a Copier template, ADR-0001) |
 | `src/napkinstack/` | The engine, the `nstack` command |
 | `platform/` | The engine module's envelope: manifest, runbook, tests |
 | `PRODUCT.md`, `docs/governance/` | The working context for NapkinStack itself |

{napkinstack-0.6.2 → napkinstack-0.7.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.6.2"
+version = "0.7.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.0/src/napkinstack/assurance.py

@@ -0,0 +1,74 @@
+"""
+The machine half of the assurance matrix (`.nstack/handbook/05-workflow.md` §7).
+
+`assurance` here is the word of DO-178C's *Design Assurance Level*, of ISO 26262, of the
+OpenSSF Baseline's "advanced high assurance", and of plain *quality assurance*: how much
+verification the cost of a failure buys. It is not `insurance`, and it is not the French
+word it is spelled like.
+
+That table is the single source of what a criticality value requires (D67). Its rows are marked
+*machine* or *owed*: the machine ones are here, the owed ones belong to a human and this module
+does not pretend to know them.
+
+Before it, one threshold lived in four places — `pull_request.SHEET_CRITICALITIES`,
+`modules.NEEDS_RUNBOOK`, `modules.NEEDS_SHEET` and a literal inside M8 — which is how a
+framework comes to describe one fact three times in its documents and spend it as one in its
+code. A rule that reads the matrix here cannot drift from the table that announces it;
+`platform/tests/test_assurance_contract.py` guards the other direction.
+
+One row of the table is deliberately absent: **e2e**. A check can read that a module
+declares an `e2e` verb; it cannot read that the verb runs end-to-end scenarios rather than
+the unit suite under another name. This repository's own `platform` module declares its
+whole oracle as `test`, so the rule would have asked it to alias one command as two — and a
+rule a one-line alias satisfies teaches the alias (P6). The row is owed to a human.
+"""
+
+from __future__ import annotations
+
+# Ascending, so that "the value below" is the previous one. M3 validates a manifest against it.
+CRITICALITIES = ("prototype", "standard", "high", "critical")
+
+# What each value requires, machine rows only:
+#   sheet            a test sheet run by a verifier who is not an author (T1)
+#   runbook          a runbook declared in the manifest and present (M8)
+#   rerun_at_head    every scenario re-run at the head; no confirmation stands in for a
+#                    re-run, which is what the top value costs (T4)
+# `"user_facing"` means: required only when the module declares a user-visible surface (M10).
+MATRIX: dict[str, dict[str, bool | str]] = {
+    "prototype": {"sheet": False, "runbook": False, "rerun_at_head": False},
+    "standard": {"sheet": "user_facing", "runbook": False, "rerun_at_head": False},
+    "high": {"sheet": True, "runbook": True, "rerun_at_head": False},
+    "critical": {"sheet": True, "runbook": True, "rerun_at_head": True},
+}
+
+
+def requires(criticality: str | None, row: str, user_facing: bool = False) -> bool:
+    """Does `criticality` require `row`? An unknown value reads as the strictest: M3 refuses it
+    where a manifest is judged, and until a reader fixes that the safe reading is the expensive
+    one — never the cheap one."""
+    rule = MATRIX.get(criticality or "", MATRIX["critical"])[row]
+    return bool(user_facing) if rule == "user_facing" else bool(rule)
+
+
+def below(criticality: str | None) -> str | None:
+    """The value one step down, or None at the bottom and for a value the engine does not know."""
+    if criticality not in CRITICALITIES:
+        return None
+    index = CRITICALITIES.index(criticality)
+    return CRITICALITIES[index - 1] if index else None
+
+
+def relief(criticality: str | None, row: str, user_facing: bool = False) -> str:
+    """What the value below would have required instead, as half a sentence, or "" when there is
+    nothing below or nothing would change.
+
+    P6 asks a refusal to name an action. On a threshold the action is not always "do the work":
+    it can be "this module is not what you declared it to be". Saying what the neighbouring
+    value costs lets a reader judge the declaration instead of only obeying it — which is the
+    decision an agent took alone when nothing told it where to stop (D70)."""
+    lower = below(criticality)
+    if lower is None or requires(lower, row, user_facing):
+        return ""
+    if MATRIX[lower][row] == "user_facing":
+        return f"at {lower} it would be required only for a module a user sees"
+    return f"at {lower} it would not be required"

{napkinstack-0.6.2 → napkinstack-0.7.0}/src/napkinstack/cli.py

@@ -6,7 +6,8 @@ import argparse
 import json
 from pathlib import Path
 
-from napkinstack import (__version__, compat, discovery, doctor, landed, modules, provenance,
+from napkinstack import assurance
+from napkinstack import (__version__, compat, discovery, doctor, landed, modules, provenance, settings,
                          pull_request, skills)
 from napkinstack.fitness import boundaries, hygiene, manifests, plan, pr_scope
 
@@ -65,7 +66,7 @@ def build_parser() -> argparse.ArgumentParser:
          lambda a: manifests.run(a.root))
     _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))
+    _add(sub, "plan", "the discovery, the charter and the cycles (C1-C8)", lambda a: plan.run(a.root))
     sk = _add(sub, "skills", "generates or checks the skills (S1-S4)",
               lambda a: skills.run(a.root, check_only=a.check))
     sk.add_argument("--check", action="store_true", help="check without writing")
@@ -73,16 +74,24 @@ def build_parser() -> argparse.ArgumentParser:
          lambda a: hygiene.run(a.root))
     _add(sub, "fitness", "manifests + boundaries + skills + plan + hygiene",
          lambda a: _fitness(a.root))
-    _add(sub, "doctor", "diagnoses the workstation and the GitHub settings, read-only (PDR-0001)",
+    _add(sub, "doctor", "diagnoses the workstation and the GitHub settings, read-only",
          lambda a: doctor.run(a.root))
+    _add(sub, "settings", "prints the calls that would bring the GitHub settings to the checklist; changes nothing",
+         lambda a: settings.run(a.root))
     nm = _add(sub, "new-module", "creates a module and its guardrails, with no imposed stack",
               lambda a: modules.create(a.root, a.name, a.owner, a.criticality, a.user_facing))
     nm.add_argument("name", help="module name, kebab-case")
     nm.add_argument("owner", help="GitHub team, organisation/team, or a user when the project has "
                                   "no organisation")
-    nm.add_argument("criticality", choices=["prototype", "standard", "high", "critical"])
+    nm.add_argument("criticality", choices=list(assurance.CRITICALITIES),
+                    help="what a failure of this module costs — prototype: nothing, it is "
+                         "thrown away and nothing depends on it · standard: real code, no "
+                         "money and no personal data · high: a day of work · critical: a "
+                         "key, an order, money, or someone's personal data. The decider "
+                         "settles it (.nstack/handbook/05-workflow.md §7)")
     nm.add_argument("--user-facing", action="store_true",
-                    help="a user sees this module: its pull requests carry a test sheet")
+                    help="a user sees this module: from standard up, its pull requests carry a "
+                         "test sheet (.nstack/handbook/05-workflow.md §7)")
     for verb, help_text in (("bootstrap", "prepares one module, or all of them (commands.bootstrap)"),
                             ("check", "format, lint, types of one module, or all (commands.check)"),
                             ("test", "tests of one module, or of all of them (commands.test)"),
@@ -105,6 +114,10 @@ def build_parser() -> argparse.ArgumentParser:
     ps = _add(sub, "pr-scope", "one PR = one module, review budget (P1-P2)",
               lambda a: pr_scope.run(a.root, a.base))
     ps.add_argument("--base", default="origin/main")
+    nc = _add(sub, "new-contract", "creates a contract — and, the first time, the module that holds them all",
+              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-K4)",
               lambda a: pull_request.run(a.root, a.base, a.body_file))
     pc.add_argument("--base", default="origin/main")
@@ -113,10 +126,10 @@ def build_parser() -> argparse.ArgumentParser:
               lambda a: landed.run(a.root, a.span, landed.from_environment(a.root)))
     ld.add_argument("--span", default="HEAD~1..HEAD",
                     help="the commits to read, BEFORE..AFTER (default: the last commit)")
-    ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent (PDR-0002)",
+    ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent",
               lambda a: discovery.run(a.root, a.idea))
     ds.add_argument("idea", type=Path, help="the idea, a .md or .txt file")
-    ini = sub.add_parser("init", help="creates a project from the skeleton (PDR-0001)")
+    ini = sub.add_parser("init", help="creates a project from the skeleton")
     ini.add_argument("destination", type=Path, help="project folder, missing or empty")
     ini.add_argument("--project-name", help="project name (asked when absent)")
     ini.add_argument("--github-repo", help="GitHub repository, organisation/name (asked when absent)")
@@ -125,13 +138,13 @@ def build_parser() -> argparse.ArgumentParser:
     ini.add_argument("--source", help="template: URL or path (default: the NapkinStack repository)")
     ini.add_argument("--ref", help="skeleton version, tag vX.Y.Z (default: the one of nstack)")
     ini.set_defaults(func=_init)
-    up = _add(sub, "update", "merges a NapkinStack version onto a branch to review (PDR-0001)",
+    up = _add(sub, "update", "merges a NapkinStack version onto a branch to review",
               _update)
     up.add_argument("--ref", help="target version, tag vX.Y.Z (default: the one of nstack)")
     return parser
 
 
-JUDGES = {"manifests", "boundaries", "plan", "skills", "hygiene", "fitness", "doctor", "pr-scope",
+JUDGES = {"manifests", "boundaries", "plan", "skills", "hygiene", "fitness", "doctor", "settings", "pr-scope",
           "pr-check", "compat", "landed"}  # the commands whose verdict depends on the framework's rules
 
 
@@ -139,4 +152,6 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     if args.command in JUDGES:
         print(provenance.judged_by(args.root), flush=True)
+        if said := plan.stage_line(args.root):
+            print(said, flush=True)
     return args.func(args)

{napkinstack-0.6.2 → napkinstack-0.7.0}/src/napkinstack/compat.py

@@ -1,6 +1,6 @@
 """
 Contract versions (D30): a merged version that someone relies on changes only with a proof
-that the change is additive (docs/os/03-contracts.md §3 and §4).
+that the change is additive (.nstack/handbook/03-contracts.md §3 and §4).
 
 Rule:
   V1  a frozen contract version changes only when the compatibility command of the module
@@ -15,7 +15,7 @@ those under provides[].path; a new version beside it changes nothing merged. A v
 provided at the head is judged wherever it now lives: moving it is no removal (D36).
 
 The command is the project's (P1: no format assumed): an OpenAPI, protobuf or JSON Schema
-comparator, named in docs/tooling-profile.md. It runs from the holding module's folder with
+comparator, named in .nstack/tooling-profile.md. It runs from the holding module's folder with
   NSTACK_CONTRACT   the contract's name                    catalog-api
   NSTACK_VERSION    the version                            v1
   NSTACK_BASE_PATH  the version as merged, extracted to a temporary folder
@@ -133,7 +133,7 @@ def run(root: Path, module: str | None, base: str) -> int:
         if holder is None:
             failures.append(f"[V1] {label} changed at '{target}', which no module holds: nothing declares "
                             "how its versions are compared.\n      Action: keep contracts under contracts/ "
-                            "(docs/os/03-contracts.md §2).")
+                            "(.nstack/handbook/03-contracts.md §2).")
             continue
         if module is not None and holder[0] != module:
             continue
@@ -151,8 +151,8 @@ def run(root: Path, module: str | None, base: str) -> int:
         if not command:
             failures.append(f"[V1] {label} changed, and no merged compatibility command proves the "
                             f"change compatible.\n      Action: declare commands.compat in {where} in a "
-                            "pull request of its own (docs/tooling-profile.md), or publish the change as "
-                            "a new version beside it (docs/os/03-contracts.md §4).")
+                            "pull request of its own (.nstack/tooling-profile.md), or publish the change as "
+                            "a new version beside it (.nstack/handbook/03-contracts.md §4).")
             continue
         with tempfile.TemporaryDirectory() as temporary:
             tree = _base_tree(root, fork, Path(temporary))
@@ -161,7 +161,7 @@ def run(root: Path, module: str | None, base: str) -> int:
                 failures.append(f"[V1] {label}: module '{name}' has no folder at the base, so its "
                                 f"compatibility command cannot be run as merged.\n      Action: "
                                 "declare the command where the module now lives, in a pull request "
-                                "of its own (docs/os/03-contracts.md §4).")
+                                "of its own (.nstack/handbook/03-contracts.md §4).")
                 continue
             env = {**os.environ, "NSTACK_CONTRACT": contract, "NSTACK_VERSION": version,
                    "NSTACK_BASE_PATH": str(tree / path), "NSTACK_HEAD_PATH": str(root / target)}
@@ -172,7 +172,7 @@ def run(root: Path, module: str | None, base: str) -> int:
                             f"did not prove the change compatible (exit {code}).\n"
                             "      Action: read the comparator's output above. If the change is "
                             "breaking, publish it as a new version beside this one and migrate its "
-                            "consumers (expand/contract, docs/os/03-contracts.md §4). If the command "
+                            "consumers (expand/contract, .nstack/handbook/03-contracts.md §4). If the command "
                             "could not run — a missing tool, no network — fix the command: V1 cannot "
                             "pass without a proof.")
         else:

{napkinstack-0.6.2 → napkinstack-0.7.0}/src/napkinstack/discovery.py

@@ -3,7 +3,7 @@ nstack discover — starts a project's discovery from an idea file (PDR-0002, ex
 
 Deterministic, no model called: the idea is kept in docs/project/inputs/, the discovery
 document is created from its template, and the instruction for the team's agent is
-printed. The conversation itself happens in the agent (playbooks/discovery.md).
+printed. The conversation itself happens in the agent (.nstack/playbooks/discovery.md).
 
 Usage :  nstack discover <idea-file> [--root ROOT]
 Output:  0 when the discovery is started, 1 otherwise.
@@ -17,7 +17,7 @@ from pathlib import Path
 from napkinstack.fitness.plan import DISCOVERY, PROJECT
 
 INPUTS = PROJECT / "inputs"
-TEMPLATE = PROJECT / "_DISCOVERY_TEMPLATE.md"
+TEMPLATE = Path(".nstack") / "forms" / "discovery.md"  # the framework's forms live in its one folder (PDR-0012)
 SUFFIXES = {".md", ".txt"}
 
 
@@ -33,7 +33,7 @@ def run(root: Path, idea: Path) -> int:
         return 1
     if (root / DISCOVERY).exists():
         print(f"FAIL [discover] {DISCOVERY} already exists: one discovery per project.\n      Action: "
-              "continue it in your agent (playbooks/discovery.md), as a new round of the same document.")
+              "continue it in your agent (.nstack/playbooks/discovery.md), as a new round of the same document.")
         return 1
     kept = root / INPUTS / idea.name
     if kept.exists() and kept.resolve() != idea.resolve():
@@ -47,7 +47,7 @@ def run(root: Path, idea: Path) -> int:
     (root / DISCOVERY).write_text(template.replace("<idea file>", source), encoding="utf-8")
     print(f"Discovery started: {source} kept, {DISCOVERY} created.")
     print("\nNext, in your agent:")
-    print(f"  Follow playbooks/discovery.md on {source}: interview me, one question at a time.")
+    print(f"  Follow .nstack/playbooks/discovery.md on {source}: interview me, one question at a time.")
     print("Then, in another session, have the document challenged (stage 5); the decider decides: "
           "go, clarify or kill.")
     return 0

{napkinstack-0.6.2 → napkinstack-0.7.0}/src/napkinstack/doctor.py

@@ -3,7 +3,7 @@ Read-only diagnosis of a project: the workstation and the GitHub settings (PDR-0
 
 Workflows inform; it is the GitHub settings that block, and they are not copied with the
 project. CHECKLIST is printed by nstack init, checked here, and repeated word for word in
-the skeleton README (a test verifies it).
+the foundation manual, skeleton/.nstack/handbook/INSTALL.md.jinja (a test verifies it).
 
 GitHub is read with a token supplied by a human (GH_TOKEN, otherwise GITHUB_TOKEN):
 fine-grained, limited to the repository, Administration: read permission. Without a token,
@@ -14,15 +14,21 @@ Rules:
       published: an unpublished framework is a gap, never compliance (PDR-0005)
   L2  git and pre-commit available
   L3  pre-commit hooks installed
-  L4  PRODUCT.md absent: that is NapkinStack's own development context (R6)
-  L5  README personalised: the presentation sentence is written
+  L4  retired (D79): it refused a file named PRODUCT.md, which a product may write. The
+      number is not reused.
+  L5  retired (PDR-0010): it reported the front page's unwritten sentence from a project's
+      first minute. The plan check asks for it at the discovery's go (C8). Not reused.
   L6  CODEOWNERS starts with a default owner: the code owner review covers every path
   L7  the template source reachable by anyone: a repository, not a path on one machine
-  G1-G13  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
-          repository, and on a private one G1-G5, G12 and G13 name the GitHub plan or option required
+  G1-G18  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
 
 Usage :  nstack doctor [--root ROOT]
-Output:  0 when everything is verified and compliant, 1 otherwise.
+Output:  0 when everything is verified and compliant; 1 when a setting is missing — a gap;
+         2 when nothing read is missing and something could not be read — not verified
+         (D77). The two are different things to whoever reads the code: one asks for a
+         change, the other for a token.
 """
 
 from __future__ import annotations
@@ -41,6 +47,7 @@ from pathlib import Path
 import yaml
 
 from napkinstack import __version__, provenance
+from napkinstack.fitness import plan
 from napkinstack.project import ANSWERS
 
 OK, GAP, UNKNOWN, NOT_APPLICABLE = "OK", "FAIL", "NOT VERIFIED", "NOT APPLICABLE"
@@ -49,7 +56,6 @@ OUT_OF_REACH = "OUT OF REACH"      # the plan forbids it: a state, not a fault (
 # all in force; the others matter and none of them stops a merge.
 BLOCKING = ("G1", "G2", "G3", "G4", "G12", "G13")
 API_VERSION = "2026-03-10"
-PLACEHOLDER = "<One sentence: what this project does.>"
 JOBS = ("Fitness functions", "PR scope and review budget", "Hooks and secrets", "Test sheet and cycle",
         "Module checks")
 THIRD_PARTY_ACTIONS = ("astral-sh/setup-uv",)  # non-GitHub actions of the skeleton workflows
@@ -60,6 +66,7 @@ REMOTE = re.compile(r"https://|ssh://|git@[^:/]+:|gh:|gl:")  # as .nstack/instal
 RULESET = "Settings → Rules → Rulesets, main branch"
 SECURITY = "Settings → Advanced Security"
 ACTIONS = "Settings → Actions → General"
+MERGES = "Settings → General → Pull Requests"
 CODEOWNERS = Path(".github") / "CODEOWNERS"
 
 CHECKLIST = [  # (rule, setting, action)
@@ -87,13 +94,25 @@ CHECKLIST = [  # (rule, setting, action)
      f"{RULESET}: remove every bypass actor"),
     ("G13", "Stale approvals dismissed when new commits are pushed",
      f"{RULESET}: dismiss stale pull request approvals when new commits are pushed"),
+    # G14 to G16 shape the merge; they never refuse one, so they are not in BLOCKING. Like G11,
+    # they need neither the Administration permission nor a paid plan (D61).
+    ("G14", "Auto-merge available: a pull request armed for it merges itself once approved and green",
+     f"{MERGES}: allow auto-merge"),
+    ("G15", "Squash the only merge method: one pull request, one commit on main",
+     f"{MERGES}: allow squash merging, and turn off merge commits and rebase merging"),
+    ("G16", "Head branch deleted on merge: a merged branch is history, not a place to work",
+     f"{MERGES}: automatically delete head branches"),
+    # G17 and G18 protect the branch itself (D78): the rules above say how a change reaches
+    # 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"),
 ]
 
 # 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"),
+PRIVATE_PLAN = dict.fromkeys(("G1", "G2", "G3", "G4", "G12", "G13", "G17", "G18"),
                              "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 "
@@ -189,6 +208,33 @@ def _no_bypass(client: GitHub) -> bool:
     return True
 
 
+MERGE_SETTINGS = ("allow_auto_merge", "allow_squash_merge", "allow_merge_commit",
+                  "allow_rebase_merge", "delete_branch_on_merge")
+
+
+def _merges(client: GitHub, *keys: str) -> dict:
+    """G14 to G16 read the repository object, which carries these fields in every answer and
+    asks for no Administration permission (D61). Absent means a degraded read, never a setting
+    that is off: the difference between "not verified" and "missing" is the whole point of this
+    command (PDR-0005). Each rule names the fields it reads, and one of them absent is enough."""
+    repo = client.get("")
+    absent = [key for key in keys or MERGE_SETTINGS if key not in repo]
+    if absent:
+        raise NotVerified(f"{', '.join(absent)} not visible in the repository's own object")
+    return repo
+
+
+def _squash_only(client: GitHub) -> bool:
+    """G15: squash alone, so that a workstream reaches main as one commit. A merge commit puts
+    the branch's commits on main beside a merge of its own; a rebase puts them there without
+    one. Measured on two repositories before the rule existed: 22 branches for 23 merged pull
+    requests, and four commits on main for two workstreams (D61)."""
+    repo = _merges(client, "allow_squash_merge", "allow_merge_commit", "allow_rebase_merge")
+    return (repo.get("allow_squash_merge") is True
+            and repo.get("allow_merge_commit") is False
+            and repo.get("allow_rebase_merge") is False)
+
+
 CHECKS: dict[str, Callable[[GitHub], bool]] = {
     "G1": lambda c: _rule(c, "pull_request") is not None,
     "G2": lambda c: _parameters(c, "pull_request").get("required_approving_review_count", 0) >= 1,
@@ -205,6 +251,11 @@ CHECKS: dict[str, Callable[[GitHub], bool]] = {
     "G11": lambda c: all(c.get(f"/labels/{label}", missing=True) is not None for label in LABELS),
     "G12": _no_bypass,
     "G13": lambda c: _parameters(c, "pull_request").get("dismiss_stale_reviews_on_push") is True,
+    "G14": lambda c: _merges(c, "allow_auto_merge").get("allow_auto_merge") is True,
+    "G15": _squash_only,
+    "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,
 }
 
 
@@ -218,7 +269,7 @@ def _default_owner(root: Path) -> tuple[str, str]:
     if rules and rules[0][0] == "*" and len(rules[0]) > 1:
         return OK, ""
     return GAP, (f"The first rule of {CODEOWNERS} is not a default owner.\nAction: make `*  @<owner>` "
-                 "its first rule: the code owner review then covers every path (ADR-0004).")
+                 "its first rule: the code owner review then covers every path (.nstack/handbook/07-governance.md §7).")
 
 
 def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
@@ -230,12 +281,13 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
     _, origin = provenance.engine()
     if not PUBLISHED.fullmatch(commit):
         l1 = (GAP, f"The project is pinned to an unpublished framework ({commit or 'unknown'}): its "
-                   "verdicts come from rules nobody has published (PDR-0005).\nAction: once the change it "
+                   "verdicts come from rules nobody has published.\nAction: once the change it "
                    "waits for is released, nstack update --ref vX.Y.Z.")
     elif origin is not None:
-        l1 = (GAP, f"The nstack running is unpublished ({origin}) (PDR-0005).\nAction: {install}")
+        l1 = (GAP, f"The nstack running is unpublished ({origin}).\nAction: {install}")
     elif project != __version__:
-        l1 = (GAP, f"nstack {__version__} installed, project on {project} (PDR-0001 R3).\nAction: {install}")
+        l1 = (GAP, f"nstack {__version__} installed, project on {project}: the engine and the project "
+                   f"move together.\nAction: {install}")
     else:
         l1 = (OK, "")
     results.append(("L1", "nstack at the project version", *l1))
@@ -256,24 +308,13 @@ 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))
 
-    product = (root / "PRODUCT.md").exists()
-    results.append(("L4", "PRODUCT.md absent", GAP if product else OK,
-                    "PRODUCT.md describes the development of NapkinStack itself (PDR-0001 R6).\n"
-                    "Action: delete it." if product else ""))
-
-    readme = root / "README.md"
-    untouched = readme.is_file() and PLACEHOLDER in readme.read_text(encoding="utf-8", errors="replace")
-    results.append(("L5", "README personalised", GAP if untouched else OK,
-                    f'README.md still contains "{PLACEHOLDER}".\n'
-                    "Action: write the sentence that presents the project." if untouched else ""))
-
     results.append(("L6", "CODEOWNERS starts with a default owner", *_default_owner(root)))
 
     source = str(answers.get("_src_path") or "")
     local = not REMOTE.match(source)
     results.append(("L7", "Template source reachable by anyone", GAP if local else OK,
                     f"The project was generated from '{source}', a path on one machine: nobody else can "
-                    "update it (PDR-0005).\nAction: nstack update, from the published source." if local else ""))
+                    "update it.\nAction: nstack update, from the published source." if local else ""))
     return results
 
 
@@ -333,6 +374,15 @@ def run(root: Path) -> int:
     for result in results:
         _display(*result)
 
+    if plan.stage(root) == plan.UNFRAMED:
+        # Said here and nowhere else, once: every other run names the stage in one line and
+        # leaves it there. A stage is not a gap, and nothing below counts it as one.
+        print("\nProject\n  UNFRAMED       no accepted charter — a stage, not a gap\n"
+              "                 Framing buys an appetite, an end date, a circuit breaker and a decider.\n"
+              "                 It is worth its price when there is something to bound: several people,\n"
+              "                 a deadline, a decider who is not the one typing.\n"
+              "                 To start: follow .nstack/playbooks/framing.md with your agent.")
+
     token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
     print(f"\nGitHub: {answers.get('github_repo')}")
     if token:
@@ -373,4 +423,6 @@ def run(root: Path) -> int:
         return 0
     print(f"\nnstack doctor: {gaps} gap(s), {unknown} not verified{suffix}.\nWorkflows inform; "
           "it is the GitHub settings that block, and they are not copied with the project.")
-    return 1
+    if gaps:
+        print("What would close the gaps, as calls to run yourself: nstack settings")
+    return 1 if gaps else 2