diff --git a/.copier-answers.yml b/.copier-answers.yml index 4481add..2382bb1 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.5.0 +_commit: v0.6.0 _src_path: https://github.com/NapkinStack/engineering-os.git github_repo: NapkinStack/tool-library owner_team: NapkinStack/maintainers diff --git a/.github/workflows/module-checks.yml b/.github/workflows/module-checks.yml index fcf7aa3..e8d1e30 100644 --- a/.github/workflows/module-checks.yml +++ b/.github/workflows/module-checks.yml @@ -9,6 +9,10 @@ name: Modules # `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. # +# A change to a contract version also runs the checks of the module that provides it and of +# every module that declares it in consumes: the contract tests of both sides, which is what +# docs/os/03-contracts.md section 5 promises. +# # Module names come from the paths the pull request changed: they are never inserted # into a script, only read from an environment variable. @@ -52,7 +56,7 @@ jobs: # 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=$(nstack modules --root . --changed-since "$BASE" --json) + MODS=$(nstack modules --root . --changed-since "$BASE" --with-contract-sides --json) echo "modules=$MODS" >> "$GITHUB_OUTPUT" echo "base=$BASE" >> "$GITHUB_OUTPUT" if [ "$MODS" = '[]' ]; then echo "any=false" >> "$GITHUB_OUTPUT"; diff --git a/README.md b/README.md index 3220d70..fe2fcef 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ mention such a commit, and where a ruleset does refuse, it catches a bypass. ```bash # 1. Tooling at the project's NapkinStack version (prerequisite: uv) -uv tool install "napkinstack==0.5.0" --with-executables-from pre-commit +uv tool install "napkinstack==0.6.0" --with-executables-from pre-commit # 2. Hooks, once per clone pre-commit install @@ -185,6 +185,7 @@ 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 modules --changed-since --with-contract-sides # ... and both sides of a changed contract 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 ``` diff --git a/docs/os/02-modules.md b/docs/os/02-modules.md index 371e887..9bf2a63 100644 --- a/docs/os/02-modules.md +++ b/docs/os/02-modules.md @@ -164,7 +164,8 @@ traps, business invariants, non-standard commands, areas not to change and why. This is the piece that makes multi-team work operational. A single declarative file, readable by a human, by an agent **and by CI**. -See `templates/MANIFEST.example.yaml` for the full format. It declares: +The manifest `nstack new-module` writes is the reference for the full format; +`contracts/MANIFEST.yaml` is the one every project already holds. It declares: - identity and responsibility in one sentence; - owner (a team, not an individual); @@ -174,6 +175,10 @@ See `templates/MANIFEST.example.yaml` for the full format. It declares: - contracts consumed, with versions; - standard commands. +Each of these is filled in: a responsibility still holding the template's sentence fails +M2 from the module's first file of code — never before, so a module the engine has just +created is green. + ### The three uses that justify its cost ```mermaid @@ -245,10 +250,10 @@ The status lives in the manifest, so it is checkable: | Situation | CI result | |---|---| -| A `maintenance` module whose contract changes | **Red** | -| A `deprecated` module that gains a consumer | **Red** | -| A `deprecated` module whose removal date has passed | **Red** | -| An `active` module with no declared owner | **Red** | +| A frozen contract version of a `maintenance` module changed | **Red** (V1): a version consumed or stable changes only with the merged proof | +| A `deprecated` module with a consumer | Reported (B8), and **red** once its removal date has passed (M5) | +| A `deprecated` module whose removal date has passed | **Red** (M5) | +| An `active` module with no declared owner | **Red** (M2) | This is what avoids **permanent intermediate states**: a deprecated path that never disappears because nobody is responsible for removing it. diff --git a/docs/os/03-contracts.md b/docs/os/03-contracts.md index b821457..4166ec7 100644 --- a/docs/os/03-contracts.md +++ b/docs/os/03-contracts.md @@ -175,8 +175,11 @@ Both directions matter, and they catch different mistakes: non-contractual behaviour — the case where the producer breaks someone without having violated anything. -Contract tests run in the CI of **both modules**. A contract change that breaks a -declared consumer is caught before merge, without a meeting. +Contract tests run in the CI of **both modules**: a change to a contract version runs the +checks of the module that provides it and of every module that declares it in `consumes`, +read from the manifests (`nstack modules --with-contract-sides`, wired into the module +workflow). A contract change that breaks a declared consumer is caught before merge, +without a meeting. --- diff --git a/docs/os/05-workflow.md b/docs/os/05-workflow.md index 04a95e8..5dfe565 100644 --- a/docs/os/05-workflow.md +++ b/docs/os/05-workflow.md @@ -97,8 +97,9 @@ generation instead of observing the damage afterwards. > The project's real throughput is its verification throughput, not its generation > throughput. -The budget is an explicit ceiling, declared at project level and adjustable per module -according to its criticality. It covers: +The budget is an explicit ceiling, set for the project — `MAX_LINES` and `MAX_FILES` in +the pull request workflow. Adjusting it per module, by criticality, is not automated: it +is in the automation backlog. It covers: | Dimension | Indicative ceiling | |---|---| diff --git a/docs/os/09-platform.md b/docs/os/09-platform.md index e6dbafe..7478b55 100644 --- a/docs/os/09-platform.md +++ b/docs/os/09-platform.md @@ -258,7 +258,9 @@ What the skeleton and its engine provide from day one: - the kernel and the playbooks; - execution of the standard verbs declared in the manifests; - the ADR, PDR, issue and pull request templates; -- the basic fitness functions (1 to 3 of `07-governance.md` §3); +- the fitness functions of `07-governance.md` §3, 1 to 9: the declared graph, cycles, + another module's data, contract compatibility and consumers, lifecycle statuses and + dates, one pull request one module, the module envelope; - CI with the checks of the `standard` level; - CODEOWNERS, and the checklist of forge settings, which the engine verifies read-only; - module creation; diff --git a/docs/os/README.md b/docs/os/README.md index 0083bb1..3d1acb4 100644 --- a/docs/os/README.md +++ b/docs/os/README.md @@ -101,4 +101,4 @@ rule live?" first. The answer is very often "in CI", not "in the prompt". This OS is subject to its own rules: it evolves in small steps, its structuring changes get an ADR, and every rule it contains is a candidate for automation. See -`docs/10-measurement.md` § "Improving the OS". +`10-measurement.md` § "Improving the OS". diff --git a/docs/project/README.md b/docs/project/README.md index 32c931a..b7a0a25 100644 --- a/docs/project/README.md +++ b/docs/project/README.md @@ -9,7 +9,7 @@ cycle before working (`AGENTS.md` §4). | `discovery.md` | An idea tested: evidence, value hypothesis, challenge, decision | The framer, then the challenger (`playbooks/discovery.md`) | The decider | | `charter.md` | Users, problem, constraints, risks, success criteria, out of scope | The framer (`playbooks/framing.md`) | The decider | | `cycles/NN-.md` | One goal, a finite list of deliverables, an appetite, an end date, the closure | The framer | The decider | -| `_CHARTER_TEMPLATE.md`, `cycles/_TEMPLATE.md` | The templates | — | — | +| `_DISCOVERY_TEMPLATE.md`, `_CHARTER_TEMPLATE.md`, `cycles/_TEMPLATE.md` | The templates | — | — | ```mermaid flowchart LR @@ -33,7 +33,7 @@ red: the circuit breaker and what it can lead to. | Check | When | Rules | |---|---|---| -| The plan, a fitness function | Every push | Formats; one accepted cycle at a time, under an accepted charter; `end` = `start` + the appetite; acceptance criteria once a deliverable is ready; closures recorded; a discovery decided with its decider and date, a charter only after a go | +| The plan, a fitness function | Every push | Formats; one accepted cycle at a time, under an accepted charter; `end` = `start` + the appetite; acceptance criteria once a deliverable is ready; closures recorded; a discovery decided with its decider and date, a charter only after a go. A charter, a cycle or a deliverable still holding the template's words is refused | | The pull request check | Every pull request changing a module beyond its description — manifest, `AGENTS.md`, `README.md`, `docs/`; not a framework update | An accepted cycle; not past its end date; a ready or in-progress deliverable named — or the `out-of-cycle` label with its justification | The charter changes only through a PDR (`docs/os/06-decisions.md` §4). A cycle is never