Skip to content

NapkinStack v0.3.1 -> v0.4.0, and the contracts module's check and test - #31

Merged
napkinstack-agent[bot] merged 3 commits into
mainfrom
nstack/update-v0.4.0
Sep 19, 2026
Merged

napkinstack-agent[bot] merged 3 commits into
mainfrom
nstack/update-v0.4.0

Conversation

@napkinstack-agent

@napkinstack-agent napkinstack-agent Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

NapkinStack v0.3.1 -> v0.4.0, and the contracts module's check and test

Part of the validation log, #1 (NapkinStack M10h: the fixes of v0.4.0, proved where they
were found).


Module

contracts — exactly one. The rest of the diff is the framework's own update, outside
every module.

  • This pull request touches a single module
  • ⚠️ Cross-module — the cross-module label is required, justification below

Deliverable

Out of cycle: the update to v0.4.0 asks the contracts module for its verbs (fitness M7), and cycle 1 is closed with no cycle framed after it. The framework's own update, not a deliverable.

What it changes

The update. nstack update from v0.3.1 to v0.4.0, merged by Copier with no conflict
(commit 7b0cd04, unchanged by hand): the required Module checks, the engine installed
from the registry by .nstack/install-engine.sh, the handbook and the kernel as v0.4.0 ships
them. v0.4.0 no longer ships placeholder verbs, so contracts/, which holds catalog-api v1,
is asked for its own (fitness M7).

