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.4.0
_commit: v0.5.0
_src_path: https://github.com/NapkinStack/engineering-os.git
github_repo: NapkinStack/tool-library
owner_team: NapkinStack/maintainers
Expand Down
44 changes: 44 additions & 0 deletions .github/workflows/commits-on-main.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Commits on main

# What reached this branch outside a pull request, recorded (W1, PDR-0006).
#
# This workflow RECORDS; it never refuses. What refuses a merge is the ruleset, and on a
# repository whose plan cannot enforce one, nothing refuses at all — which is exactly when
# this record is the only thing that will ever mention a commit pushed straight to main.
# On a guarded repository it is cheap and catches a bypass by an administrator.
#
# It says nothing about what predates its own arrival, nor about the commit that created the
# repository: a record that greets a project by failing on itself teaches people to ignore it.
#
# Rights: none beyond reading. The token reads how each commit arrived and nothing else, so
# the project's automation stays read-only (checklist rule G10).

on:
push:
branches: [main]

permissions:
contents: read
pull-requests: read

jobs:
landed:
name: Commits on main
runs-on: ubuntu-latest
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

# The pushed range. A branch's first push carries no "before": the tip alone is read.
- name: How each commit arrived
env:
SPAN: ${{ github.event.before }}..${{ github.event.after }}
GH_TOKEN: ${{ github.token }}
run: nstack landed --span "$SPAN"
9 changes: 6 additions & 3 deletions .github/workflows/module-checks.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Modules

# Runs the standard verbs on the touched modules only: nstack reads their commands
# Runs the standard verbs on the changed modules only: nstack reads their commands
# 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
Expand Down Expand Up @@ -101,8 +101,11 @@ jobs:
run: nstack test "$MODULE"

# A contract version someone relies on changes only with the merged proof (V1,
# docs/os/03-contracts.md §4).
# docs/os/03-contracts.md §4). The step runs even when an earlier one failed: a pull
# request that breaks a frozen version AND a test would otherwise meet V1 a round trip
# later, once the tests are green (D46).
- name: compat
if: ${{ !cancelled() }}
run: nstack compat "$MODULE" --base "$BASE"

# Levels high and critical — not wired up yet (D9)
Expand Down Expand Up @@ -132,7 +135,7 @@ jobs:
if: always()
runs-on: ubuntu-latest
steps:
- name: Every touched module passed
- name: Every changed module passed
env:
DISCOVERED: ${{ needs.discover.result }}
VALIDATED: ${{ needs.validate.result }}
Expand Down
15 changes: 12 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,14 +47,23 @@ CI decides as soon as the rulesets require it: what does not pass does not merge
| Private vulnerability reporting | Yes | Does not exist | Does not exist |
| CI minutes | Unlimited | 2 000 per month | Per the plan |

`nstack doctor` follows the repository's visibility and names the plan required for every
missing setting.
`nstack doctor` reads these settings and answers in one word. **Guarded**: the forge refuses
what the checklist asks it to refuse. **Unguarded**: nothing here refuses a merge — and it
keeps apart what your plan forbids, which you can do nothing about, from what is simply not
in place yet. A project that has done everything its plan allows is reported as compliant,
and still told that it is unguarded: the checks below keep telling the truth, and none of
them stops a merge on their own.

Whatever the plan allows, the project receives one more workflow, **Commits on main**: it
fails when a commit reached `main` outside a pull request, and names it. It records; it does
not refuse — on a repository where nothing can refuse, it is the only thing that will ever
mention such a commit, and where a ruleset does refuse, it catches a bypass.

## Installation

```bash
# 1. Tooling at the project's NapkinStack version (prerequisite: uv)
uv tool install "napkinstack==0.4.0" --with-executables-from pre-commit
uv tool install "napkinstack==0.5.0" --with-executables-from pre-commit

# 2. Hooks, once per clone
pre-commit install
Expand Down
6 changes: 6 additions & 0 deletions docs/os/03-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,12 @@ compatible; otherwise it becomes a new version beside it (`nstack compat`, rule
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.

**The proof runs as merged, and in the merged tree.** The command is read at the base, and it
is executed in the repository as it is at the base — so a script, a fixture or a tool it calls
is the merged one, not the one the pull request may have rewritten. Of the change, it is handed
exactly one thing: the document it judges, at `NSTACK_HEAD_PATH`. A comparator therefore never
takes its instructions from what it is judging.

```mermaid
flowchart TD
A["Contract change considered"] --> B{"Does an existing consumer<br/>keep working with no<br/>change at all?"}
Expand Down
8 changes: 8 additions & 0 deletions docs/os/07-governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,11 +237,19 @@ to use (GitHub wording, transposable elsewhere):
| 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 |
| A record of what landed | Nothing reaches the protected branch in silence — it records, it never refuses |

> **Critical rules must not be bypassable by an instruction given to the AI.** That is
> the ultimate test of governance: if asking an agent nicely is enough to get around it,
> the rule does not exist.

**And when the forge cannot enforce any of it.** Every mechanism above depends on what the
repository's plan allows; on some, none of them is available, and nothing refuses a merge at
all. The diagnosis says so in one word — *unguarded* — and what remains is the last row: a
run that fails when a commit reached the protected branch outside a pull request. That is a
record, not a barrier, and it is worth exactly what a record is worth: the thing nobody would
otherwise have been told. Reading it as a guarantee is the mistake it exists to prevent.

### Agents and approval

A pull request's author cannot approve it. An agent working with a human's credentials
Expand Down
Loading