diff --git a/.copier-answers.yml b/.copier-answers.yml index 3cd5e80..4481add 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.4.0 +_commit: v0.5.0 _src_path: https://github.com/NapkinStack/engineering-os.git github_repo: NapkinStack/tool-library owner_team: NapkinStack/maintainers diff --git a/.github/workflows/commits-on-main.yml b/.github/workflows/commits-on-main.yml new file mode 100644 index 0000000..a74e7a6 --- /dev/null +++ b/.github/workflows/commits-on-main.yml @@ -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" diff --git a/.github/workflows/module-checks.yml b/.github/workflows/module-checks.yml index 6b45c01..fcf7aa3 100644 --- a/.github/workflows/module-checks.yml +++ b/.github/workflows/module-checks.yml @@ -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 @@ -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) @@ -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 }} diff --git a/README.md b/README.md index 67436e1..3220d70 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/os/03-contracts.md b/docs/os/03-contracts.md index 4c2a61d..b821457 100644 --- a/docs/os/03-contracts.md +++ b/docs/os/03-contracts.md @@ -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
keep working with no
change at all?"} diff --git a/docs/os/07-governance.md b/docs/os/07-governance.md index 1da9727..9d3011b 100644 --- a/docs/os/07-governance.md +++ b/docs/os/07-governance.md @@ -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