napkinstack 0.6.2__tar.gz → 0.7.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.6.2
+Version: 0.7.1
 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,24 +20,9 @@ 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
-> 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
-> an author, and every verdict names the framework that gave it. Since v0.6.0, a document still
-> 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.
-> 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),
-> [every barrier refuses](docs/governance/plans/2026-09-19-v0.4.0-every-barrier-refuses.md),
-> [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),
-> [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
+> **Status: v0.7.1, 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).
 
 ## A project's journey
 
@@ -62,6 +47,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 +84,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.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.7.1" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.1"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -113,11 +106,13 @@ Each project then pins its version and changes it through `nstack update`.
 |---|---|
 | `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 settings` | Prints the calls that would bring the GitHub settings to the checklist; changes nothing |
 | `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
+| `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 |
-| `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene |
+| `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 |
@@ -155,8 +150,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.1}/README.md

@@ -5,24 +5,9 @@ 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
-> 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
-> an author, and every verdict names the framework that gave it. Since v0.6.0, a document still
-> 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.
-> 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),
-> [every barrier refuses](docs/governance/plans/2026-09-19-v0.4.0-every-barrier-refuses.md),
-> [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),
-> [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
+> **Status: v0.7.1, 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).
 
 ## A project's journey
 
@@ -47,6 +32,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 +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.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.7.1" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.7.1"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a
@@ -98,11 +91,13 @@ Each project then pins its version and changes it through `nstack update`.
 |---|---|
 | `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 settings` | Prints the calls that would bring the GitHub settings to the checklist; changes nothing |
 | `nstack new-module <name> <owner> <criticality>` | Creates a module, with no imposed stack |
+| `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 |
-| `nstack fitness` | Manifests, boundaries between modules, skills, plan, hygiene |
+| `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 |
@@ -140,8 +135,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.1}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.6.2"
+version = "0.7.1"
 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.1/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.1}/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.1}/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.1}/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