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.3.1
_commit: v0.4.0
_src_path: https://github.com/NapkinStack/engineering-os.git
github_repo: NapkinStack/tool-library
owner_team: NapkinStack/maintainers
Expand Down
5 changes: 3 additions & 2 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,8 @@ other: <specify>

- [ ] 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

Expand Down Expand Up @@ -95,7 +96,7 @@ other: <specify>
> not the author (`playbooks/verification.md`). Kind: automated · explored · human only —
> reason. Result: passed · failed — what was observed · not verified.

Verifier: <agent session or @human>
Verifier: <@handle, or session and the agent session's identifier>

| # | Given · when · then | Kind | Result | Evidence | Commit |
|---|---|---|---|---|---|
Expand Down
14 changes: 4 additions & 10 deletions .github/workflows/governance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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.
Expand Down
71 changes: 52 additions & 19 deletions .github/workflows/module-checks.yml
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
Expand All @@ -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"
Expand All @@ -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'
Expand All @@ -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 ]; }
5 changes: 2 additions & 3 deletions .github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
31 changes: 31 additions & 0 deletions .nstack/install-engine.sh
Original file line number Diff line number Diff line change
@@ -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<sha>
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
}
7 changes: 6 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: <an identifier of this session>`; as a verifier, you
sign the sheet `Verifier: session <that identifier>`, and CI refuses one among the authors.

---

Expand Down Expand Up @@ -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/<x>.md` if and only if:

| You are touching… | Load |
Expand Down
24 changes: 18 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
<commit>` 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
Expand All @@ -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
Expand Down Expand Up @@ -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 <idea-file> # 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
Expand All @@ -167,6 +175,8 @@ nstack check [module] # MANIFEST commands: check, test, bootstrap; default: al
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 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 Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions contracts/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 13 additions & 2 deletions contracts/MANIFEST.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion contracts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
6 changes: 6 additions & 0 deletions contracts/ruff.toml
Original file line number Diff line number Diff line change
@@ -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"]
Empty file removed contracts/tests/.gitkeep
Empty file.
Loading
Loading