diff --git a/.copier-answers.yml b/.copier-answers.yml index 752633f..3cd5e80 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,6 +1,6 @@ # The project creation answers and the NapkinStack version (_commit). # Managed by Copier: changed by nstack update, never by hand. -_commit: v0.3.1 +_commit: v0.4.0 _src_path: https://github.com/NapkinStack/engineering-os.git github_repo: NapkinStack/tool-library owner_team: NapkinStack/maintainers diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a16abfb..6689431 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -58,7 +58,8 @@ other: - [ ] No contract affected - [ ] Contract consumed — the version is declared in the manifest -- [ ] Contract changed, **additive** — contract tests green +- [ ] Contract changed, **additive** — contract tests green, and `nstack compat` proving it + once the version is consumed or stable - [ ] Contract changed, **breaking** — expand/contract step no. <1|2|3|4>, ADR linked, removal date set @@ -95,7 +96,7 @@ other: > not the author (`playbooks/verification.md`). Kind: automated · explored · human only — > reason. Result: passed · failed — what was observed · not verified. -Verifier: +Verifier: <@handle, or session and the agent session's identifier> | # | Given · when · then | Kind | Result | Evidence | Commit | |---|---|---|---|---|---| diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 4d8599a..f2a79ac 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -35,11 +35,9 @@ jobs: - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 - name: NapkinStack, the project version - run: | - VERSION=$(yq '._commit' .copier-answers.yml) - uv tool install "napkinstack==${VERSION#v}" --with-executables-from pre-commit + run: bash .nstack/install-engine.sh - - name: Manifests, boundaries, skills + - name: Manifests, boundaries, skills, plan, hygiene run: nstack fitness --root . scope: @@ -56,9 +54,7 @@ jobs: - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 - name: NapkinStack, the project version - run: | - VERSION=$(yq '._commit' .copier-answers.yml) - uv tool install "napkinstack==${VERSION#v}" --with-executables-from pre-commit + run: bash .nstack/install-engine.sh - name: One PR = one module env: @@ -83,9 +79,7 @@ jobs: key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml', '.copier-answers.yml') }} - name: NapkinStack, the project version - run: | - VERSION=$(yq '._commit' .copier-answers.yml) - uv tool install "napkinstack==${VERSION#v}" --with-executables-from pre-commit + run: bash .nstack/install-engine.sh # The same configuration as the local hooks. The "gitleaks" hook only scans the # staged changes, empty in CI: the next step covers the secrets. diff --git a/.github/workflows/module-checks.yml b/.github/workflows/module-checks.yml index 75af797..6b45c01 100644 --- a/.github/workflows/module-checks.yml +++ b/.github/workflows/module-checks.yml @@ -1,10 +1,14 @@ name: Modules # Runs the standard verbs on the touched modules only: nstack reads their commands -# from the module's MANIFEST.yaml, assuming no stack (P1). +# from the module's MANIFEST.yaml, assuming no stack (P1). A module is a folder holding a +# MANIFEST.yaml, contracts/ included: nstack lists them, the workflow defines nothing. # The level of validation is proportionate to the criticality declared in the MANIFEST # (docs/os/07-governance.md §6). # +# `Module checks` is the required check: a matrix job carries each module's name, which no +# ruleset can require in advance, so this job fails whenever one of them failed. +# # Module names come from the paths the pull request changed: they are never inserted # into a script, only read from an environment variable. @@ -18,35 +22,45 @@ permissions: jobs: discover: - name: Touched modules + name: Changed modules runs-on: ubuntu-latest outputs: modules: ${{ steps.list.outputs.modules }} any: ${{ steps.list.outputs.any }} + base: ${{ steps.list.outputs.base }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 persist-credentials: false + - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 + + - name: NapkinStack, the project version + run: bash .nstack/install-engine.sh + - id: list env: BASE: ${{ github.event.pull_request.base.sha || github.event.before }} run: | - if ! git rev-parse --verify "$BASE" >/dev/null 2>&1; then + if ! git rev-parse --verify --quiet "$BASE^{commit}" >/dev/null; then + if [ "$GITHUB_EVENT_NAME" = pull_request ]; then + echo "::error::Base $BASE of the pull request not found: its modules cannot be listed." \ + "Action: run the jobs again; the checkout fetches the whole history." + exit 1 + fi + # The first push of a branch has no previous commit: every file is new. BASE=$(git rev-list --max-parents=0 HEAD | tail -1) fi - MODS=$(git diff --name-only "$BASE"...HEAD \ - | grep -E '^modules/[^/]+/' \ - | cut -d/ -f2 | sort -u | jq -R . | jq -sc .) - [ "$MODS" = "" ] && MODS='[]' + MODS=$(nstack modules --root . --changed-since "$BASE" --json) echo "modules=$MODS" >> "$GITHUB_OUTPUT" + echo "base=$BASE" >> "$GITHUB_OUTPUT" if [ "$MODS" = '[]' ]; then echo "any=false" >> "$GITHUB_OUTPUT"; else echo "any=true" >> "$GITHUB_OUTPUT"; fi - echo "Touched modules: $MODS" + echo "Modules with a file changed: $MODS" validate: - name: ${{ matrix.module }} + name: ${{ matrix.module.name }} needs: discover if: needs.discover.outputs.any == 'true' runs-on: ubuntu-latest @@ -55,26 +69,26 @@ jobs: matrix: module: ${{ fromJson(needs.discover.outputs.modules) }} env: - MODULE: ${{ matrix.module }} + MODULE: ${{ matrix.module.name }} + FOLDER: ${{ matrix.module.folder }} + BASE: ${{ needs.discover.outputs.base }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + fetch-depth: 0 persist-credentials: false - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 - name: NapkinStack, the project version - run: | - VERSION=$(yq '._commit' .copier-answers.yml) - uv tool install "napkinstack==${VERSION#v}" --with-executables-from pre-commit + run: bash .nstack/install-engine.sh - name: Declared criticality id: crit run: | - LEVEL=$(grep -E '^\s*criticality:' "modules/$MODULE/MANIFEST.yaml" \ - | head -1 | awk '{print $2}') - echo "level=${LEVEL:-standard}" >> "$GITHUB_OUTPUT" - echo "Criticality: ${LEVEL:-standard}" + LEVEL=$(yq '.module.criticality // "standard"' "$FOLDER/MANIFEST.yaml") + echo "level=$LEVEL" >> "$GITHUB_OUTPUT" + echo "Criticality: $LEVEL" - name: bootstrap run: nstack bootstrap "$MODULE" @@ -86,6 +100,11 @@ jobs: - name: test run: nstack test "$MODULE" + # A contract version someone relies on changes only with the merged proof (V1, + # docs/os/03-contracts.md §4). + - name: compat + run: nstack compat "$MODULE" --base "$BASE" + # Levels high and critical — not wired up yet (D9) - name: Integration tests if: steps.crit.outputs.level == 'high' || steps.crit.outputs.level == 'critical' @@ -101,8 +120,22 @@ jobs: if: always() uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: - name: evidence-${{ matrix.module }} - path: modules/${{ matrix.module }}/.evidence/ + name: evidence-${{ matrix.module.name }} + path: ${{ matrix.module.folder }}/.evidence/ include-hidden-files: true if-no-files-found: ignore retention-days: 30 + + checks: + name: Module checks + needs: [discover, validate] + if: always() + runs-on: ubuntu-latest + steps: + - name: Every touched module passed + env: + DISCOVERED: ${{ needs.discover.result }} + VALIDATED: ${{ needs.validate.result }} + run: | + echo "Changed modules: $DISCOVERED. Their checks: $VALIDATED." + [ "$DISCOVERED" = success ] && { [ "$VALIDATED" = success ] || [ "$VALIDATED" = skipped ]; } diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 8bc8d26..4605cee 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -26,14 +26,13 @@ jobs: - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 - name: NapkinStack, the project version - run: | - VERSION=$(yq '._commit' .copier-answers.yml) - uv tool install "napkinstack==${VERSION#v}" --with-executables-from pre-commit + run: bash .nstack/install-engine.sh - name: Test sheet and cycle env: PR_BODY: ${{ github.event.pull_request.body }} PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }} PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }} + PR_AUTHOR: ${{ github.event.pull_request.user.login }} BASE_REF: ${{ github.base_ref }} run: nstack pr-check --root . --base "origin/$BASE_REF" diff --git a/.nstack/install-engine.sh b/.nstack/install-engine.sh new file mode 100755 index 0000000..5f7f506 --- /dev/null +++ b/.nstack/install-engine.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +# Installs the NapkinStack engine this project records, for CI (PDR-0005). +# +# A published version (_commit: vX.Y.Z) comes from PyPI, the only published channel +# (ADR-0002). Anything else comes from the framework's repository at that commit, and is +# announced: nstack then says, on every run that judges, that its rules are unpublished. +# A ref that cannot be fetched fails here; no published version is ever used in its place. +set -euo pipefail + +VERSION=$(yq '._commit' .copier-answers.yml) +if [[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + exec uv tool install "napkinstack==${VERSION#v}" --with-executables-from pre-commit +fi + +SOURCE=$(yq '._src_path' .copier-answers.yml) +case "$SOURCE" in # Copier's remote forms, as nstack doctor L7 reads them + https://*|ssh://*) ;; + gh:*) SOURCE="https://github.com/${SOURCE#gh:}" ;; + gl:*) SOURCE="https://gitlab.com/${SOURCE#gl:}" ;; + git@*:*) HOST=${SOURCE#git@}; SOURCE="ssh://git@${HOST%%:*}/${HOST#*:}" ;; + *) echo "FAIL [nstack] framework source '$SOURCE' is a path on one machine: CI cannot fetch it." + echo " Action: nstack update from the framework's repository (PDR-0005)." + exit 1 ;; +esac +REF=${VERSION##*-g} # Copier records an unpublished commit as git describe: vX.Y.Z-N-g +echo "::warning::UNPUBLISHED NapkinStack: ${SOURCE}@${REF} judges this run (PDR-0005)" +uv tool install "napkinstack @ git+${SOURCE}@${REF}" --with-executables-from pre-commit || { + echo "FAIL [nstack] framework ref '$REF' not found at $SOURCE: no published version is used in its place." + echo " Action: pin an existing commit with nstack update --ref, or a published vX.Y.Z (PDR-0005)." + exit 1 +} diff --git a/AGENTS.md b/AGENTS.md index c059070..655bd45 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,9 @@ write, the **challenger**; to verify a change you did not write, the **verifier* loads its playbook (§4). You never verify, challenge or approve your own work. **Identity.** You work under your own GitHub identity, never with a human's credentials, -and you never approve a pull request (`docs/os/07-governance.md` §7). +and you never approve a pull request (`docs/os/07-governance.md` §7). Every commit you make +carries the trailer `Agent-Session: `; as a verifier, you +sign the sheet `Verifier: session `, and CI refuses one among the authors. --- @@ -105,6 +107,9 @@ kernel (this file) → contracts consumed (the contract alone, never someone else's implementation) ``` +One session, one working tree: never share a checkout with another session — each works in +its own copy of the repository. + **Playbooks — triggers.** Load `playbooks/.md` if and only if: | You are touching… | Load | diff --git a/README.md b/README.md index b736323..67436e1 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ missing setting. ```bash # 1. Tooling at the project's NapkinStack version (prerequisite: uv) -uv tool install "napkinstack==0.3.1" --with-executables-from pre-commit +uv tool install "napkinstack==0.4.0" --with-executables-from pre-commit # 2. Hooks, once per clone pre-commit install @@ -81,6 +81,10 @@ The merge keeps the project's adaptations and never touches the modules' code. A stays marked in the file, uncommitted: the team decides, and both the hook and CI reject any remaining marker. +A fix to NapkinStack itself can be tried here before it is released: `nstack update --ref +` pins the unpublished commit, CI installs it from the framework's repository, and +every run says so until a published version replaces it. + ## To do once on GitHub — otherwise nothing is guaranteed Workflows **inform**; it is the rulesets that **block**. Without this step the whole @@ -91,9 +95,13 @@ Settings → Rules → Rulesets → on the main branch (private repository: Team - [ ] Pull request required: no direct push to main - [ ] At least 1 approving review - [ ] Code owner review required -- [ ] Required checks: `Fitness functions`, `PR scope and review budget`, `Hooks and secrets`, `Test sheet and cycle` +- [ ] Stale approvals dismissed when new commits are pushed +- [ ] Required checks: `Fitness functions`, `PR scope and review budget`, `Hooks and secrets`, `Test sheet and cycle`, `Module checks` - [ ] Bypass list empty: nobody merges around the rules, administrators included +GitHub offers a check to require only once it has run: open a first pull request, then +select them. + Settings → Advanced Security (private repository: the Secret Protection option): - [ ] Secret Protection and push protection @@ -158,7 +166,7 @@ token, the GitHub part stays "not verified", never compliant. ```bash nstack --help # lists the commands -nstack fitness # manifests + boundaries + skills + plan — before every commit +nstack fitness # manifests + boundaries + skills + plan + hygiene — before every commit nstack discover # starts a discovery, for your agent nstack plan # the discovery, the charter and the cycles (docs/project/) nstack skills # generates the Claude Code skills from the playbooks @@ -167,6 +175,8 @@ nstack check [module] # MANIFEST commands: check, test, bootstrap; default: al nstack run # local start, when commands.run is declared nstack e2e [module] # end-to-end scenarios, when commands.e2e is declared nstack pr-check --body-file # test sheet and cycle, as CI reads them from the pull request +nstack modules --changed-since # the modules with a file changed, as CI lists them +nstack compat [module] --base # a contract version consumed or stable: the merged proof # check, test and run of a module: the `commands` section of its MANIFEST.yaml ``` @@ -217,14 +227,16 @@ fast feedback, not a guarantee: the blocking checks stay in CI No stack: no language, no application framework, no database. The OS imposes a **selection method** and a decision trail, not a list of technologies (`docs/os/06-decisions.md` §7). -A new module therefore declares commands "to be declared", which fail: wiring `check`, -`test` and `run` onto your own tooling is your job. The **names** never change, the +A new module therefore declares no command: it is green while it holds only its +description, and `nstack fitness` asks for `check` and `test` with its first file of code. +Wiring them, and `run`, onto your own tooling is your job. The **names** never change, the **content** is yours. ## What is left to wire after the installation - [ ] The `check` and `test` commands of every module, in its `MANIFEST.yaml` -- [ ] The contract format chosen, and the contract tests that go with it +- [ ] The contract format chosen, and the contract tests and the comparator behind + `commands.compat` that go with it - [ ] The review budget values (400 lines / 15 files are a starting point) - [ ] Re-read the `description` fields in `.nstack/skills.yaml` — they are what triggers the skills, and they must speak your domain's vocabulary diff --git a/contracts/AGENTS.md b/contracts/AGENTS.md index 457704f..6a8de42 100644 --- a/contracts/AGENTS.md +++ b/contracts/AGENTS.md @@ -10,6 +10,8 @@ Defines and versions the interface contracts between modules. - Every deprecated version carries a `removal_date`. Without a date, the pull request is refused. - A breaking change goes through **4 pull requests** (expand/contract), never one. +- A version a module consumes, or marked stable, changes only with the merged `compat` + command's approval (V1). - Contract tests run on **both sides**: producer and consumer. ## The main trap diff --git a/contracts/MANIFEST.yaml b/contracts/MANIFEST.yaml index 11f6dba..d3f68d7 100644 --- a/contracts/MANIFEST.yaml +++ b/contracts/MANIFEST.yaml @@ -15,9 +15,20 @@ data: shared: [] dependencies: [] +# Declared with the first contract: check and test are required once this folder holds one +# (fitness M7), and compat once a version is consumed or stable (nstack compat, V1). The +# tools are the project's, named in docs/tooling-profile.md. commands: - check: "echo 'commands.check to be declared: contract schema validation' >&2; exit 1" - test: "echo 'commands.test to be declared: contract tests' >&2; exit 1" + # Every document is valid OpenAPI 3.1 - its structure, not its examples. + check: >- + uvx --python 3.13 --from openapi-spec-validator==0.9.0 openapi-spec-validator */v*/openapi.yaml && + uvx --from ruff==0.16.8 ruff format --check tests && uvx --from ruff==0.16.8 ruff check tests + # Every example is what its schema declares: the consumers' doubles are built from them. + # Both sides' contract tests are the modules' own (charter, C2). + test: >- + uvx --python 3.13 --from pytest==9.1.1 --with pyyaml==6.0.3 --with jsonschema==4.26.0 + --with referencing==0.37.0 pytest tests +# compat: # exits 0 when $NSTACK_HEAD_PATH is compatible with $NSTACK_BASE_PATH docs: readme: README.md diff --git a/contracts/README.md b/contracts/README.md index 981b209..1bef683 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -20,7 +20,7 @@ contracts/ ## Evolving a contract **Additive** (optional field, new endpoint) → a simple pull request, contract tests -green. +green — and, once the version is consumed or stable, the `compat` command confirming it. **Breaking** → an expand/contract sequence in 4 pull requests, never one (`docs/os/03-contracts.md` §4): diff --git a/contracts/ruff.toml b/contracts/ruff.toml new file mode 100644 index 0000000..d023c81 --- /dev/null +++ b/contracts/ruff.toml @@ -0,0 +1,6 @@ +# The modules' own rules (modules/*/pyproject.toml): contracts holds Python for its tests only. +line-length = 100 +target-version = "py313" + +[lint] +select = ["E", "F", "I", "UP", "B", "SIM"] diff --git a/contracts/tests/.gitkeep b/contracts/tests/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/contracts/tests/test_the_examples_are_what_the_schemas_declare.py b/contracts/tests/test_the_examples_are_what_the_schemas_declare.py new file mode 100644 index 0000000..1447ea7 --- /dev/null +++ b/contracts/tests/test_the_examples_are_what_the_schemas_declare.py @@ -0,0 +1,96 @@ +"""Every example a contract document gives is what its own schema declares. + +A consumer's double is built from these examples (`modules/loans/src/loans/catalogue_double.py`): +an example that breaks its schema is a double that lies to every consumer tested against it. +The module's `check` validates the document's structure, never its examples; this suite reads +them. A pull request that changes only a contract document runs this module's verbs alone, so +nothing else would catch it. +""" + +from __future__ import annotations + +import re +from collections.abc import Iterator +from pathlib import Path +from typing import Any + +import pytest +import yaml +from jsonschema import Draft202012Validator +from referencing import Registry, Resource +from referencing.jsonschema import DRAFT202012 + +CONTRACTS = Path(__file__).resolve().parents[1] +DOCUMENTS = sorted(CONTRACTS.glob("*/v*/openapi.yaml")) +BY_REFERENCE = object() +PROBLEM = re.compile(r"/responses/(?P[1-5][0-9][0-9])/content/application~1problem\+json/") + + +def escaped(key: object) -> str: + return str(key).replace("~", "~0").replace("/", "~1") + + +def examples(node: Any, pointer: str = "") -> Iterator[tuple[str, str, Any]]: + """(where the example is, where its schema is, the example): every media type, parameter + and header that gives both a schema and an example.""" + if isinstance(node, dict): + if "schema" in node: + if "example" in node: + yield f"{pointer}/example", f"{pointer}/schema", node["example"] + for name, given in (node.get("examples") or {}).items(): + value = given.get("value", BY_REFERENCE) if isinstance(given, dict) else given + yield f"{pointer}/examples/{escaped(name)}", f"{pointer}/schema", value + for key, value in node.items(): + yield from examples(value, f"{pointer}/{escaped(key)}") + elif isinstance(node, list): + for index, value in enumerate(node): + yield from examples(value, f"{pointer}/{index}") + + +def read(document: Path) -> Any: + return yaml.safe_load(document.read_text(encoding="utf-8")) + + +FOUND = [ + (f"{document.relative_to(CONTRACTS)}#{where}", document, where, schema, example) + for document in DOCUMENTS + for where, schema, example in examples(read(document)) +] +CASES = [ + pytest.param(document, schema, example, id=name) for name, document, _, schema, example in FOUND +] +PROBLEMS = [ + pytest.param(int(found["code"]), example, id=name) + for name, _, where, _, example in FOUND + if (found := PROBLEM.search(where)) and isinstance(example, dict) +] + + +def test_the_documents_and_their_examples_are_found() -> None: + """No quiet pass: a suite that finds nothing to read says so.""" + assert DOCUMENTS, "no contract document found under contracts//v/openapi.yaml" + assert CASES, "no example found in the contract documents" + + +@pytest.mark.parametrize(("document", "schema", "example"), CASES) +def test_the_example_is_what_its_schema_declares(document: Path, schema: str, example: Any) -> None: + assert example is not BY_REFERENCE, ( + "an example given by reference or as an external value: read it here before a " + "double relies on it" + ) + uri = document.as_uri() + registry = Registry().with_resource( + uri, Resource(contents=read(document), specification=DRAFT202012) + ) + validator = Draft202012Validator({"$ref": f"{uri}#{schema}"}, registry=registry) + + broken = [f"{error.json_path}: {error.message}" for error in validator.iter_errors(example)] + + assert not broken, broken + + +@pytest.mark.parametrize(("code", "example"), PROBLEMS) +def test_a_problem_says_the_status_its_response_answers(code: int, example: dict) -> None: + """RFC 9457 §3.1.3: `status` is the code of the response that carries it. A double answers + with the response's code and the example's body: a 404 whose body says 400 would lie.""" + assert example.get("status", code) == code diff --git a/docs/os/02-modules.md b/docs/os/02-modules.md index 185a86b..371e887 100644 --- a/docs/os/02-modules.md +++ b/docs/os/02-modules.md @@ -142,11 +142,14 @@ modules// ├── docs/ │ ├── adr/ ← local technical decisions │ └── runbook.md ← when the module is operated in production -├── contracts/ ← contracts PROVIDED by this module ├── src/ └── tests/ ``` +The contracts a module provides live in the project's `contracts/` module, one folder per +contract and version (`03-contracts.md` §2), and its manifest points at them +(`provides[].path`). + **Rule for the local `AGENTS.md`**: it contains only what is specific to the module. Never duplicate a kernel rule there. A local `AGENTS.md` that repeats the kernel is a bug — it wastes context and creates a risk of divergence. @@ -192,9 +195,10 @@ flowchart LR **Legend** — dark grey: the declaration · green: the deterministic verdict. -The essential point: **the manifest declares the intent, CI verifies reality.** An import -towards an undeclared module fails in CI. A dependency declared but unused is reported. -No semantic analysis is needed — it is a comparison of graphs. +The essential point: **the manifest declares the intent, CI verifies reality.** A contract +a module reads without declaring it fails in CI, and so does any reference to another +module's code, declared or not; a contract declared and never read is reported. No semantic +analysis is needed — it is a comparison of graphs. --- @@ -259,6 +263,10 @@ violation becomes an architecture signal. **Rule.** A pull request changes the files of a single module. Exceptions exist but are visible, traced and counted. +A module is touched when its behaviour changes: editing only its description — manifest, +`AGENTS.md`, `README.md`, `docs/` — touches none, and `contracts/` is a module like the +others. + | Exception | Handling | |---|---| | Contract change | An expand/contract sequence, never a single PR (`03-contracts.md`) | @@ -314,7 +322,8 @@ forbidden paths. **Allowed but worth watching:** shared technical primitives (logging, errors, utilities with no business logic). As soon as a business rule enters a shared package, two modules -become inseparable. +become inseparable. They live outside the module folders: a module never imports another +module's code, and declaring its contract in `consumes` does not change that. --- diff --git a/docs/os/03-contracts.md b/docs/os/03-contracts.md index 5bd9ebb..4c2a61d 100644 --- a/docs/os/03-contracts.md +++ b/docs/os/03-contracts.md @@ -39,7 +39,12 @@ errors, authentication, authorisation, compatibility and deprecation rules. ## 3. Classifying a change -This is the first question to ask, and it can be mechanised. +This is the first question to ask, and it can be mechanised. It is: from the moment a +module consumes a version, or its producer marks it `stable`, a change to its files needs the +project's comparator — the `compat` command of the module holding it, as merged — to call it +compatible; otherwise it becomes a new version beside it (`nstack compat`, rule V1). Moving +the version to another folder changes nothing: it is judged wherever it now lives. A version +still experimental, which nobody consumes, is free to change. ```mermaid flowchart TD @@ -109,9 +114,9 @@ sequenceDiagram | **1 — Expand contract** | Producer | v2 declared, additive. v1 untouched. | Contract tests v1 **and** v2 green | | **2 — Expand impl.** | Producer | Serves both versions at once | No consumer affected | | **3 — Migration** | Each consumer | Switches to v2, at its own pace | Manifest updated: version consumed | -| **4 — Contract** | Producer | Removal of v1 | Review: v1 consumers = 0 (to automate) | +| **4 — Contract** | Producer | Removal of v1 | v1 consumers = 0, checked (B6) | -### The two guardrails +### The three guardrails **① The deprecation date is a check.** From PR 1 onwards, v1 carries a removal date. A check fails once the date has passed and consumers remain. Without it, you accumulate @@ -121,6 +126,9 @@ versions nobody dares remove. precisely what produces permanent intermediate states. PR 1 opens a contraction issue, assigned to the contract's owner: by hand, until opening it is automated. +**③ A version someone relies on is frozen.** The expand step adds v2 beside v1; editing v1 +in place passes only when the merged comparator proves the edit compatible (V1). + --- ## 5. Contract tests diff --git a/docs/os/05-workflow.md b/docs/os/05-workflow.md index f28c03e..04a95e8 100644 --- a/docs/os/05-workflow.md +++ b/docs/os/05-workflow.md @@ -224,7 +224,10 @@ criticality are read before and after the change, and the stricter applies: - **Written before the code**, from the acceptance criteria: it is part of the oracle. - **Run by a verifier who is not the author**: another agent session with a fresh context, or a human (`playbooks/verification.md`). The session that wrote the code - shares its misunderstandings. + shares its misunderstandings. CI compares the verifier's name with the change's authors — + the pull request's, the commits' GitHub accounts (read from their noreply addresses), and + the sessions their `Agent-Session` trailers name — and refuses a match: a declaration + checked against the history, not a proof of identity. - **No result without evidence**, tied to the commit tested. A new commit sends the scenarios back to be run again. - **Kinds**: *automated* — replayable, run by CI through the module's `e2e` command; diff --git a/docs/os/07-governance.md b/docs/os/07-governance.md index 1f9270b..1da9727 100644 --- a/docs/os/07-governance.md +++ b/docs/os/07-governance.md @@ -124,6 +124,11 @@ The first six are cheap: they are computed from data already present (manifests, contract schemas). There is **no semantic analysis** — these are comparisons of graphs and schemas. +Beside them, the engine checks what a shared repository must not carry: a path rooted in one +person's home directory, in any tracked file (H1). It exists on no other machine and +publishes the layout of the one it was written on; an image's or a runner's home, a +placeholder or a variable is the same everywhere. + ### Writing a fitness function A good fitness function is fast (it runs on every pull request), deterministic (no random @@ -230,6 +235,7 @@ to use (GitHub wording, transposable elsewhere): | Merge queue | Avoids merges that break each other | | A dedicated identity for agents | An agent neither approves nor merges around a human approval | | Rulesets with an empty bypass list | Nobody, administrators included, merges around a rule | +| Stale approvals dismissed on push | An approval covers the commits its approver read | | A default code owner | The code owner review covers every path | > **Critical rules must not be bypassable by an instruction given to the AI.** That is @@ -239,7 +245,7 @@ to use (GitHub wording, transposable elsewhere): ### Agents and approval A pull request's author cannot approve it. An agent working with a human's credentials -*is* that human: it can approve a colleague's pull request in their name, then merge. Three +*is* that human: it can approve a colleague's pull request in their name, then merge. Four settings close that door, and they only hold together: 1. **The agent has its own identity** — a GitHub App installed on the repository: tokens @@ -249,6 +255,8 @@ settings close that door, and they only hold together: 2. **The merge requires a human code owner's approval**, and `CODEOWNERS` starts with a default owner: an App can approve, but it is never a code owner. 3. **Nobody is on the rulesets' bypass list**, administrators included. +4. **An approval is dismissed when new commits are pushed**: otherwise a force-push after + the approval merges content its approver never read. The human who drove the agent may approve its pull request. A team that wants four eyes adds "require approval of the most recent reviewable push", or a second reviewer. An diff --git a/docs/os/09-platform.md b/docs/os/09-platform.md index 2b0d6cf..e6dbafe 100644 --- a/docs/os/09-platform.md +++ b/docs/os/09-platform.md @@ -57,15 +57,18 @@ section, with its own stack's commands. | `test` | The module's test suite | With no dependency on another module | | `run` | Start the module locally | With doubles for the dependencies | | `e2e` | The module's end-to-end scenarios; evidence written to `.evidence/` | Against the running module, in CI | +| `compat` | Tell whether a change to a contract version is compatible: exit 0 when `$NSTACK_HEAD_PATH` accepts what `$NSTACK_BASE_PATH` did | On the module holding contracts, once one is consumed or stable | | `contracts` | Validate and generate the contract artefacts | On every contract change | | `migrate` | Apply the data migrations | When the module owns data | | `release` | Produce the shippable artefact | Reproducibly | -The engine runs `bootstrap`, `check`, `test`, `run` and `e2e`: it reads the command from +The engine runs `bootstrap`, `check`, `test`, `run`, `e2e` and `compat`: it reads the command from the manifest and launches it from the module's folder, locally as in CI. `check` and -`test` are mandatory, `bootstrap` and `e2e` optional; a new module declares them as "to be declared", failing, until the team -puts its own stack's commands there. `contracts`, `migrate` and `release` are reserved -names, to declare when a module needs them. +`test` are mandatory as soon as the module holds anything beyond its description — its +manifest, `AGENTS.md`, `README.md`, `docs/`; `bootstrap` and `e2e` are optional. A new module +holds only its description: its verbs report that there is nothing to run yet, and +`nstack fitness` asks for `check` and `test` with its first other file. `contracts`, +`migrate` and `release` are reserved names, to declare when a module needs them. **Why this is the foundation of multi-team work.** A developer or an agent arriving on an unknown module does not have to discover whether to run `npm`, `make`, `cargo`, `pytest` @@ -150,11 +153,11 @@ flowchart TD A["Creation ADR
capability · owner · criticality"]:::human --> B["Engine: the module is created
in a single call"]:::engine B --> C1["MANIFEST pre-filled
owner organisation/team"]:::generated B --> C2["AGENTS.md and README
with the expected sections"]:::generated - B --> C3["check and test commands
to be declared, failing"]:::generated + B --> C3["No command yet: green
until its first code"]:::generated B --> C4["CODEOWNERS updated"]:::generated B --> C5["Runbook
when criticality is high or critical"]:::generated B --> C6["Fitness functions and CI
active from the first commit"]:::generated - C3 --> E["The team declares its
own stack's commands"]:::human + C3 --> E["The team declares its stack's
check and test, then codes"]:::human C1 --> D["First useful commit"]:::done C2 --> D E --> D @@ -174,8 +177,8 @@ generated · light grey: the result. The critical point is `C6`: **the guardrails are active from the first commit**. A module created without fitness functions will accumulate violations discovered too late, and eventually tolerated because fixing them has become too expensive. `C3` is its corollary: -a module whose commands are not declared fails in CI instead of going green while -checking nothing. +a module is green while it holds nothing to check, and fails in CI from its first file of +code whose commands are not declared — never green while checking nothing. --- diff --git a/docs/tooling-profile.md b/docs/tooling-profile.md index d62b36b..d7c73e1 100644 --- a/docs/tooling-profile.md +++ b/docs/tooling-profile.md @@ -20,6 +20,8 @@ | Pre-commit checks | Immediate feedback, the same configuration as CI | pre-commit | NapkinStack foundation | | Format validation | Loadable YAML with no traps, conforming GitHub files | check-yaml, yamllint, check-jsonschema | NapkinStack foundation | | Architecture analysis | Support for the fitness functions | `nstack fitness` | NapkinStack foundation | +| Contract documents | Each contract document valid in its format, each example what its schema declares | openapi-spec-validator (`check`); pytest and jsonschema (`test`) | The `contracts` module's verbs, with the update to v0.4.0 | +| Contract compatibility | Proving a change to a version someone relies on compatible | | | | Framing and verification checks | The discovery, the charter, the cycles and the test sheet, checked | `nstack discover`, `nstack plan`, `nstack pr-check` | NapkinStack foundation | | Loading rules on demand | Playbooks triggered by context | Claude Code skills, generated by `nstack skills` | NapkinStack foundation | | Specialised agents | Independent review, isolated investigation | | | diff --git a/modules/README.md b/modules/README.md index db73dcc..3cf16f5 100644 --- a/modules/README.md +++ b/modules/README.md @@ -12,9 +12,10 @@ One autonomous unit of context and of parallelism per folder. nstack new-module billing acme/billing standard ``` -The scaffolding produces the manifest, the local `AGENTS.md`, the standard verbs, the -CODEOWNERS line, and activates the fitness functions **from the first commit** — a module -created without guardrails accumulates violations discovered too late. +The scaffolding produces the manifest, the local `AGENTS.md`, the CODEOWNERS line, and +activates the fitness functions **from the first commit** — a module created without +guardrails accumulates violations discovered too late. The standard verbs are the team's to +declare, for its stack, before the module's first file of code. Creating a module is a decision: it goes through an **ADR** (the capability covered, the boundary, the rejected alternatives). diff --git a/playbooks/verification.md b/playbooks/verification.md index 4455886..581c0ba 100644 --- a/playbooks/verification.md +++ b/playbooks/verification.md @@ -19,7 +19,9 @@ still applies. | Report the gaps against the need or against correctness | Report a preference as a gap | The session that wrote the change cannot verify it: start another session, with a fresh -context, or hand the sheet to a human. +context, or hand the sheet to a human. Sign the sheet with your session's identifier — +`Verifier: session ` — or, as a person, `Verifier: @`. CI compares it with the +change's authors and refuses a match. ---