Skip to content

catalog, loans — the lock committed, and every uv run refuses a stale one - #33

Merged
napkinstack-agent[bot] merged 4 commits into
mainfrom
modules/uv-lock
Sep 19, 2026
Merged

napkinstack-agent[bot] merged 4 commits into
mainfrom
modules/uv-lock

Conversation

@napkinstack-agent

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

Copy link
Copy Markdown
Contributor

catalog, loans — the lock committed, and every uv run refuses a stale one

Part of the validation log, #1 (NapkinStack M10h) — D34 #10: uv.lock neither committed nor
ignored.


Module

modules/catalog and modules/loans.

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

The same mechanical fix in both modules, which share the stack of the charter (C2): each
commits the lock uv already writes, and runs its verbs against it. Split in two, the second
pull request would repeat the first line for line. No contract is touched.

Deliverable

Out of cycle: D34 #10, a defect of the rehearsal found by NapkinStack M9 — the modules' resolved dependencies are not reproducible; cycle 1 is closed and no cycle is framed after it.

What it changes

Both modules pin their direct dependencies (==), not what those pull in: starlette,
pydantic, anyio and the rest float. uv run wrote a uv.lock in each module on every
workstation, and nobody committed it or ignored it. A page verified at a phone's width is
evidence only if the same versions answer in CI and on a workstation.

  • modules/catalog/uv.lock (57 packages) and modules/loans/uv.lock (35), from uv lock.
  • Every uv run of the verbs runs --locked (7 of them): a pyproject.toml changed without
    its lock is refused — uv names the fix, uv lock — rather than re-locked in CI and thrown
    away with the runner.
  • No verb uses --with any more. uv run --locked --with X resolves X in a layer of its
    own, outside the lock, and says nothing. The tools the verbs need are dependency groups,
    resolved in uv.lock with the rest: test in both modules, e2e in loans (catalog
    already had one).
  • test, e2e and bootstrap run --exact. uv run adds to an environment and never
    removes; in CI the verbs share one, so a verb could pass on a package only another group
    brings. Now each passes on its own group or not at all.
  • Each module carries a .python-version, 3.13 — the charter's Python (C2). Without
    it uv takes the newest interpreter it has: CI ran 3.14.7.
  • catalog's README and two docstrings run --locked; both AGENTS.md name the three traps.

Since the first verification

The sheet was run on 3b2e9b5 by a verifier session (dec9b511-…). S1 to S4 passed, and
the run found what they did not ask: loans' test and e2e imported 10 and 8 packages the
lock does not hold (catalog's test matched its lock by coincidence of dates), CI's Python
was 3.14.7, and three documented commands lacked --locked. Fixed in 017f55f; S5 and S6
are the scenarios that would have caught it. The branch was rebased on 951b390 (#32) at the
same time.

A second verifier session (b15a829f-…) passed S1 to S6 on 017f55f and noted that in CI
loans' e2e could still import 5 packages only its test group brings — every one locked,
but a verb proven green on another group's packages. Fixed in 3d4ff7f with --exact, with
the wording it also caught: check never reads the lock.

A third (645beb1b-…) passed S1 to S6 on 3d4ff7f and found the traps in AGENTS.md naming
the right remedies with the wrong mechanisms: uv prefers its managed interpreters rather
than the newest it finds — CI got 3.14.7 because the runner's own 3.12 is below
requires-python — and an inexact uv run does replace a package at another version, it
only never removes an extraneous one. Fixed in 905adfc, AGENTS.md only. The sheet below
is the fourth run (55e90888-…), on 905adfc: S1 to S6 passed, notes only.

Oracle

  • The success criterion was written before the implementation — the verbs pass on
    the locked versions; a stale lock is refused; every package a verb's interpreter sees
    is in the lock, at its version; the interpreter is 3.13
  • It was seen failing, for the right reason — a pin of loans changed without
    uv lock: nstack test loans refused, "To update the lockfile, run uv lock";
    on 3b2e9b5, loans' test environment saw 10 distributions absent from its lock
    (pytest, pluggy, jsonschema, rpds-py…) and e2e 8; without .python-version,
    uv run --python-preference system picks 3.14.7 on a workstation that has both; in one
    environment, loans' e2e after its test saw 33 distributions, jsonschema among
    them, against the 28 its group prescribes
  • It passes now — 0 distributions outside the lock in each of the 5 environments; 3.13.15;
    with --exact, 28 and no jsonschema

Kind of oracle: other: the modules' own verbs, locked; the distributions each verb's interpreter lists (importlib.metadata) compared with uv.lock


Review budget

  • Lines changed (excluding generated): 75 — the two locks, 1,780 lines, are generated
  • Files touched: 11 (13 with the locks)
  • Within budget
  • ⚠️ Over budget — label required, justification: <generation, mechanical migration,
    mass rename…>

Contracts

  • No contract affected
  • 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

  • Oracle green
  • Lint, format, types — both modules' check
  • Unit tests — both modules' test
  • Build — nothing is built
  • Contract tests (when there is a contract) — loans' consumer side, in its test
  • Fitness functions
  • Integration tests (per risk)
  • Security analysis — the project's hooks, gitleaks
  • Accessibility (when there is UI) — no page changes
  • E2E on critical journeys (criticality high and above) — both modules' e2e, locked
  • Observability added (criticality high and above)
  • Rollback verified (criticality critical)
  • Affected documentation updated — catalog's README, app.py and contract_double.py
    run --locked; both AGENTS.md, Known traps
  • 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 55e90888-0b84-49ee-9a6a-76c904784237

# Given · when · then Kind Result Evidence Commit
S1 Given the head commit, when Module checks runs, then catalog passes bootstrap, check, test and e2e, and loans — which declares no bootstrap and installs its browser in e2e — passes check, test and e2e; every uv run with --locked, none with --with, and test, e2e and bootstrap with --exact automated passed Modules run 35462191700, Module checks success. It ran on merge dfbbc2b, whose tree 31a8a9f is the head's tree. catalog: bootstrap ok, check ok, test 8 passed, e2e 7 passed and 2 subtests passed. loans: "bootstrap not declared", check ok, test 15 passed, e2e (browser install then pytest) 4 passed. All 5 logged uv run command lines have --locked --exact --group …, and none has --with 905adfc
S2 Given a copy of the head where a pin of modules/loans/pyproject.toml changes without uv lock, when nstack test loans runs, then it is refused and uv names uv lock as the fix explored passed Changed httpx==0.28.1 to 0.28.0, then ran uvx --from napkinstack==0.4.0 nstack test loans: rc=1, error: The lockfile at uv.lock needs to be updated, but --locked was provided. and hint: To update the lockfile, run uv lock. nstack e2e loans was refused the same way, as was test loans with only the e2e group's playwright pin changed. nstack check loans still passes (rc=0). loans/uv.lock sha256 ff0f7b31… is unchanged and pyproject.toml was restored (bfdbcee9…) 905adfc
S3 Given a fresh clone of the head, when each module's environment is created from its lock (uv sync --locked), then every installed version is the one its uv.lock records explored passed Ran UV_PROJECT_ENVIRONMENT=<new dir> uv sync --locked in each module, once without and once with --all-groups. catalog installed 16 (55 with all groups) and loans 20 (33). I listed each environment's distributions with its own interpreter (importlib.metadata): 0 are missing from the lock, 0 have another version, and the set equals the closure computed from uv.lock. uv pip freeze equals uv export --locked --all-groups except colorama, which is win32 only. CPython 3.13.15 905adfc
S4 Given loans locked, when its test runs in CI, then catalog is neither importable nor imported (charter C2.2, unchanged) automated passed evidence-loans, test-run.json: collected 15, failed 0, catalog_importable false, catalog_imported false. isolation.json (e2e) is also false/false and records catalog_base_url_configured false. modules/loans/uv.lock has no catalog package 905adfc
S5 Given a fresh clone of the head and a new environment per verb, when the interpreter of catalog's test and e2e, and of loans' test and e2e, lists the distributions it can import, then each one — the module aside — is in that module's uv.lock, at the version it records explored passed Gave each verb its own UV_PROJECT_ENVIRONMENT and ran it through nstack 0.4.0. All passed (catalog test 8, e2e 7 and 2 subtests; loans test 15, e2e 4). Then each environment's interpreter listed its distributions: catalog test 21, catalog e2e 55, loans test 30, loans e2e 28 (and catalog bootstrap 55). In every case 0 are outside uv.lock, 0 are at another version, and the set is exactly the lock's closure of the project plus that verb's group. Listing from inside uv run --locked --exact --group <g> python gave the same result. The interpreter was CPython 3.13.15 each time 905adfc
S6 Given the head commit, when Module checks runs, then every uv run of catalog and loans uses CPython 3.13, the charter's (C2), and not the newest the runner can get automated passed In run 35462191700, catalog's bootstrap and loans' test each log Downloading cpython-3.13.15, Using CPython 3.13.15 and Creating virtual environment at: .venv. Neither job selects another interpreter or re-creates .venv. For contrast, before the pin run 35453717121 (3b2e9b5) downloaded and used CPython 3.14.7; the runner's own Python is 3.12.3 905adfc

Summary

DONE

  • Both modules' locks committed; every uv run of their verbs --locked, none --with;
    test, e2e and bootstrap --exact.
  • The verbs' tools in dependency groups; .python-version 3.13 in each module; the
    documented commands locked; the two traps in both AGENTS.md.

VERIFIED

  • Locally, from deleted environments, every verb of both modules on the head through
    nstack 0.4.0, in CI's order and one environment per module as CI has: catalog
    bootstrap, check, test 8 passed ("Uninstalled 34 packages", the e2e group's), e2e
    7 passed and 2 subtests; loans check, test 15 passed, e2e 4 passed ("Uninstalled 5
    packages"
    , the test group's); "Using CPython 3.13.15"; both locks unchanged.
  • A stale lock refused, a pin of loans' test group this time; the lock's SHA-256 unchanged.
  • loans' test-run.json: 15 collected, 0 failed, catalog_importable false,
    catalog_imported false.
  • nstack fitness compliant; nstack pr-scope: 2 modules (P1 → cross-module), 75/400
    lines, 11/15 files. The project's hooks; gitleaks over the branch's commits; one author,
    napkinstack-agent[bot], each commit with its Agent-Session: trailer — two author
    sessions, d9d08c03-… and 26f79b64-…, over four commits; gitleaks over the whole
    history in CI.
  • By the first verifier, on 3b2e9b5: CI's uv (0.12.17) reads a lock written by 0.12.14.

ASSUMED

  • Nothing.

NOT VERIFIED

  • By any automated run: the uv run --locked wrappers of catalog's two documented start
    commands (README). The scenarios start the same invocation from the e2e interpreter, and
    CI never runs the run verb. Run by hand by the fourth verifier on 905adfc: GET / 200,
    the double's GET /tools 200. The README's checked on every run predates this pull
    request; reported to the log.

RISKS

  • A dependency bump now takes two files, pyproject.toml and uv.lock: the price of the
    same versions everywhere.
  • --locked makes CI depend on uv's version, which setup-uv does not pin (the latest,
    0.12.17; the locks were written by 0.12.14): a uv release that writes locks differently
    would turn both modules red with no change here. The workflow is NapkinStack's; reported
    to its register rather than patched in this project.
  • The verifiers are subagents of the author sessions, each with a fresh context, the brief
    alone and an identifier it generated; T2 compares names and cannot see that link. The
    approver decides whether that is independent enough — as on NapkinStack v0.3.1 -> v0.4.0, and the contracts module's check and test #31.
  • Out of scope, reported to the log: contracts' test runs uvx --from pytest==9.1.1 --with … — the same unlocked layer, with no project of its own to lock.
  • Reported to the log, not changed here: catalog's run verb is --locked but not
    --exact, so on a workstation it inherits whatever group ran last (the page runs on its
    own 16 packages in a fresh environment); loans' test records catalog_importable but
    does not fail on it — the hard assertion is in its e2e, and S4 reads the record.

Signals to report

  • I had to look at another module's implementation → a signal of a bad boundary
  • A kernel or playbook rule got in my way for no good reason
  • A quality gate blocked without improving quality
  • A rule applied by hand would be worth automating — --locked and no --with in a
    module's uv run verbs is checked by nobody; the sheet's S5 is its manual form

🤖 Generated with Claude Code

@napkinstack-agent napkinstack-agent Bot added cross-module PR touching several modules, justified in the description out-of-cycle Work outside the cycle — an incident, a production defect — justified in the description labels Sep 19, 2026
@napkinstack-agent
napkinstack-agent Bot requested review from a team as code owners September 19, 2026 16:03
@napkinstack-agent
napkinstack-agent Bot marked this pull request as draft September 19, 2026 16:11
@napkinstack-agent

Copy link
Copy Markdown
Contributor Author

Back to draft: the verifier found that uv run --locked --with … resolves the --with packages outside the lock — loans' test and e2e still float ten transitive packages — and that CI runs Python 3.14 where the charter says 3.13. To be fixed (dependency groups run --locked --group, a .python-version, the README's commands) and verified again on the new head before approval.

napkinstack-agent Bot and others added 2 commits September 19, 2026 20:12
Both modules pinned their direct dependencies but not what those pull in: uv.lock was
neither committed nor ignored (D34 #10). A page verified at a phone's width is evidence
only if the same versions answer in CI and on a workstation.

- modules/catalog/uv.lock (57 packages) and modules/loans/uv.lock (21), from uv lock.
- Every uv run of the verbs runs --locked: a pyproject.toml changed without its lock is
  refused, uv naming the fix (uv lock), rather than re-locked silently in CI.

Agent-Session: d9d08c03-d66a-408a-b9e2-39932ff3130a
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…Python

The verifier's run of the sheet on 3b2e9b5 found what --locked does not cover:

- `uv run --locked --with X` resolves X in a layer of its own, outside uv.lock. loans'
  test and e2e saw 10 and 8 packages the lock does not hold; catalog's test matched its
  lock by coincidence. The tools move into dependency groups — test in both modules, e2e
  in loans — resolved in uv.lock, and the verbs run --group. loans' lock: 21 -> 35.
- CI ran CPython 3.14.7, the charter says 3.13 (C2). Each module carries a
  .python-version, uv's convention: without it, uv picks the newest interpreter it has.
- catalog's README and two docstrings showed `uv run` without --locked.
- Both AGENTS.md name the two traps.

Agent-Session: 26f79b64-9fc9-4b2b-9354-485dcc9cda58
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
From the second verification, on 017f55f:

- `uv run` adds to an environment and never removes. In CI the verbs share one, so
  loans' e2e could import what only the test group brings (jsonschema and 4 more), and
  catalog's test ran on the 55 packages bootstrap installed. test, e2e and bootstrap
  now run --exact: a verb passes on its own group or not at all.
- Both AGENTS.md said a stale pin is refused by every verb: not by check, which runs
  ruff through uvx and never reads the lock.

Agent-Session: 26f79b64-9fc9-4b2b-9354-485dcc9cda58
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@napkinstack-agent napkinstack-agent Bot changed the title catalog, loans — the lock committed, and every verb refuses a stale one catalog, loans — the lock committed, and every uv run refuses a stale one Sep 19, 2026
From the third verification, on 3d4ff7f: the AGENTS.md traps named the right remedies
with the wrong mechanisms.

- Without .python-version, uv does not take the newest interpreter it finds: it prefers
  its managed ones. CI got 3.14.7 because the runner's own Python, 3.12, is below
  requires-python, so uv downloaded the newest.
- An inexact uv run does replace a package locked at another version; what it never
  removes is an extraneous one.

catalog's traps keep the blank line between bullets the list already had.

Agent-Session: 26f79b64-9fc9-4b2b-9354-485dcc9cda58
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@napkinstack-agent
napkinstack-agent Bot marked this pull request as ready for review September 19, 2026 18:58
@napkinstack-agent
napkinstack-agent Bot merged commit 87bb76b into main Sep 19, 2026
8 of 10 checks passed
@napkinstack-agent napkinstack-agent Bot mentioned this pull request Sep 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cross-module PR touching several modules, justified in the description out-of-cycle Work outside the cycle — an incident, a production defect — justified in the description

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant