Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .copier-answers.yml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
6 changes: 5 additions & 1 deletion .github/workflows/module-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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";
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -185,6 +185,7 @@ nstack run <module> # local start, when commands.run is declared
nstack e2e [module] # end-to-end scenarios, when commands.e2e is declared
nstack pr-check --body-file <file> # test sheet and cycle, as CI reads them from the pull request
nstack modules --changed-since <base> # the modules with a file changed, as CI lists them
nstack modules --changed-since <base> --with-contract-sides # ... and both sides of a changed contract
nstack compat [module] --base <base> # a contract version consumed or stable: the merged proof
# check, test and run of a module: the `commands` section of its MANIFEST.yaml
```
Expand Down
15 changes: 10 additions & 5 deletions docs/os/02-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
7 changes: 5 additions & 2 deletions docs/os/03-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
5 changes: 3 additions & 2 deletions docs/os/05-workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|
Expand Down
4 changes: 3 additions & 1 deletion docs/os/09-platform.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion docs/os/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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".
4 changes: 2 additions & 2 deletions docs/project/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<slug>.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
Expand All @@ -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
Expand Down
Loading