Repository navigation
NapkinStack v0.3.1 -> v0.4.0, and the contracts module's check and test - #31
Merged
Merged
Conversation
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>
…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>
Open
napkinstack-admin
approved these changes
Sep 19, 2026
16 of 29 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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, outsideevery module.
cross-modulelabel is required, justification belowDeliverable
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 updatefrom v0.3.1 to v0.4.0, merged by Copier with no conflict(commit
7b0cd04, unchanged by hand): the requiredModule checks, the engine installedfrom the registry by
.nstack/install-engine.sh, the handbook and the kernel as v0.4.0 shipsthem. v0.4.0 no longer ships placeholder verbs, so
contracts/, which holdscatalog-apiv1,is asked for its own (fitness M7).
The adaptation (commits
3f043a2and20d484a), in the stack of the charter (C2: Python 3.13 throughuv, pytest, ruff), every tool pinned:check— every contract document is valid OpenAPI 3.1 (openapi-spec-validator), and thePython of its tests passes the modules' own ruff rules (
contracts/ruff.toml, copied frommodules/*/pyproject.toml).test— every example a document gives is what its schema declares.loansbuilds itsdouble of
catalogfrom these examples (catalogue_double.py): an example that breaks itsschema is a double that lies to every test run against it. The check reads the structure
only — an example with
status: 200in aProblem, whose minimum is 400, passes it — anda pull request that changes only a contract document runs this module's verbs alone. And a
Problemexample says the status its response answers (RFC 9457 §3.1.3): the double answerswith 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. TheContract compatibilityrow staysempty until
commands.compatis declared, in a pull request of its own (V1 reads the proofas merged).
Oracle
contracts/after the update; the test's criterion, each example against its schemadocument with a broken example (below, S2)
Kind of oracle: contract test · fitness function
Review budget
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
catalog-apiv1 is unchanged; only the module that holds itgains its verbs
nstack compatproving itonce the version is consumed or stable
removal date set
Definition of Done
checktestmodules', untouched
Test sheet
Verifier: session dec9b511-ed04-4cef-96bd-88d79753b757
Module checksruns, thencontracts'checkandtestpass:catalog-apiv1 is valid OpenAPI 3.1, and each of its examples is what its schema declarescontracts, stepcheck: "catalog-api/v1/openapi.yaml: OK", "1 file already formatted", "All checks passed!"; steptest: "collected 8 items", "8 passed in 0.11s". JobModule checks: "Changed modules: success. Their checks: success." Local replay:nstack check contractsexit 0,nstack test contracts"8 passed" — the guard, 5 examples, 2 Problem statuses/tools/{toolId}answersstatus: 200, whennstack check contractsthennstack test contractsrun, then the check passes and the test fails, naming that example and the minimum it breaksstatus: 404→status: 200.nstack check contractsexit 0 ("OK", "All checks passed!").nstack test contractsexit 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 discardeddescription, whennstack check contractsruns, then it failsdescription).nstack check contractsexit 1: "Validation Error: 'description' is a required property", "On instance['paths']['/tools/{toolId}']['get']['responses']['404']", "FAIL [check] module 'contracts': … exited with 1." Copy discardedFitness functionsruns, then the manifests are compliant:contractsdeclarescheckandtest(M7)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 on3f043a2: the two verbs commented out → "FAIL [M7] contracts" twice/tools/{toolId}answersstatus: 400, whennstack test contractsruns, then it fails, naming that example and both codesstatus: 404→status: 400.nstack test contractsexit 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 contractsstays green on the same mutation. The reverse swap (a 400 example saying 404) fails the same way. Copy discardedSummary
DONE
contractsdeclarescheck(the document's structure, the tests' Python) andtest(theexamples against their schemas), each run before it was declared.
VERIFIED
nstack fitness— M7, twice, oncontracts. After: compliant(manifests, boundaries, skills, plan, hygiene).
nstack check contractsandnstack test contractsgreen: 8 tests — the 5 examples, the 2Problemstatuses, and the guard that refuses a suite finding nothing. On copies of themodule: an example with
status: 200→ check green, test red naming it; a 404 example withstatus: 400→ test red,assert 400 == 404, naming it; theToolIdparameter's examplemade invalid → test red naming it; a response with no
description→ check red.checkrefused the formatting of
20d484a's own code, and yamllint its manifest line of 135characters, before it was committed.
napkinstack-agent[bot], each commit carrying itsAgent-Session:trailer.nstack pr-scope: one module, over the files budget (22/15).7b0cd04is Copier's merge unchanged by hand — a freshnstack updateofmainat 6e18b41 gives the same tree (90a45db), only the trailersdiffer; every claim of this description checked against the diff and the runs.
3f043a2passed S1 to S4, and found what20d484afixes: the missing status rule,
referencingunpinned, ruff's target version, andthis description's two commit hashes, swapped. The sheet is run again on the head.
nstack pr-check, before thisdescription: T1 (the sheet,
contractsis of criticality high) and K1 — expected.ASSUMED
$ref: "#/components/responses/…") escapes the status test:its example is checked against its schema, not against a code it does not carry.
v1hasnone and is frozen, and
loansreads no response by reference — it would fail, not lie.$ref,externalValue) is not read by the test, whichfails on one rather than passing it:
catalog-apiv1 has none.NOT VERIFIED
Module checkshas never run on this repository before this pull request: its first run isthis one.
RISKS
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).
testdownloads Python 3.13 whereuvhas none, as the modules' own verbs do.Module checksrequired onmain, then runsnstack doctorwith a token of their own.Signals to report
(
docs/os/02-modules.md§9)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.
→ the automation backlog (
docs/os/07-governance.md§9)🤖 Generated with Claude Code