The adaptation (commits 3f043a2 and 20d484a), in the stack of the charter (C2: Python 3.13 through
uv, pytest, ruff), every tool pinned:

  • check — every contract document is valid OpenAPI 3.1 (openapi-spec-validator), and the
    Python of its tests passes the modules' own ruff rules (contracts/ruff.toml, copied from
    modules/*/pyproject.toml).
  • test — every example a document gives is what its schema declares. loans builds its
    double of catalog from these examples (catalogue_double.py): an example that breaks its
    schema is a double that lies to every test run against it. The check reads the structure
    only — an example with status: 200 in a Problem, whose minimum is 400, passes it — and
    a pull request that changes only a contract document runs this module's verbs alone. And a
    Problem example says the status its response answers (RFC 9457 §3.1.3): the double answers
    with the response's code and the example's body, so a 404 whose body says 400 would lie —
    the verifier found that the first version of the test let it through.
  • docs/tooling-profile.md: the row of these tools. The Contract compatibility row stays
    empty until commands.compat is declared, in a pull request of its own (V1 reads the proof
    as merged).

Oracle

docs/os/05-workflow.md §3

  • The success criterion was written before the implementation — fitness M7 on
    contracts/ after the update; the test's criterion, each example against its schema
  • It was seen failing, for the right reason — M7, twice; the test on a copy of the
    document with a broken example (below, S2)
  • It passes now

Kind of oracle: contract test · fitness function


Review budget

docs/os/05-workflow.md §4

  • Lines changed (excluding generated): 360
  • Files touched: 22
  • Within budget
  • ⚠️ Over budget — label required, justification: a framework update — 19 of the 22
    files are Copier's merge of v0.4.0, unchanged by hand; the adaptation is 5 files, 114 lines,
    two of them among those 19

Contracts

  • No contract affected — catalog-api v1 is unchanged; only the module that holds it
    gains its verbs
  • Contract consumed — the version is declared in the manifest
  • 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

Definition of Done

Tick what is applicable for the module's criticality
(docs/os/05-workflow.md §7). Never tick a box without having actually run it.

  • Oracle green
  • Lint, format, types — ruff, through the module's check
  • Unit tests — the module's test
  • Build — nothing is built
  • Contract tests (when there is a contract) — the examples; both sides' own are the
    modules', untouched
  • Fitness functions
  • Integration tests (per risk) — none: no module is started
  • Security analysis — the project's hooks, gitleaks over the three commits
  • Accessibility (when there is UI) — no UI
  • E2E on critical journeys (criticality high and above) — no journey: a document
  • Observability added (criticality high and above) — nothing runs
  • Rollback verified (criticality critical) — not critical
  • Affected documentation updated
  • Diff self-reviewed line by line

Test sheet

Required when the pull request changes a user-facing module, or one of criticality high
or critical, beyond its description — manifest, AGENTS.md, README.md, docs/
(docs/os/05-workflow.md §7). The scenarios come from the acceptance
criteria and are written before the code; the results are filled in by a verifier who is
not the author (playbooks/verification.md). Kind: automated · explored · human only —
reason. Result: passed · failed — what was observed · not verified.

Verifier: session dec9b511-ed04-4cef-96bd-88d79753b757

# Given · when · then Kind Result Evidence Commit
S1 Given the head commit, when Module checks runs, then contracts' check and test pass: catalog-api v1 is valid OpenAPI 3.1, and each of its examples is what its schema declares automated passed CI run 35447926488 ("Modules", headSha 20d484a…), checkout 5543913 whose tree c4f5647 is the head's. Job contracts, step check: "catalog-api/v1/openapi.yaml: OK", "1 file already formatted", "All checks passed!"; step test: "collected 8 items", "8 passed in 0.11s". Job Module checks: "Changed modules: success. Their checks: success." Local replay: nstack check contracts exit 0, nstack test contracts "8 passed" — the guard, 5 examples, 2 Problem statuses 20d484a
S2 Given a copy of the head where the 404 example of /tools/{toolId} answers status: 200, when nstack check contracts then nstack test contracts run, then the check passes and the test fails, naming that example and the minimum it breaks explored passed Clean copy, line 98 status: 404 → status: 200. nstack check contracts exit 0 ("OK", "All checks passed!"). nstack test contracts exit 1: "AssertionError: ['$.status: 200 is less than the minimum of 400']", "FAILED …[catalog-api/v1/openapi.yaml#/paths/1tools1{toolId}/get/responses/404/content/application~1problem+json/example]", and the status test "assert 200 == 404": "2 failed, 6 passed". Copy discarded 20d484a
S3 Given a copy of the head where a response has lost its required description, when nstack check contracts runs, then it fails explored passed Clean copy, line 90 removed (the 404 response's description). nstack check contracts exit 1: "Validation Error: 'description' is a required property", "On instance['paths']['/tools/{toolId}']['get']['responses']['404']", "FAIL [check] module 'contracts': … exited with 1." Copy discarded 20d484a
S4 Given the head commit, when Fitness functions runs, then the manifests are compliant: contracts declares check and test (M7) automated passed CI run 35447926530 ("Governance", headSha 20d484a…, same tree as the head). Job Fitness functions, step "Manifests, boundaries, skills, plan, hygiene": "Manifests checked: 3", "Manifests: compliant.", Boundaries, Plan and Hygiene "compliant". Local replay: nstack fitness --root . exit 0. Counter-probe on 3f043a2: the two verbs commented out → "FAIL [M7] contracts" twice 20d484a
S5 Given a copy of the head where the 404 example of /tools/{toolId} answers status: 400, when nstack test contracts runs, then it fails, naming that example and both codes explored passed Clean copy, line 98 status: 404 → status: 400. nstack test contracts exit 1: "AssertionError: assert 400 == 404", "FAILED …test_a_problem_says_the_status_its_response_answers[catalog-api/v1/openapi.yaml#/paths/1tools1{toolId}/get/responses/404/content/application~1problem+json/example]", "1 failed, 7 passed"; nstack check contracts stays green on the same mutation. The reverse swap (a 400 example saying 404) fails the same way. Copy discarded 20d484a

Summary

DONE

  • NapkinStack updated from v0.3.1 to v0.4.0, Copier's merge unchanged by hand.
  • contracts declares check (the document's structure, the tests' Python) and test (the
    examples against their schemas), each run before it was declared.
  • The tooling profile names the tools.

VERIFIED

  • Before the adaptation: nstack fitness — M7, twice, on contracts. After: compliant
    (manifests, boundaries, skills, plan, hygiene).
  • nstack check contracts and nstack test contracts green: 8 tests — the 5 examples, the 2
    Problem statuses, and the guard that refuses a suite finding nothing. On copies of the
    module: an example with status: 200 → check green, test red naming it; a 404 example with
    status: 400 → test red, assert 400 == 404, naming it; the ToolId parameter's example
    made invalid → test red naming it; a response with no description → check red. check
    refused the formatting of 20d484a's own code, and yamllint its manifest line of 135
    characters, before it was committed.
  • The project's pre-commit hooks on the three commits; gitleaks over them: no leak; one author,
    napkinstack-agent[bot], each commit carrying its Agent-Session: trailer.
  • nstack pr-scope: one module, over the files budget (22/15).
  • The verifier, beyond the sheet: 7b0cd04 is Copier's merge unchanged by hand — a fresh
    nstack update of main at 6e18b41 gives the same tree (90a45db), only the trailers
    differ; every claim of this description checked against the diff and the runs.
  • A first verification of the sheet on 3f043a2 passed S1 to S4, and found what 20d484a
    fixes: the missing status rule, referencing unpinned, ruff's target version, and
    this description's two commit hashes, swapped. The sheet is run again on the head. nstack pr-check, before this
    description: T1 (the sheet, contracts is of criticality high) and K1 — expected.

ASSUMED

  • A response given by reference ($ref: "#/components/responses/…") escapes the status test:
    its example is checked against its schema, not against a code it does not carry. v1 has
    none and is frozen, and loans reads no response by reference — it would fail, not lie.
  • An example given by reference ($ref, externalValue) is not read by the test, which
    fails on one rather than passing it: catalog-api v1 has none.

NOT VERIFIED

  • Module checks has never run on this repository before this pull request: its first run is
    this one.

RISKS

  • The verifier is an agent with a fresh context and an identifier of its own, launched from
    the author's session — not a separately started session. CI sees no match between them
    (T2); the approver should know it (charter, An agent verifies an agent).
  • test downloads Python 3.13 where uv has none, as the modules' own verbs do.
  • After the merge, the maintainer makes Module checks required on main, then runs
    nstack doctor with a token of their own.

Signals to report

  • I had to look at another module's implementation → a signal of a bad boundary
    (docs/os/02-modules.md §9)
  • A kernel or playbook rule got in my way for no good reason — not the rule, its
    message: between two cycles, K1 says "the project is not framed" and points to
    playbooks/framing.md, while the charter is accepted and only the next cycle is missing.
    Reported to NapkinStack in the validation log.
  • A quality gate blocked without improving quality
  • A rule applied by hand would be worth automating
    → the automation backlog (docs/os/07-governance.md §9)

🤖 Generated with Claude Code

napkinstack-agent Bot and others added 2 commits September 19, 2026 15:57
Agent-Session: d9d08c03-d66a-408a-b9e2-39932ff3130a
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
v0.4.0 no longer ships placeholder verbs: a module that holds more than its description
declares check and test (fitness M7), and contracts/ holds catalog-api v1.

- check: every contract document is valid OpenAPI 3.1 (openapi-spec-validator, pinned),
  and the Python of its tests passes the modules' own ruff rules.
- test: every example a document gives is what its schema declares. loans builds its
  double of catalog from these examples; the check reads the structure, not the examples,
  and a pull request changing only a contract runs this module's verbs alone.

Agent-Session: d9d08c03-d66a-408a-b9e2-39932ff3130a
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@napkinstack-agent
napkinstack-agent Bot requested a review from a team as a code owner September 19, 2026 13:59
@napkinstack-agent napkinstack-agent Bot added over-budget Over the review budget, justified in the pull request (mechanical migration, generation) out-of-cycle Work outside the cycle — an incident, a production defect — justified in the description labels Sep 19, 2026
…complete

From the verifier's review of the sheet:

- A 404 example whose body says 400 passed both verbs, while loans' double answers with
  the response's code and the example's body. RFC 9457 §3.1.3: status is the code of the
  response that carries it. Now a test of its own, seen failing on that example.
- referencing, imported by the test, pinned as catalog pins it; the validator runs on
  Python 3.13 like the rest; ruff targets 3.13, as the modules' requires-python makes it.

Agent-Session: d9d08c03-d66a-408a-b9e2-39932ff3130a
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@napkinstack-agent napkinstack-agent Bot mentioned this pull request Sep 19, 2026
@napkinstack-agent
napkinstack-agent Bot merged commit 85cd486 into main Sep 19, 2026
7 of 9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

out-of-cycle Work outside the cycle — an incident, a production defect — justified in the description over-budget Over the review budget, justified in the pull request (mechanical migration, generation)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant