napkinstack 0.2.0__tar.gz → 0.3.0__tar.gz

{napkinstack-0.2.0 → napkinstack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.2.0
+Version: 0.3.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,9 +20,10 @@ 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.1.0, the first published version** ([PyPI](https://pypi.org/project/napkinstack/)).
-> A first pilot project, private, puts it to the test before the rest. Tracking:
-> [roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
+> **Status: v0.2.0, published** ([PyPI](https://pypi.org/project/napkinstack/)), English
+> throughout. A first pilot project, private, starts from it and puts it to the test before
+> the rest. 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),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -84,10 +85,14 @@ the commit of this repository
 |---|---|
 | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, GitHub checklist |
 | `nstack doctor` | Checks the workstation and the GitHub settings, read-only |
-| `nstack new-module <name> <organisation>/<team> <criticality>` | Creates a module, with no imposed stack |
+| `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
-| `nstack fitness` | Manifests, boundaries between modules, skills |
+| `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 |
+| `nstack fitness` | Manifests, boundaries between modules, skills, plan |
 | `nstack pr-scope` | One PR = one module, review budget |
+| `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared |
+| `nstack pr-check` | The test sheet and the cycle, read from the pull request description |
 | `nstack skills` | Exposes the playbooks as skills for the agent |
 | `nstack update` | Lays the new version on a branch to review |
 

{napkinstack-0.2.0 → napkinstack-0.3.0}/README.md

@@ -5,9 +5,10 @@ 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.1.0, the first published version** ([PyPI](https://pypi.org/project/napkinstack/)).
-> A first pilot project, private, puts it to the test before the rest. Tracking:
-> [roadmap](docs/governance/plans/2026-09-15-engine-v0.1.0.md),
+> **Status: v0.2.0, published** ([PyPI](https://pypi.org/project/napkinstack/)), English
+> throughout. A first pilot project, private, starts from it and puts it to the test before
+> the rest. 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),
 > [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
 ## A project's journey
@@ -69,10 +70,14 @@ the commit of this repository
 |---|---|
 | `nstack init <folder>` | Creates the project: skeleton, git repository, initial commit, GitHub checklist |
 | `nstack doctor` | Checks the workstation and the GitHub settings, read-only |
-| `nstack new-module <name> <organisation>/<team> <criticality>` | Creates a module, with no imposed stack |
+| `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
 | `nstack check`, `test`, `bootstrap` `[module]`; `nstack run <module>` | Run the commands declared in the module's manifest |
-| `nstack fitness` | Manifests, boundaries between modules, skills |
+| `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 |
+| `nstack fitness` | Manifests, boundaries between modules, skills, plan |
 | `nstack pr-scope` | One PR = one module, review budget |
+| `nstack e2e [module]` | Runs the module's end-to-end scenarios, when declared |
+| `nstack pr-check` | The test sheet and the cycle, read from the pull request description |
 | `nstack skills` | Exposes the playbooks as skills for the agent |
 | `nstack update` | Lays the new version on a branch to review |
 

{napkinstack-0.2.0 → napkinstack-0.3.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.2.0"
+version = "0.3.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.2.0 → napkinstack-0.3.0}/src/napkinstack/cli.py

@@ -7,8 +7,8 @@ import os
 import subprocess
 from pathlib import Path
 
-from napkinstack import __version__, doctor, modules, skills
-from napkinstack.fitness import boundaries, manifests
+from napkinstack import __version__, discovery, doctor, modules, pull_request, skills
+from napkinstack.fitness import boundaries, manifests, plan
 
 PACKAGE = Path(__file__).resolve().parent
 
@@ -26,7 +26,7 @@ def _script(relative: str, *args: str, root: Path) -> int:
 
 
 def _fitness(root: Path) -> int:
-    results = [manifests.run(root), boundaries.run(root), skills.run(root, check_only=True)]
+    results = [manifests.run(root), boundaries.run(root), skills.run(root, check_only=True), plan.run(root)]
     return 1 if any(results) else 0
 
 
@@ -61,21 +61,26 @@ def build_parser() -> argparse.ArgumentParser:
          lambda a: manifests.run(a.root))
     _add(sub, "boundaries", "declared graph against real graph (B1-B5)",
          lambda a: boundaries.run(a.root))
+    _add(sub, "plan", "the discovery, the charter and the cycles (C1-C7)", 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")
-    _add(sub, "fitness", "manifests + boundaries + skills",
+    _add(sub, "fitness", "manifests + boundaries + skills + plan",
          lambda a: _fitness(a.root))
     _add(sub, "doctor", "diagnoses the workstation and the GitHub settings, read-only (PDR-0001)",
          lambda a: doctor.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))
+              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")
+    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("--user-facing", action="store_true",
+                    help="a user sees this module: its pull requests carry a test sheet")
     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)")):
+                            ("test", "tests of one module, or of all of them (commands.test)"),
+                            ("e2e", "end-to-end scenarios of one module, or of all (commands.e2e)")):
         vb = _add(sub, verb, help_text, lambda a, v=verb: modules.run_verb(a.root, v, a.module))
         vb.add_argument("module", nargs="?", help="module name (default: all)")
     rn = _add(sub, "run", "starts a module locally (commands.run)",
@@ -84,12 +89,19 @@ def build_parser() -> argparse.ArgumentParser:
     ps = _add(sub, "pr-scope", "one PR = one module, review budget (P1-P2)",
               lambda a: _script("fitness/pr_scope.sh", a.base, root=a.root))
     ps.add_argument("--base", default="origin/main")
+    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")
+    pc.add_argument("--body-file", type=Path, help="the description, when PR_BODY is not set")
+    ds = _add(sub, "discover", "starts a discovery from an idea file, for the team's agent (PDR-0002)",
+              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.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)")
-    ini.add_argument("--owner-team", help="GitHub team owning the foundation, organisation/team "
-                                          "(asked when absent)")
+    ini.add_argument("--owner-team", help="owner of the foundation: organisation/team, or a user "
+                                          "when the project has no organisation (asked when absent)")
     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)

napkinstack-0.3.0/src/napkinstack/discovery.py

@@ -0,0 +1,53 @@
+"""
+nstack discover — starts a project's discovery from an idea file (PDR-0002, extension).
+
+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).
+
+Usage :  nstack discover <idea-file> [--root ROOT]
+Output:  0 when the discovery is started, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from napkinstack.fitness.plan import DISCOVERY, PROJECT
+
+INPUTS = PROJECT / "inputs"
+TEMPLATE = PROJECT / "_DISCOVERY_TEMPLATE.md"
+SUFFIXES = {".md", ".txt"}
+
+
+def run(root: Path, idea: Path) -> int:
+    if not (root / TEMPLATE).is_file():
+        print(f"FAIL [discover] {TEMPLATE} not found in {root}: not a project created by nstack init, "
+              "or one older than the discovery.\n      Action: run it at the project root, or update "
+              "the project (nstack update).")
+        return 1
+    if not idea.is_file() or idea.suffix.lower() not in SUFFIXES:
+        print(f"FAIL [discover] {idea}: a Markdown or text file expected.\n      Action: write the idea "
+              "in a .md or .txt file — a few lines are enough.")
+        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.")
+        return 1
+    kept = root / INPUTS / idea.name
+    if kept.exists() and kept.resolve() != idea.resolve():
+        print(f"FAIL [discover] {INPUTS / idea.name} already exists.\n      Action: rename the idea file.")
+        return 1
+    kept.parent.mkdir(parents=True, exist_ok=True)
+    if kept.resolve() != idea.resolve():
+        shutil.copyfile(idea, kept)
+    source = (INPUTS / idea.name).as_posix()
+    template = (root / TEMPLATE).read_text(encoding="utf-8")
+    (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("Then, in another session, have the document challenged (stage 5); the decider decides: "
+          "go, clarify or kill.")
+    return 0

{napkinstack-0.2.0 → napkinstack-0.3.0}/src/napkinstack/doctor.py

@@ -15,8 +15,9 @@ Rules:
   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
-  G1-G11  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
-          repository, and on a private one G1-G5 name the GitHub plan or option required
+  L6  CODEOWNERS starts with a default owner: the code owner review covers every path
+  G1-G12  the GitHub settings of CHECKLIST; G6 is not applicable outside a public
+          repository, and on a private one G1-G5 and G12 name the GitHub plan or option required
 
 Usage :  nstack doctor [--root ROOT]
 Output:  0 when everything is verified and compliant, 1 otherwise.
@@ -43,14 +44,15 @@ from napkinstack.project import ANSWERS
 OK, GAP, UNKNOWN, NOT_APPLICABLE = "OK", "FAIL", "NOT VERIFIED", "NOT APPLICABLE"
 API_VERSION = "2026-03-10"
 PLACEHOLDER = "<One sentence: what this project does.>"
-JOBS = ("Fitness functions", "PR scope and review budget", "Hooks and secrets")
+JOBS = ("Fitness functions", "PR scope and review budget", "Hooks and secrets", "Test sheet and cycle")
 THIRD_PARTY_ACTIONS = ("astral-sh/setup-uv",)  # non-GitHub actions of the skeleton workflows
-LABELS = ("cross-module", "over-budget")
+LABELS = ("cross-module", "over-budget", "out-of-cycle")
 PUBLISHED = re.compile(r"v\d+(\.\d+)*((a|b|rc)\d+)?(\.post\d+)?(\.dev\d+)?")
 
 RULESET = "Settings → Rules → Rulesets, main branch"
 SECURITY = "Settings → Advanced Security"
 ACTIONS = "Settings → Actions → General"
+CODEOWNERS = Path(".github") / "CODEOWNERS"
 
 CHECKLIST = [  # (rule, setting, action)
     ("G1", "Pull request required: no direct push to main",
@@ -70,15 +72,17 @@ CHECKLIST = [  # (rule, setting, action)
      f"{ACTIONS}: require approval for all external contributors"),
     ("G10", "Workflow token read-only; Actions neither creates nor approves pull requests",
      f"{ACTIONS}: workflow permissions read-only, with no pull request creation or approval"),
-    ("G11", "Labels " + " and ".join(f"`{label}`" for label in LABELS),
-     "Issues → Labels: create " + " and ".join(LABELS)),
+    ("G11", "Labels " + ", ".join(f"`{label}`" for label in LABELS[:-1]) + f" and `{LABELS[-1]}`",
+     "Issues → Labels: create " + ", ".join(LABELS[:-1]) + f" and {LABELS[-1]}"),
+    ("G12", "Bypass list empty: nobody merges around the rules, administrators included",
+     f"{RULESET}: remove every bypass actor"),
 ]
 
 # 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"),
+PRIVATE_PLAN = dict.fromkeys(("G1", "G2", "G3", "G4", "G12"),
                              "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 "
@@ -155,6 +159,20 @@ def _workflows(client: GitHub) -> bool:
             and permissions.get("can_approve_pull_request_reviews") is False)
 
 
+def _no_bypass(client: GitHub) -> bool:
+    """G12: every ruleset applying to main has an empty bypass list (ADR-0004)."""
+    rulesets = {rule["ruleset_id"] for rule in client.get("/rules/branches/main") if rule.get("ruleset_id")}
+    if not rulesets:
+        return False
+    for ruleset in sorted(rulesets):
+        actors = client.get(f"/rulesets/{ruleset}?includes_parents=true").get("bypass_actors")
+        if actors is None:
+            raise NotVerified("bypass list not visible: the token lacks the Administration: read permission")
+        if actors:
+            return False
+    return True
+
+
 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,
@@ -169,9 +187,23 @@ CHECKS: dict[str, Callable[[GitHub], bool]] = {
         "approval_policy") == "all_external_contributors",
     "G10": _workflows,
     "G11": lambda c: all(c.get(f"/labels/{label}", missing=True) is not None for label in LABELS),
+    "G12": _no_bypass,
 }
 
 
+def _default_owner(root: Path) -> tuple[str, str]:
+    """L6: `*` first, so that the code owner review covers every path (ADR-0004)."""
+    path = root / CODEOWNERS
+    if not path.is_file():
+        return GAP, f"{CODEOWNERS} missing.\nAction: create it, 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 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).")
+
+
 def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
     commit = str(answers.get("_commit") or "")
     project = commit.removeprefix("v")
@@ -212,6 +244,8 @@ def _workstation(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
     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)))
     return results
 
 

{napkinstack-0.2.0 → napkinstack-0.3.0}/src/napkinstack/fitness/manifests.py

@@ -15,6 +15,7 @@ Rules:
   M7  standard verbs declared (check / test at least)
   M8  runbook required when criticality >= high
   M9  complete file envelope (AGENTS.md, README.md, tests/)
+  M10 user_facing declared: true when a user sees the module (docs/os/05-workflow.md §7)
 
 Usage :  nstack manifests [--root ROOT]
 Output:  0 if everything passes, 1 otherwise. Every failure explains the rule broken.
@@ -164,6 +165,11 @@ def check_manifest(path: Path, today: datetime.date) -> None:
     if not (path.parent / "tests").is_dir() and criticality != "prototype":
         fail(rel, "M9", "tests/ folder missing")
 
+    # M10 - a user-visible surface declared: it decides the test sheet (docs/os/05-workflow.md §7)
+    if not isinstance(mod.get("user_facing"), bool):
+        fail(rel, "M10", "module.user_facing must be true or false: does a user see this module? "
+                         "true requires a test sheet on its pull requests (docs/os/05-workflow.md §7)")
+
 
 def run(root: Path) -> int:
     failures.clear()

napkinstack-0.3.0/src/napkinstack/fitness/plan.py

@@ -0,0 +1,221 @@
+"""
+Fitness function 4 — The project's charter and cycles (PDR-0002).
+
+A project is framed by a charter and bounded by cycles, written in docs/project/. Their
+front matter, a YAML block between two --- lines at the top of the file, is what the
+checks read; the prose below it is for humans and agents.
+
+Rules:
+  C1  front matter readable: a YAML mapping at the top of the file
+  C2  charter: status proposed or accepted, a decider, at least one success criterion
+  C3  cycle: a goal, a known status, appetite_weeks, start and end, end = start + appetite
+  C4  deliverables: ids D1, D2… unique, a title, a known state, acceptance criteria once ready
+  C5  at most one accepted cycle, and only under an accepted charter
+  C6  a closed or stopped cycle records its outcome and the date it ended
+  C7  discovery: a known decision, its decider and date once decided, a challenger for a go;
+      a charter follows a go
+
+Templates, whose file name starts with "_", are not checked.
+
+Usage :  nstack plan [--root ROOT]
+Output:  0 when the charter and the cycles are valid, or absent; 1 otherwise.
+A root without docs/project/, such as the NapkinStack repository itself, is out of scope.
+"""
+
+from __future__ import annotations
+
+import datetime
+import re
+from pathlib import Path
+
+import yaml
+
+PROJECT = Path("docs") / "project"
+CHARTER = PROJECT / "charter.md"
+CYCLES = PROJECT / "cycles"
+DISCOVERY = PROJECT / "discovery.md"
+DECISIONS = {"proposed", "go", "clarify", "kill"}
+CHARTER_STATUSES = {"proposed", "accepted"}
+CYCLE_STATUSES = {"proposed", "accepted", "closed", "stopped"}
+DELIVERABLE_STATES = {"proposed", "ready", "in-progress", "accepted", "deferred", "dropped"}
+WITHOUT_CRITERIA = {"proposed", "deferred", "dropped"}  # acceptance criteria not required yet
+OUTCOMES = {"closed": {"completed", "shipped"}, "stopped": {"reframed", "stopped"}}
+DELIVERABLE_ID = re.compile(r"D[1-9][0-9]*")
+FRONT_MATTER = re.compile(r"\A---\n(.*?)\n---\n", re.S)
+
+
+def read_front_matter(path: Path) -> tuple[dict | None, str]:
+    """The front matter as a mapping, or None and the reason it cannot be read (C1)."""
+    match = FRONT_MATTER.match(path.read_text(encoding="utf-8"))
+    if not match:
+        return None, "no front matter: the file must start with a YAML block between two --- lines"
+    try:
+        data = yaml.safe_load(match[1])
+    except yaml.YAMLError as exc:
+        return None, f"front matter unreadable: {exc}"
+    if not isinstance(data, dict):
+        return None, "front matter must be a YAML mapping"
+    return data, ""
+
+
+def as_date(value) -> datetime.date | None:
+    if isinstance(value, datetime.datetime):
+        return value.date()
+    if isinstance(value, datetime.date):
+        return value
+    try:
+        return datetime.date.fromisoformat(str(value))
+    except ValueError:
+        return None
+
+
+def cycle_files(root: Path) -> list[Path]:
+    folder = root / CYCLES
+    return sorted(p for p in folder.glob("*.md") if not p.name.startswith("_")) if folder.is_dir() else []
+
+
+def charter_accepted(root: Path) -> bool:
+    path = root / CHARTER
+    data = read_front_matter(path)[0] if path.is_file() else None
+    return bool(data) and data.get("status") == "accepted"
+
+
+def accepted_cycle(root: Path) -> tuple[Path, dict] | None:
+    """The cycle in progress: the one accepted cycle, when its front matter is readable."""
+    for path in cycle_files(root):
+        data = read_front_matter(path)[0]
+        if data and data.get("status") == "accepted":
+            return path, data
+    return None
+
+
+def _check_charter(path: Path, fail) -> bool:
+    data, reason = read_front_matter(path)
+    if data is None:
+        fail("C1", path, reason)
+        return False
+    if data.get("status") not in CHARTER_STATUSES:
+        fail("C2", path, f"status '{data.get('status')}': expected one of {sorted(CHARTER_STATUSES)}")
+    if not str(data.get("decider") or "").strip():
+        fail("C2", path, "decider missing: the GitHub handle of the human who validates the charter "
+                         "and the cycles, and decides at the circuit breaker")
+    criteria = data.get("success_criteria")
+    if not isinstance(criteria, list) or not [c for c in criteria if str(c or "").strip()]:
+        fail("C2", path, "success_criteria: at least one, they say when the project itself ends")
+    return data.get("status") == "accepted"
+
+
+def _check_deliverables(path: Path, deliverables, fail) -> None:
+    if not isinstance(deliverables, list) or not deliverables:
+        fail("C4", path, "deliverables: a finite, non-empty list — what the cycle delivers")
+        return
+    seen: set[str] = set()
+    for index, item in enumerate(deliverables, start=1):
+        if not isinstance(item, dict):
+            fail("C4", path, f"deliverable no. {index}: expected a mapping (id, title, state, acceptance)")
+            continue
+        ident = str(item.get("id") or "")
+        where = ident or f"no. {index}"
+        if not DELIVERABLE_ID.fullmatch(ident):
+            fail("C4", path, f"deliverable {where}: id expected as D1, D2…")
+        elif ident in seen:
+            fail("C4", path, f"deliverable {ident}: id used twice")
+        seen.add(ident)
+        if not str(item.get("title") or "").strip():
+            fail("C4", path, f"deliverable {where}: title missing")
+        state = item.get("state")
+        if state not in DELIVERABLE_STATES:
+            fail("C4", path, f"deliverable {where}: state '{state}', expected one of {sorted(DELIVERABLE_STATES)}")
+        criteria = item.get("acceptance")
+        filled = isinstance(criteria, list) and [c for c in criteria if str(c or "").strip()]
+        if state in DELIVERABLE_STATES - WITHOUT_CRITERIA and not filled:
+            fail("C4", path, f"deliverable {where}: state '{state}' requires acceptance criteria — "
+                             "the definition of ready, and the source of its test sheet (PDR-0003)")
+
+
+def _check_cycle(path: Path, fail) -> str | None:
+    data, reason = read_front_matter(path)
+    if data is None:
+        fail("C1", path, reason)
+        return None
+    if not str(data.get("goal") or "").strip():
+        fail("C3", path, "goal missing: one sentence")
+    status = data.get("status")
+    if status not in CYCLE_STATUSES:
+        fail("C3", path, f"status '{status}': expected one of {sorted(CYCLE_STATUSES)}")
+    weeks = data.get("appetite_weeks")
+    if isinstance(weeks, bool) or not isinstance(weeks, int) or weeks < 1:
+        fail("C3", path, "appetite_weeks: a whole number of weeks, decided rather than estimated")
+        weeks = None
+    start, end = as_date(data.get("start")), as_date(data.get("end"))
+    if start is None or end is None:
+        fail("C3", path, "start and end: dates, YYYY-MM-DD")
+    elif weeks is not None and end != start + datetime.timedelta(weeks=weeks):
+        fail("C3", path, f"end {end}: the appetite sets it, start + {weeks} week(s) = "
+                         f"{start + datetime.timedelta(weeks=weeks)}")
+    _check_deliverables(path, data.get("deliverables"), fail)
+    if status in OUTCOMES:
+        if data.get("outcome") not in OUTCOMES[status]:
+            fail("C6", path, f"a {status} cycle records its outcome: one of {sorted(OUTCOMES[status])}")
+        if as_date(data.get("ended_on")) is None:
+            fail("C6", path, f"a {status} cycle records ended_on, the date it ended")
+    return status if isinstance(status, str) else None
+
+
+def _check_discovery(path: Path, fail) -> str | None:
+    data, reason = read_front_matter(path)
+    if data is None:
+        fail("C1", path, reason)
+        return None
+    decision = data.get("decision")
+    if decision not in DECISIONS:
+        fail("C7", path, f"decision '{decision}': expected one of {sorted(DECISIONS)}")
+    elif decision != "proposed":
+        if not str(data.get("decider") or "").strip():
+            fail("C7", path, f"a decision ({decision}) names its decider")
+        if as_date(data.get("decided_on")) is None:
+            fail("C7", path, f"a decision ({decision}) records decided_on, YYYY-MM-DD")
+        if decision == "go" and not str(data.get("challenger") or "").strip():
+            fail("C7", path, "a go names its challenger: another session, or a human, challenged the "
+                             "document first (playbooks/discovery.md, stage 5)")
+    return decision if isinstance(decision, str) else None
+
+
+def run(root: Path) -> int:
+    failures: list[str] = []
+
+    def fail(rule: str, path: Path, message: str) -> None:
+        failures.append(f"[{rule}] {path.relative_to(root)}\n      {message}")
+
+    if not (root / PROJECT).is_dir():
+        print(f"Plan: not applicable, no {PROJECT}/ in {root}.")
+        return 0
+    charter = root / CHARTER
+    discovery = root / DISCOVERY
+    cycles = cycle_files(root)
+    if not charter.is_file() and not cycles and not discovery.is_file():
+        print(f"Plan: no charter and no cycle in {PROJECT}/ — the project is not framed yet "
+              "(playbooks/framing.md).")
+        return 0
+    decision = _check_discovery(discovery, fail) if discovery.is_file() else None
+    accepted_charter = _check_charter(charter, fail) if charter.is_file() else False
+    if accepted_charter and discovery.is_file() and decision != "go":
+        fail("C7", charter, f"the charter is accepted, but the discovery's decision is '{decision}': "
+                            "a charter follows a go (docs/project/discovery.md)")
+    accepted = [path for path in cycles if _check_cycle(path, fail) == "accepted"]
+    if len(accepted) > 1:
+        names = ", ".join(path.name for path in accepted)
+        fail("C5", root / CYCLES, f"{len(accepted)} accepted cycles ({names}): one cycle at a time — "
+                                  "close or stop the others")
+    if accepted and not accepted_charter:
+        fail("C5", accepted[0], "an accepted cycle requires an accepted charter "
+                                f"({CHARTER}, status: accepted)")
+
+    print(f"Plan: charter {'present' if charter.is_file() else 'absent'}, {len(cycles)} cycle(s).")
+    for failure in failures:
+        print(f"  FAIL {failure}")
+    if failures:
+        print(f"\n{len(failures)} violation(s). See docs/project/README.md and playbooks/framing.md.")
+        return 1
+    print("Plan: compliant.")
+    return 0

{napkinstack-0.2.0 → napkinstack-0.3.0}/src/napkinstack/modules.py

@@ -21,8 +21,9 @@ from napkinstack.fitness.manifests import find_manifests
 
 TEMPLATE = Path(__file__).resolve().parent / "templates" / "module"
 NAME = re.compile(r"[a-z][a-z0-9-]*")
-TEAM = re.compile(r"[A-Za-z0-9-]+/[A-Za-z0-9._-]+")  # same rule as copier.yml
-OPTIONAL = {"bootstrap"}  # absent: nothing to prepare
+OWNER = re.compile(  # same rule as copier.yml: organisation/team, or a GitHub user
+    r"[A-Za-z0-9-]+/[A-Za-z0-9._-]+|(?=[A-Za-z0-9-]{1,39}$)[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*")
+OPTIONAL = {"bootstrap": "nothing to prepare", "e2e": "no end-to-end scenario"}  # undeclared: skipped
 NEEDS_RUNBOOK = {"high", "critical"}  # M8, kept in step with CRITICALITIES
 
 RUNBOOK = """# Runbook - {name}
@@ -46,13 +47,14 @@ RUNBOOK = """# Runbook - {name}
 """
 
 
-def create(root: Path, name: str, owner: str, criticality: str) -> int:
+def create(root: Path, name: str, owner: str, criticality: str, user_facing: bool = False) -> int:
     if not NAME.fullmatch(name):
         print(f"FAIL [new-module] invalid name '{name}': kebab-case expected, for example billing.")
         return 1
-    if not TEAM.fullmatch(owner):
+    if not OWNER.fullmatch(owner):
         print(f"FAIL [new-module] invalid owner '{owner}': a GitHub team, organisation/team, "
-              "for example acme/billing (CODEOWNERS, docs/os/07-governance.md §7).")
+              "or a user when the project has no organisation, for example acme/billing "
+              "(CODEOWNERS, docs/os/07-governance.md §7).")
         return 1
     folder = root / "modules" / name
     if folder.exists():
@@ -67,6 +69,11 @@ def create(root: Path, name: str, owner: str, criticality: str) -> int:
             text = text.replace(marker, value)
         file_.write_text(text, encoding="utf-8")
 
+    if user_facing:
+        manifest = folder / "MANIFEST.yaml"
+        manifest.write_text(re.sub(r"^( *)user_facing: false", r"\1user_facing: true",
+                                   manifest.read_text(encoding="utf-8"), flags=re.M), encoding="utf-8")
+
     runbook = criticality in NEEDS_RUNBOOK
     if runbook:
         (folder / "docs").mkdir(exist_ok=True)
@@ -86,10 +93,10 @@ def create(root: Path, name: str, owner: str, criticality: str) -> int:
         print(f"WARNING: .github/CODEOWNERS missing; add \"{line} @{owner}\" to it.")
 
     print(f"Module created: modules/{name} (owner {owner}, criticality {criticality})"
-          + (", runbook to fill in" if runbook else "") + ".")
+          + (", user-facing" if user_facing else "") + (", runbook to fill in" if runbook else "") + ".")
     print("\nNext steps:")
     print("  1. Creation ADR in docs/adr/: capability, boundary, alternatives")
-    print("  2. MANIFEST.yaml: responsibility in ONE sentence, then the stack's check and test commands")
+    print("  2. MANIFEST.yaml: responsibility in ONE sentence, user_facing, then the stack's check and test commands")
     print(f"  3. modules/{name}/AGENTS.md: what is specific to the module, never the kernel")
     print(f"  4. nstack fitness, then nstack check {name} and nstack test {name}")
     return 0
@@ -120,7 +127,7 @@ def run_verb(root: Path, verb: str, name: str | None) -> int:
         command = commands.get(verb)
         if not command:
             if verb in OPTIONAL:
-                print(f"-> {target}: {verb} not declared, nothing to prepare.")
+                print(f"-> {target}: {verb} not declared, {OPTIONAL[verb]}.")
                 continue
             print(f"FAIL [{verb}] module '{target}': commands.{verb} not declared in {manifest}.\n"
                   "      Action: declare the module stack's command there (docs/os/09-platform.md §2).")

napkinstack-0.3.0/src/napkinstack/pull_request.py

@@ -0,0 +1,242 @@
+"""
+Pull request rules read from its description: the test sheet (PDR-0003) and the cycle
+(PDR-0002).
+
+Rules:
+  T1  a test sheet when the pull request touches a user-facing module, or one of
+      criticality high or critical
+  T2  a verifier named, and every scenario row filled in: id, given · when · then, a kind
+      (automated, explored, human only — reason), a result (passed, failed, not verified)
+  T3  no scenario passed without its evidence and the commit it was verified on
+  T4  evidence produced on the pull request's head commit: the others are to run again
+  T5  no scenario failed; none left not verified, unless it is human only
+  K1  delivery work needs an accepted charter and an accepted cycle
+  K2  delivery work stops once the cycle is past its end date: the circuit breaker
+  K3  delivery work names a ready or in-progress deliverable of the cycle
+  K4  the out-of-cycle label carries its justification
+
+Delivery work: a pull request that changes a module — a folder holding a MANIFEST.yaml.
+The out-of-cycle label lifts K1 to K3, visibly and countably (docs/os/10-measurement.md).
+
+Usage :  nstack pr-check [--root ROOT] [--base BASE] [--body-file FILE]
+In CI :  PR_BODY, PR_LABELS and PR_HEAD_SHA come from the pull_request event.
+Output:  0 when every applicable rule passes, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+import re
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+import yaml
+
+from napkinstack.fitness import plan
+from napkinstack.fitness.manifests import find_manifests
+
+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)
+SHEET_CRITICALITIES = {"high", "critical"}
+COLUMNS = ("#", "given · when · then", "kind", "result", "evidence", "commit")
+KINDS = {"automated", "explored"}
+RESULTS = {"passed", "failed", "not verified"}
+SECTION = re.compile(r"^##[ \t]+Test sheet[ \t]*$", re.I | re.M)
+NEXT_SECTION = re.compile(r"^#{1,2}[ \t]", re.M)
+VERIFIER = re.compile(r"^Verifier:[ \t]*(.*)$", re.I | re.M)
+HUMAN_ONLY = re.compile(r"human only[ \t]*[—–-][ \t]*(\S.*)", re.I)
+PLACEHOLDER = re.compile(r"<[^<>]*>")
+EMPTY = {"", "—", "-"}
+SHA = re.compile(r"[0-9a-f]{7,40}")
+
+Fail = Callable[[str, str], None]
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+
+
+def touched_modules(root: Path, files: list[str]) -> dict[str, dict]:
+    """Folder, relative to the root, to manifest, for every module the files change."""
+    touched = {}
+    for manifest in find_manifests(root):
+        folder = manifest.parent.relative_to(root).as_posix()
+        if any(path.startswith(f"{folder}/") for path in files):
+            try:
+                data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
+            except yaml.YAMLError:
+                data = {}
+            touched[folder] = data if isinstance(data, dict) else {}
+    return touched
+
+
+def sheet_reason(folder: str, manifest: dict) -> str | None:
+    """Why a module requires a test sheet (T1), or None."""
+    module = manifest.get("module") if isinstance(manifest.get("module"), dict) else {}
+    if module.get("user_facing") is True:
+        return f"{folder} (user-facing)"
+    if module.get("criticality") in SHEET_CRITICALITIES:
+        return f"{folder} (criticality {module['criticality']})"
+    return None
+
+
+def _cells(line: str) -> list[str]:
+    inner = line.strip().removeprefix("|").removesuffix("|")
+    return [cell.strip().replace("\\|", "|") for cell in re.split(r"(?<!\\)\|", inner)]
+
+
+def read_sheet(body: str) -> tuple[str, list[str], list[dict[str, str]]]:
+    """(verifier, header, filled rows) of the "Test sheet" section; empty when absent."""
+    match = SECTION.search(body)
+    if not match:
+        return "", [], []
+    section = body[match.end():]
+    if following := NEXT_SECTION.search(section):
+        section = section[:following.start()]
+    found = VERIFIER.search(section)
+    verifier = found[1].strip() if found else ""
+    verifier = "" if PLACEHOLDER.fullmatch(verifier) else verifier
+    lines = [line for line in section.splitlines() if line.strip().startswith("|")]
+    if len(lines) < 2:
+        return verifier, [], []
+    header = [" ".join(cell.lower().split()) for cell in _cells(lines[0])]
+    rows = []
+    for line in lines[2:]:
+        values = _cells(line)
+        if all(value in EMPTY or PLACEHOLDER.fullmatch(value) for value in values[1:]):
+            continue  # the template's example row
+        rows.append(dict(zip(header, values)))
+    return verifier, header, rows
+
+
+def _result(cell: str) -> str:
+    return re.split(r"[ \t]+[—–-][ \t]+", cell.replace("*", "").strip(), maxsplit=1)[0].lower()
+
+
+def check_sheet(body: str, head: str, reasons: list[str], fail: Fail) -> list[str]:
+    """T1 to T5; returns the human-only scenarios, listed apart for the approver."""
+    verifier, header, rows = read_sheet(body)
+    if reasons and not rows:
+        fail("T1", f"Test sheet missing: this pull request touches {', '.join(reasons)}.\n"
+                   "      Action: fill in the \"Test sheet\" section of the description — scenarios "
+                   "from the acceptance criteria, run by a verifier who is not the author "
+                   "(docs/os/05-workflow.md §7).")
+        return []
+    if not rows:
+        return []
+    missing = [column for column in COLUMNS if column not in header]
+    if missing:
+        fail("T2", f"Test sheet: columns missing: {', '.join(missing)}.\n"
+                   f"      Expected: | {' | '.join(COLUMNS)} |")
+        return []
+    if not verifier:
+        fail("T2", "Test sheet: no verifier named.\n      Action: \"Verifier: <agent session "
+                   "or @human>\", someone other than the author of the change.")
+    human_only, rerun = [], []
+    for row in rows:
+        ident = row["#"] or "?"
+        kind = row["kind"]
+        reason = HUMAN_ONLY.fullmatch(kind)
+        result = _result(row["result"])
+        if row["given · when · then"] in EMPTY or PLACEHOLDER.fullmatch(row["given · when · then"]):
+            fail("T2", f"scenario {ident}: given · when · then missing")
+        if kind.lower() not in KINDS and not reason:
+            fail("T2", f"scenario {ident}: kind '{kind}', expected automated, explored, "
+                       "or human only — <reason>")
+        if result not in RESULTS:
+            fail("T2", f"scenario {ident}: result '{row['result']}', expected passed, failed or "
+                       "not verified")
+            continue
+        commit = row["commit"].strip().strip("`").lower()
+        if result == "passed" and (row["evidence"] in EMPTY or not SHA.fullmatch(commit)):
+            fail("T3", f"scenario {ident}: passed without evidence and the commit verified.\n"
+                       "      Action: link the screenshot, video, trace or log, and give the commit.")
+        elif result in {"passed", "failed"} and SHA.fullmatch(commit) and not head.startswith(commit):
+            rerun.append(ident)
+        if result == "failed":
+            fail("T5", f"scenario {ident}: failed.\n      Action: fix the change, or have the decider "
+                       "change the expected result, visibly in the sheet's history.")
+        elif result == "not verified" and reason:
+            human_only.append(f"{ident} — {reason[1]}")
+        elif result == "not verified":
+            fail("T5", f"scenario {ident}: not verified.\n      Action: run it, or mark it "
+                       "human only — <reason>.")
+    if rerun:
+        fail("T4", f"scenarios verified on another commit than the head {head[:7]}: "
+                   f"{', '.join(rerun)}.\n      Action: run them again on the head commit.")
+    return human_only
+
+
+def check_cycle(root: Path, body: str, labels: set[str], today: datetime.date, fail: Fail) -> None:
+    """K1 to K4, for delivery work."""
+    if LABEL in labels:
+        if not JUSTIFICATION.search(body):
+            fail("K4", f"label {LABEL} without its justification.\n      Action: add "
+                       "\"Out of cycle: <reason>\" to the description — an incident, a production defect.")
+        return
+    cycle = plan.accepted_cycle(root)
+    if not plan.charter_accepted(root) or cycle is None:
+        fail("K1", "the project is not framed: no accepted charter and cycle in docs/project/.\n"
+                   "      Action: frame it with your agent (playbooks/framing.md), or add the "
+                   f"{LABEL} label with a justification.")
+        return
+    path, data = cycle
+    end = plan.as_date(data.get("end"))
+    if end is not None and today > end:
+        fail("K2", f"circuit breaker: {path.name} ended on {end}, with no automatic extension.\n"
+                   "      Action: the decider chooses — ship what is accepted (status: closed), "
+                   "frame a new cycle with a new appetite, or stop the project (status: stopped).")
+        return
+    match = DELIVERABLE.search(body)
+    states = {str(item.get("id")): item.get("state") for item in data.get("deliverables") or []
+              if isinstance(item, dict)}
+    if not match:
+        fail("K3", f"no deliverable named.\n      Action: \"Deliverable: D<n>\" in the description, "
+                   f"a deliverable of {path.name}.")
+    elif match[1] not in states:
+        fail("K3", f"deliverable {match[1]} is not in {path.name}.\n      Action: name one of "
+                   f"{', '.join(states) or 'its deliverables'}, or re-frame the cycle with the decider.")
+    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).")
+
+
+def run(root: Path, base: str, body_file: Path | None = None) -> int:
+    if body_file is not None:
+        body = body_file.read_text(encoding="utf-8")
+    elif "PR_BODY" in os.environ:
+        body = os.environ["PR_BODY"]
+    else:
+        print("Pull request description not provided (PR_BODY or --body-file): not checked.")
+        return 0
+    if _git(root, "rev-parse", "--verify", "--quiet", base).returncode:
+        print(f"Base '{base}' not found — check skipped.")
+        return 0
+    files = _git(root, "diff", "--name-only", f"{base}...HEAD").stdout.split()
+    head = (os.environ.get("PR_HEAD_SHA") or _git(root, "rev-parse", "HEAD").stdout).strip().lower()
+    modules = touched_modules(root, files)
+    labels = {label.strip() for label in os.environ.get("PR_LABELS", "").split(",") if label.strip()}
+
+    failures: list[str] = []
+
+    def fail(rule: str, message: str) -> None:
+        failures.append(f"[{rule}] {message}")
+
+    reasons = [reason for folder, data in modules.items() if (reason := sheet_reason(folder, data))]
+    human_only = check_sheet(body, head, reasons, fail)
+    if modules:
+        check_cycle(root, body, labels, datetime.date.today(), fail)
+
+    print(f"Modules touched : {len(modules)}" + "".join(f"\n  - {folder}" for folder in modules))
+    print(f"Test sheet      : {'required' if reasons else 'not required'}")
+    for scenario in human_only:
+        print(f"  For the approver, human only: {scenario}")
+    for failure in failures:
+        print(f"FAIL {failure}")
+    if failures:
+        return 1
+    print("Pull request rules: compliant.")
+    return 0

{napkinstack-0.2.0 → napkinstack-0.3.0}/src/napkinstack/templates/module/MANIFEST.yaml

@@ -9,7 +9,7 @@ module:
   responsibility: >
     TODO - describe this module's business capability in one sentence.
 
-  owner: "{{OWNER}}"          # a GitHub TEAM, organisation/team, never an individual
+  owner: "{{OWNER}}"          # a GitHub team, organisation/team; a user only without an organisation
   contact: "@{{OWNER}}"
 
   # proposed | active | maintenance | deprecated | retired   (docs/os/02-modules.md §6)
@@ -18,6 +18,10 @@ module:
   # prototype | standard | high | critical              (docs/os/07-governance.md §6)
   criticality: "{{CRITICALITY}}"
 
+  # Does a user see this module? true requires a test sheet on its pull requests
+  # (docs/os/05-workflow.md §7).
+  user_facing: false
+
   # The module's name in the code, when it differs from the folder (package, namespace).
   # Used by boundary detection.
   # code_name: {{MODULE_NAME}}
@@ -63,6 +67,7 @@ commands:
   test: "echo 'commands.test to be declared in MANIFEST.yaml' >&2; exit 1"    # NEVER starts another module
   # bootstrap:                   # optional: make the module usable from a fresh clone
   # run:                         # optional: local start, with doubles for the dependencies
+  # e2e:                         # optional: end-to-end scenarios; evidence written to .evidence/
 
 # Review budget. Inherited from the project when absent (docs/os/05-workflow.md §4).
 review_budget: