napkinstack 0.1.0__tar.gz → 0.3.0__tar.gz

napkinstack-0.3.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: napkinstack
+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
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: copier==9.18.2
+Requires-Dist: pre-commit==4.6.2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/NapkinStack/engineering-os
+Project-URL: Source, https://github.com/NapkinStack/engineering-os
+Project-URL: Issues, https://github.com/NapkinStack/engineering-os/issues
+Description-Content-Type: text/markdown
+
+# NapkinStack
+
+An engineering framework for several teams and their agents working in one repository:
+modules, contracts, guardrails in CI. On the Django or Rails model, one command creates
+the project, which then receives new versions on demand; no application stack is imposed.
+Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
+
+> **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
+
+```mermaid
+flowchart LR
+    I["Install<br/>uv tool install"]:::cmd --> N["nstack init"]:::cmd
+    N --> G["Publish on GitHub<br/>apply the checklist"]:::human
+    G --> D["nstack doctor<br/>read-only"]:::cmd
+    D --> M["nstack new-module"]:::cmd
+    M --> W["Work in pull requests<br/>the team and its agent"]:::human
+    W --> U["nstack update<br/>merged branch"]:::cmd
+    U --> P["PR reviewed<br/>validated by CI"]:::human
+    P -->|"next version"| U
+
+    classDef cmd fill:#1f2937,color:#fff
+    classDef human fill:#065f46,color:#fff
+```
+
+**Legend** — grey: a NapkinStack command · green: the team's action. Decision:
+[PDR-0001](docs/pdr/0001-create-a-project-and-receive-updates.md).
+
+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.
+
+```mermaid
+flowchart LR
+    V1["Skeleton v0.1<br/>common base"]:::ref --> F{"Three-way<br/>merge"}
+    V2["Skeleton v0.2<br/>NapkinStack fixes"]:::ns --> F
+    PR["Project<br/>the team's adaptations"]:::team --> F
+    F -->|"different lines"| B["Update branch<br/>fixes + adaptations"]:::ok
+    F -->|"same line changed"| X["Conflict marked<br/>commit refused"]:::ko
+
+    classDef ref fill:#374151,color:#fff
+    classDef ns fill:#1e3a8a,color:#fff
+    classDef team fill:#065f46,color:#fff
+    classDef ok fill:#065f46,color:#fff
+    classDef ko fill:#7c2d12,color:#fff
+```
+
+**Legend** — grey: the version the project came from · blue: the new version · green: the
+team's work and the accepted result · red: a conflict left to the team.
+
+## Install
+
+```bash
+uv tool install napkinstack --with-executables-from pre-commit   # prerequisites: uv and git
+nstack init my-project
+```
+
+Each project then pins its version and changes it through `nstack update`. Every published
+version carries a provenance attestation, visible on PyPI, tying it to the workflow and
+the commit of this repository
+([ADR-0002](docs/adr/0002-distribute-napkinstack-on-pypi.md)).
+
+## The commands
+
+| Command | Role |
+|---|---|
+| `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> <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 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 |
+
+**Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
+or on a private one under the Team or Pro plan; on a private repository on the Free plan
+CI informs without blocking
+([a clarification of PDR-0001](docs/pdr/0001-create-a-project-and-receive-updates.md)).
+
+**AI**: NapkinStack embeds none. The team's agent (Claude Code, Codex, Copilot…) reads the
+kernel and the playbooks, runs the commands, and CI accepts or refuses its proposals
+exactly as it would any other contributor's.
+
+## This repository
+
+```mermaid
+flowchart LR
+    S["skeleton/<br/>the project skeleton"]:::shipped -->|"copier.yml"| P["A team's project"]:::project
+    E["src/napkinstack/<br/>the nstack engine"]:::shipped -.->|"pinned version"| P
+    A["PRODUCT.md · docs/governance/<br/>platform/ · this repository's CI"]:::internal
+
+    classDef shipped fill:#1e3a8a,color:#fff
+    classDef project fill:#065f46,color:#fff
+    classDef internal fill:#374151,color:#fff
+```
+
+**Legend** — blue: shipped to projects · green: a generated project, which owns its
+skeleton · grey: developing NapkinStack itself, never copied (PDR-0001 R6). Solid line:
+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) |
+| `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 |
+| `docs/adr/`, `docs/pdr/` | NapkinStack's decisions |
+
+## Developing NapkinStack
+
+```bash
+uv sync                               # prerequisite: uv
+uv run pre-commit install
+uv run nstack fitness                 # this repository's guardrails
+uv run bash platform/tests/run.sh     # the oracle: every guardrail proves it can fail
+uv run nstack init /tmp/trial --source . --ref HEAD   # a trial project from the working tree
+uv run nstack doctor --root /tmp/trial                # workstation and GitHub settings, read-only
+```
+
+Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md), after [`PRODUCT.md`](PRODUCT.md).
+
+Licence: [MIT](LICENSE).

napkinstack-0.3.0/README.md

@@ -0,0 +1,132 @@
+# NapkinStack
+
+An engineering framework for several teams and their agents working in one repository:
+modules, contracts, guardrails in CI. On the Django or Rails model, one command creates
+the project, which then receives new versions on demand; no application stack is imposed.
+Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
+
+> **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
+
+```mermaid
+flowchart LR
+    I["Install<br/>uv tool install"]:::cmd --> N["nstack init"]:::cmd
+    N --> G["Publish on GitHub<br/>apply the checklist"]:::human
+    G --> D["nstack doctor<br/>read-only"]:::cmd
+    D --> M["nstack new-module"]:::cmd
+    M --> W["Work in pull requests<br/>the team and its agent"]:::human
+    W --> U["nstack update<br/>merged branch"]:::cmd
+    U --> P["PR reviewed<br/>validated by CI"]:::human
+    P -->|"next version"| U
+
+    classDef cmd fill:#1f2937,color:#fff
+    classDef human fill:#065f46,color:#fff
+```
+
+**Legend** — grey: a NapkinStack command · green: the team's action. Decision:
+[PDR-0001](docs/pdr/0001-create-a-project-and-receive-updates.md).
+
+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.
+
+```mermaid
+flowchart LR
+    V1["Skeleton v0.1<br/>common base"]:::ref --> F{"Three-way<br/>merge"}
+    V2["Skeleton v0.2<br/>NapkinStack fixes"]:::ns --> F
+    PR["Project<br/>the team's adaptations"]:::team --> F
+    F -->|"different lines"| B["Update branch<br/>fixes + adaptations"]:::ok
+    F -->|"same line changed"| X["Conflict marked<br/>commit refused"]:::ko
+
+    classDef ref fill:#374151,color:#fff
+    classDef ns fill:#1e3a8a,color:#fff
+    classDef team fill:#065f46,color:#fff
+    classDef ok fill:#065f46,color:#fff
+    classDef ko fill:#7c2d12,color:#fff
+```
+
+**Legend** — grey: the version the project came from · blue: the new version · green: the
+team's work and the accepted result · red: a conflict left to the team.
+
+## Install
+
+```bash
+uv tool install napkinstack --with-executables-from pre-commit   # prerequisites: uv and git
+nstack init my-project
+```
+
+Each project then pins its version and changes it through `nstack update`. Every published
+version carries a provenance attestation, visible on PyPI, tying it to the workflow and
+the commit of this repository
+([ADR-0002](docs/adr/0002-distribute-napkinstack-on-pypi.md)).
+
+## The commands
+
+| Command | Role |
+|---|---|
+| `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> <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 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 |
+
+**Prerequisites**: uv and git. The guardrails really block on a public GitHub repository,
+or on a private one under the Team or Pro plan; on a private repository on the Free plan
+CI informs without blocking
+([a clarification of PDR-0001](docs/pdr/0001-create-a-project-and-receive-updates.md)).
+
+**AI**: NapkinStack embeds none. The team's agent (Claude Code, Codex, Copilot…) reads the
+kernel and the playbooks, runs the commands, and CI accepts or refuses its proposals
+exactly as it would any other contributor's.
+
+## This repository
+
+```mermaid
+flowchart LR
+    S["skeleton/<br/>the project skeleton"]:::shipped -->|"copier.yml"| P["A team's project"]:::project
+    E["src/napkinstack/<br/>the nstack engine"]:::shipped -.->|"pinned version"| P
+    A["PRODUCT.md · docs/governance/<br/>platform/ · this repository's CI"]:::internal
+
+    classDef shipped fill:#1e3a8a,color:#fff
+    classDef project fill:#065f46,color:#fff
+    classDef internal fill:#374151,color:#fff
+```
+
+**Legend** — blue: shipped to projects · green: a generated project, which owns its
+skeleton · grey: developing NapkinStack itself, never copied (PDR-0001 R6). Solid line:
+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) |
+| `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 |
+| `docs/adr/`, `docs/pdr/` | NapkinStack's decisions |
+
+## Developing NapkinStack
+
+```bash
+uv sync                               # prerequisite: uv
+uv run pre-commit install
+uv run nstack fitness                 # this repository's guardrails
+uv run bash platform/tests/run.sh     # the oracle: every guardrail proves it can fail
+uv run nstack init /tmp/trial --source . --ref HEAD   # a trial project from the working tree
+uv run nstack doctor --root /tmp/trial                # workstation and GitHub settings, read-only
+```
+
+Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md), after [`PRODUCT.md`](PRODUCT.md).
+
+Licence: [MIT](LICENSE).

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

@@ -1,7 +1,7 @@
 [project]
 name = "napkinstack"
-version = "0.1.0"
-description = "Framework de travail pour faire travailler plusieurs équipes et leurs agents sur un même dépôt : modules, contrats, garde-fous en CI."
+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"
 license-files = ["LICENSE"]

{napkinstack-0.1.0 → napkinstack-0.3.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "napkinstack"
-version = "0.1.0"
-description = "Framework de travail pour faire travailler plusieurs équipes et leurs agents sur un même dépôt : modules, contrats, garde-fous en CI."
+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"
 license-files = ["LICENSE"]

napkinstack-0.3.0/src/napkinstack/__init__.py

@@ -0,0 +1,5 @@
+"""NapkinStack - engine: fitness functions, skills and module scaffolding."""
+
+from importlib.metadata import version
+
+__version__ = version("napkinstack")

napkinstack-0.3.0/src/napkinstack/cli.py

@@ -0,0 +1,116 @@
+"""Single entry point `nstack` (workstream C1, PDR-0001)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+from pathlib import Path
+
+from napkinstack import __version__, discovery, doctor, modules, pull_request, skills
+from napkinstack.fitness import boundaries, manifests, plan
+
+PACKAGE = Path(__file__).resolve().parent
+
+
+def _root(value: str) -> Path:
+    root = Path(value).resolve()
+    if not root.is_dir():
+        raise argparse.ArgumentTypeError(f"root not found: {value}")
+    return root
+
+
+def _script(relative: str, *args: str, root: Path) -> int:
+    env = {**os.environ, "NSTACK_ROOT": str(root)}
+    return subprocess.run(["bash", str(PACKAGE / relative), *args], cwd=root, env=env).returncode
+
+
+def _fitness(root: Path) -> int:
+    results = [manifests.run(root), boundaries.run(root), skills.run(root, check_only=True), plan.run(root)]
+    return 1 if any(results) else 0
+
+
+def _add(sub, name: str, help_: str, func) -> argparse.ArgumentParser:
+    parser = sub.add_parser(name, help=help_)
+    parser.add_argument("--root", type=_root, default=Path.cwd(),
+                        help="project root (default: current folder)")
+    parser.set_defaults(func=func)
+    return parser
+
+
+def _init(args: argparse.Namespace) -> int:
+    from napkinstack import project  # Copier is only loaded for init and update
+
+    answers = {"project_name": args.project_name, "github_repo": args.github_repo,
+               "owner_team": args.owner_team}
+    return project.init(args.destination, answers, args.source or project.SOURCE,
+                        args.ref or project.default_ref())
+
+
+def _update(args: argparse.Namespace) -> int:
+    from napkinstack import project
+
+    return project.update(args.root, args.ref or project.default_ref())
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nstack", description="NapkinStack engine.")
+    parser.add_argument("--version", action="version", version=f"nstack {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="command")
+    _add(sub, "manifests", "manifests, lifecycles, deprecations (M1-M9)",
+         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 + 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, 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("--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)"),
+                            ("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)",
+              lambda a: modules.run_verb(a.root, "run", a.module))
+    rn.add_argument("module")
+    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="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)
+    up = _add(sub, "update", "merges a NapkinStack version onto a branch to review (PDR-0001)",
+              _update)
+    up.add_argument("--ref", help="target version, tag vX.Y.Z (default: the one of nstack)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)

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