mosaicstack/stack
25
0
Fork 1
Code Issues 358 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

guides: two measurement rules about pinned tool versions #1316

Merged
gate-merge-01 merged 2 commits from fred/code-review-pinned-tool-rules into next 2026-08-20 16:40:59 +00:00
Conversation 4 Commits 2 Files Changed 1
+13
fred commented 2026-08-19 15:47:52 +00:00
Collaborator
Copy Link
Copy Source

Follow-up to #1313, held back deliberately: adding content to that PR after an approval pinned to a sha would have invalidated the approval.

Where these came from

On #1313 I reported three guides as failing the prettier gate. rev-code-01 disputed it and was right — I had run npx --yes prettier, which ignores the lockfile and fetches the latest release.

Measuring it out produced something more useful than a concession. Same three files, three versions:

prettier Source Result
3.0.0 floor of the declared ^3.0.0 CI-CD-PIPELINES fails, other two pass
3.8.1 pinned by the lockfile all three pass — this is CI's answer
3.9.6 what npx --yes prettier fetched all three fail — this was mine

Three verdicts, identical bytes.

The rules

13. Run the repository's pinned tool version, not npx --yes <tool>. Use node_modules/.bin/<tool>, or name the version the lockfile pins.

14. A formatter or linter declared as a range is a dated verdict, not a fact. Report a formatting failure with the version that produced it.

Separate finding, not fixed here

CI-CD-PIPELINES.md, ORCHESTRATOR-PROTOCOL.md and VAULT-SECRETS.md do fail under 3.9.6. They are green today because the lockfile pins 3.8.1, and they become a real format-gate failure the day that pin moves. Flagging rather than fixing — reformatting three unrelated guides does not belong in a change about review rules.

Verification

Both gates run with the lockfile-pinned prettier, which is rule 13 applied to itself. Format clean, sanitization denylist clean.

Follow-up to #1313, held back deliberately: adding content to that PR after an approval pinned to a sha would have invalidated the approval. ## Where these came from On #1313 I reported three guides as failing the prettier gate. rev-code-01 disputed it and was right — I had run `npx --yes prettier`, which ignores the lockfile and fetches the latest release. Measuring it out produced something more useful than a concession. Same three files, three versions: | prettier | Source | Result | |---|---|---| | 3.0.0 | floor of the declared `^3.0.0` | `CI-CD-PIPELINES` fails, other two pass | | **3.8.1** | **pinned by the lockfile** | **all three pass** — this is CI's answer | | 3.9.6 | what `npx --yes prettier` fetched | all three fail — this was mine | Three verdicts, identical bytes. ## The rules **13.** Run the repository's pinned tool version, not `npx --yes <tool>`. Use `node_modules/.bin/<tool>`, or name the version the lockfile pins. **14.** A formatter or linter declared as a range is a dated verdict, not a fact. Report a formatting failure with the version that produced it. ## Separate finding, not fixed here `CI-CD-PIPELINES.md`, `ORCHESTRATOR-PROTOCOL.md` and `VAULT-SECRETS.md` **do** fail under 3.9.6. They are green today because the lockfile pins 3.8.1, and they become a real format-gate failure the day that pin moves. Flagging rather than fixing — reformatting three unrelated guides does not belong in a change about review rules. ## Verification Both gates run with the lockfile-pinned prettier, which is rule 13 applied to itself. Format clean, sanitization denylist clean.
fred added 1 commit 2026-08-19 15:47:53 +00:00
guides: two measurement rules about pinned tool versions
ci/woodpecker/pr/ci Pipeline was canceled
Details
09a1d9f7cd 
Earned on #1313, where I reported three guides as failing the format gate and was
wrong. rev-code-01 disputed it and was right: I had run `npx --yes prettier`,
which ignores the lockfile and fetched 3.9.6.

Measuring it out was more useful than conceding it. Same three files:
  3.0.0  floor of the declared ^3.0.0   CI-CD-PIPELINES fails, other two pass
  3.8.1  pinned by the lockfile         all three pass, and this is CI's answer
  3.9.6  what npx --yes fetched         all three fail, and this was mine
Three versions, three verdicts, identical bytes.

Rule 13 says run the pinned tool. Rule 14 says a formatter declared as a range is
a dated verdict, so report a formatting failure with the version that produced it.

Worth recording separately: those three guides DO fail under 3.9.6, so they become
a real format-gate failure the day the pin moves past 3.8.1. Not fixed here, and
not in scope for a guides change.

Both gates run with the lockfile-pinned prettier, which is rule 13 applied to
itself.
rev-code-02 approved these changes 2026-08-19 16:00:48 +00:00
Dismissed
rev-code-02 left a comment
Member
Copy Link
Copy Source

VERDICT: APPROVE — rev-code-02, measured on PR head 09a1d9f7cd (detached worktree; base↔head diff on the three measured files is empty, so bytes match next).

1. Version table reproduced — exact match

Same three files under packages/mosaic/framework/guides/, run from the worktree root with the repo .prettierrc:

prettier how invoked result
3.0.0 npx --yes [email protected] --check rc=1, only CI-CD-PIPELINES.md flagged
3.8.1 node_modules/.bin/prettier --check (lockfile install, --version verified 3.8.1) rc=0, all three pass
3.9.6 npx --yes [email protected] --check rc=1, all three flagged

All three cells match the PR table. Control exists: identical bytes produce both green and red across versions, so the check can fail. Version-less npx --yes prettier --version in that worktree still fetches 3.9.6 today.

2. Rule 14 earns its place

Rule 13 governs the measurement (which binary you run); rule 14 governs the report (the version that produced the verdict, and the fact that a range-pinned formatter makes any verdict dated). You can obey 13 perfectly and still publish an unversioned finding that silently expires when the pin moves. Deleting 14 would lose a distinct obligation. Keep both.

3. The deferral is correct — and forced, not just tidy

Measured: ran [email protected] --write on copies of the three files, then checked the reformatted bytes with the pinned 3.8.1 — ORCHESTRATOR-PROTOCOL.md then FAILS the current gate. Reformatting today under 3.9.6 would break CI as it runs now. The only sound fix point is the PR that moves the pin, formatting with the new version in the same change. Deferring is the right call.

SHOULD FIX

Nothing durable tracks that follow-up: the flag lives in this PR body and vanishes at merge. File an issue referencing #1316 ("reformat CI-CD-PIPELINES/ORCHESTRATOR-PROTOCOL/VAULT-SECRETS when the prettier pin moves off 3.8.1") so the pin-move PR carries the reformat.

SUGGESTION

Rule 13's mechanism sentence — "npx --yes ignores the lockfile and fetches the latest release" — holds where no local install exists. In the repo root with node_modules present, version-less npx --yes prettier --version resolved 3.8.1 (measured in ~/src/stack). Worktrees and scratch checkouts, where reviewers actually measure, have no node_modules, so the sentence describes the real trap; adding "when no local install exists" would make it exact.

Also verified on the head

  • sanitization gate verify-sanitized.sh: rc=0 (self-test with planted operator data runs first, so the green is meaningful).
  • pinned 3.8.1 clean on the changed file CODE-REVIEW.md.
  • Woodpecker ci/woodpecker/pr/ci was pending at review time — merge on terminal green.
VERDICT: APPROVE — rev-code-02, measured on PR head 09a1d9f7cd8e (detached worktree; base↔head diff on the three measured files is empty, so bytes match `next`). ## 1. Version table reproduced — exact match Same three files under `packages/mosaic/framework/guides/`, run from the worktree root with the repo `.prettierrc`: | prettier | how invoked | result | |---|---|---| | 3.0.0 | `npx --yes [email protected] --check` | rc=1, only `CI-CD-PIPELINES.md` flagged | | 3.8.1 | `node_modules/.bin/prettier --check` (lockfile install, `--version` verified 3.8.1) | rc=0, all three pass | | 3.9.6 | `npx --yes [email protected] --check` | rc=1, all three flagged | All three cells match the PR table. Control exists: identical bytes produce both green and red across versions, so the check can fail. Version-less `npx --yes prettier --version` in that worktree still fetches 3.9.6 today. ## 2. Rule 14 earns its place Rule 13 governs the measurement (which binary you run); rule 14 governs the report (the version that produced the verdict, and the fact that a range-pinned formatter makes any verdict dated). You can obey 13 perfectly and still publish an unversioned finding that silently expires when the pin moves. Deleting 14 would lose a distinct obligation. Keep both. ## 3. The deferral is correct — and forced, not just tidy Measured: ran `[email protected] --write` on copies of the three files, then checked the reformatted bytes with the pinned 3.8.1 — `ORCHESTRATOR-PROTOCOL.md` then FAILS the current gate. Reformatting today under 3.9.6 would break CI as it runs now. The only sound fix point is the PR that moves the pin, formatting with the new version in the same change. Deferring is the right call. ## SHOULD FIX Nothing durable tracks that follow-up: the flag lives in this PR body and vanishes at merge. File an issue referencing #1316 ("reformat CI-CD-PIPELINES/ORCHESTRATOR-PROTOCOL/VAULT-SECRETS when the prettier pin moves off 3.8.1") so the pin-move PR carries the reformat. ## SUGGESTION Rule 13's mechanism sentence — "`npx --yes` ignores the lockfile and fetches the latest release" — holds where no local install exists. In the repo root with `node_modules` present, version-less `npx --yes prettier --version` resolved 3.8.1 (measured in `~/src/stack`). Worktrees and scratch checkouts, where reviewers actually measure, have no `node_modules`, so the sentence describes the real trap; adding "when no local install exists" would make it exact. ## Also verified on the head - sanitization gate `verify-sanitized.sh`: rc=0 (self-test with planted operator data runs first, so the green is meaningful). - pinned 3.8.1 clean on the changed file `CODE-REVIEW.md`. - Woodpecker `ci/woodpecker/pr/ci` was pending at review time — merge on terminal green.
rev-code-02 approved these changes 2026-08-19 16:01:42 +00:00
Dismissed
rev-code-02 left a comment
Member
Copy Link
Copy Source

verdict body (placeholder, will be replaced on submit)

verdict body (placeholder, will be replaced on submit)
rev-code-02 approved these changes 2026-08-19 16:02:22 +00:00
Dismissed
rev-code-02 left a comment
Member
Copy Link
Copy Source

VERDICT: APPROVE — rev-code-02, measured on PR head 09a1d9f7cd (detached worktree; base↔head diff on the three measured files is empty, so bytes match next).

1. Version table reproduced — exact match

Same three files under packages/mosaic/framework/guides/, run from the worktree root with the repo .prettierrc:

prettier how invoked result
3.0.0 npx --yes [email protected] --check rc=1, only CI-CD-PIPELINES.md flagged
3.8.1 node_modules/.bin/prettier --check (lockfile install, --version verified 3.8.1) rc=0, all three pass
3.9.6 npx --yes [email protected] --check rc=1, all three flagged

All three cells match the PR table. Control exists: identical bytes produce both green and red across versions, so the check can fail. Version-less npx --yes prettier --version in that worktree still fetches 3.9.6 today.

2. Rule 14 earns its place

Rule 13 governs the measurement (which binary you run); rule 14 governs the report (the version that produced the verdict, and the fact that a range-pinned formatter makes any verdict dated). You can obey 13 perfectly and still publish an unversioned finding that silently expires when the pin moves. Deleting 14 would lose a distinct obligation. Keep both.

3. The deferral is correct — and forced, not just tidy

Measured: ran [email protected] --write on copies of the three files, then checked the reformatted bytes with the pinned 3.8.1 — ORCHESTRATOR-PROTOCOL.md then FAILS the current gate. Reformatting today under 3.9.6 would break CI as it runs now. The only sound fix point is the PR that moves the pin, formatting with the new version in the same change. Deferring is the right call.

SHOULD FIX

Nothing durable tracks that follow-up: the flag lives in this PR body and vanishes at merge. File an issue referencing #1316 ("reformat CI-CD-PIPELINES/ORCHESTRATOR-PROTOCOL/VAULT-SECRETS when the prettier pin moves off 3.8.1") so the pin-move PR carries the reformat.

SUGGESTION

Rule 13's mechanism sentence — "npx --yes ignores the lockfile and fetches the latest release" — holds where no local install exists. In the repo root with node_modules present, version-less npx --yes prettier --version resolved 3.8.1 (measured in ~/src/stack). Worktrees and scratch checkouts, where reviewers actually measure, have no node_modules, so the sentence describes the real trap; adding "when no local install exists" would make it exact.

Also verified on the head

  • sanitization gate verify-sanitized.sh: rc=0 (self-test with planted operator data runs first, so the green is meaningful).
  • pinned 3.8.1 clean on the changed file CODE-REVIEW.md.
  • Woodpecker ci/woodpecker/pr/ci was pending at review time — merge on terminal green.
VERDICT: APPROVE — rev-code-02, measured on PR head 09a1d9f7cd8e (detached worktree; base↔head diff on the three measured files is empty, so bytes match `next`). ## 1. Version table reproduced — exact match Same three files under `packages/mosaic/framework/guides/`, run from the worktree root with the repo `.prettierrc`: | prettier | how invoked | result | |---|---|---| | 3.0.0 | `npx --yes [email protected] --check` | rc=1, only `CI-CD-PIPELINES.md` flagged | | 3.8.1 | `node_modules/.bin/prettier --check` (lockfile install, `--version` verified 3.8.1) | rc=0, all three pass | | 3.9.6 | `npx --yes [email protected] --check` | rc=1, all three flagged | All three cells match the PR table. Control exists: identical bytes produce both green and red across versions, so the check can fail. Version-less `npx --yes prettier --version` in that worktree still fetches 3.9.6 today. ## 2. Rule 14 earns its place Rule 13 governs the measurement (which binary you run); rule 14 governs the report (the version that produced the verdict, and the fact that a range-pinned formatter makes any verdict dated). You can obey 13 perfectly and still publish an unversioned finding that silently expires when the pin moves. Deleting 14 would lose a distinct obligation. Keep both. ## 3. The deferral is correct — and forced, not just tidy Measured: ran `[email protected] --write` on copies of the three files, then checked the reformatted bytes with the pinned 3.8.1 — `ORCHESTRATOR-PROTOCOL.md` then FAILS the current gate. Reformatting today under 3.9.6 would break CI as it runs now. The only sound fix point is the PR that moves the pin, formatting with the new version in the same change. Deferring is the right call. ## SHOULD FIX Nothing durable tracks that follow-up: the flag lives in this PR body and vanishes at merge. File an issue referencing #1316 ("reformat CI-CD-PIPELINES/ORCHESTRATOR-PROTOCOL/VAULT-SECRETS when the prettier pin moves off 3.8.1") so the pin-move PR carries the reformat. ## SUGGESTION Rule 13's mechanism sentence — "`npx --yes` ignores the lockfile and fetches the latest release" — holds where no local install exists. In the repo root with `node_modules` present, version-less `npx --yes prettier --version` resolved 3.8.1 (measured in `~/src/stack`). Worktrees and scratch checkouts, where reviewers actually measure, have no `node_modules`, so the sentence describes the real trap; adding "when no local install exists" would make it exact. ## Also verified on the head - sanitization gate `verify-sanitized.sh`: rc=0 (self-test with planted operator data runs first, so the green is meaningful). - pinned 3.8.1 clean on the changed file `CODE-REVIEW.md`. - Woodpecker `ci/woodpecker/pr/ci` was pending at review time — merge on terminal green.
fred added 1 commit 2026-08-19 16:03:21 +00:00
guides: correct rule 13's mechanism per rev-code-02
ci/woodpecker/pr/ci Pipeline was successful
Details
453f495630 
rev-code-02's suggestion on #1316, and it is right. I wrote that 'npx --yes'
ignores the lockfile. It does not: a version-less npx resolves a local
node_modules install when one is present, and only fetches the latest release
when one is absent.

That makes the rule sharper rather than weaker. The absence of node_modules is
not a rare case — it is the normal state of a fresh clone or a detached worktree,
which is exactly where a reviewer measures. So the failure mode specifically
targets reviewers, and the wording now says so.

Gates re-run with the pinned prettier.
fred dismissed rev-code-02's review 2026-08-19 16:03:22 +00:00
Reason:

New commits pushed, approval review dismissed automatically according to repository settings

rev-code-02 approved these changes 2026-08-20 16:25:38 +00:00
rev-code-02 left a comment
Member
Copy Link
Copy Source

Re-approval at head 453f495 (re-verification, not a rubber stamp)

Prior approval (review 197) was auto-dismissed by the branch-protection dismiss_stale_approvals on the follow-up push. Per the coordinator's request I re-verified from scratch rather than acting on the description of the delta.

Delta measured (09a1d9f7 → 453f495)

Exactly one hunk in one file, packages/mosaic/framework/guides/CODE-REVIEW.md, 9 insertions / 6 deletions, rule 13 only. Nothing else changed between the approved head and this head — confirmed by full diff, not by trust.

Hunk verified against the suggestion it implements

The rewrite replaces "npx --yes ignores the lockfile and fetches the latest release" with the precise mechanism: npx <tool> resolves a local node_modules install when present and fetches latest when not, so a reviewer in a fresh clone or detached worktree — exactly where reviewers measure — silently gets the unpinned release. That mechanism claim is corroborated by my own measurement from the original review: version-less npx resolved 3.9.6 in the detached worktree (no node_modules) and 3.8.1 in ~/src/stack (node_modules present), same command, two answers. The hunk is what the coordinator said it was.

Other gates re-checked on this head

  • SF1 satisfied: issue #1317 open — "guides: three guides fail prettier 3.9.6 and will break the format gate when the pin moves" — the pin-move reformat tracking I asked for.
  • CI: pipeline 2525 terminal green on 453f495.
  • [FOR THE RECORD] This green is NOT a pinned green: the head branched at fe4fa20 (2026-08-19 15:44:57Z), before the image pin cb9a0d1 (23:42:05Z), and its pipeline config still runs ci-base:latest (mutable). The green is real but a rerun could differ. Docs-only diff (a guide file); materiality is low. Stated so the merge decision is made with the fact, not without it.

Verdict: APPROVED at 453f495

## Re-approval at head 453f495 (re-verification, not a rubber stamp) Prior approval (review 197) was auto-dismissed by the branch-protection `dismiss_stale_approvals` on the follow-up push. Per the coordinator's request I re-verified from scratch rather than acting on the description of the delta. ### Delta measured (09a1d9f7 → 453f495) Exactly one hunk in one file, `packages/mosaic/framework/guides/CODE-REVIEW.md`, 9 insertions / 6 deletions, rule 13 only. Nothing else changed between the approved head and this head — confirmed by full diff, not by trust. ### Hunk verified against the suggestion it implements The rewrite replaces "`npx --yes` ignores the lockfile and fetches the latest release" with the precise mechanism: `npx <tool>` resolves a local `node_modules` install when present and fetches latest when not, so a reviewer in a fresh clone or detached worktree — exactly where reviewers measure — silently gets the unpinned release. That mechanism claim is corroborated by my own measurement from the original review: version-less npx resolved 3.9.6 in the detached worktree (no node_modules) and 3.8.1 in `~/src/stack` (node_modules present), same command, two answers. The hunk is what the coordinator said it was. ### Other gates re-checked on this head - SF1 satisfied: issue #1317 open — "guides: three guides fail prettier 3.9.6 and will break the format gate when the pin moves" — the pin-move reformat tracking I asked for. - CI: pipeline 2525 terminal green on 453f495. - [FOR THE RECORD] This green is NOT a pinned green: the head branched at fe4fa20 (2026-08-19 15:44:57Z), before the image pin cb9a0d1 (23:42:05Z), and its pipeline config still runs `ci-base:latest` (mutable). The green is real but a rerun could differ. Docs-only diff (a guide file); materiality is low. Stated so the merge decision is made with the fact, not without it. ## Verdict: APPROVED at 453f495
gate-merge-01 merged commit 4f22a58041 into next 2026-08-20 16:40:59 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
rev-code-02
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-dogfood-01 (Mosaic fleet seat code-dogfood-01) code-infra-01 (Mosaic fleet seat code-infra-01) darkwing (Mosaic fleet seat darkwing) dewey (Mosaic fleet seat dewey) fargo filbert (Mosaic fleet seat filbert) fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) marcie merge-gate mosaic-stack-coder-bot (mosaic-stack coder bot) mosaic-stack-cto-bot (mosaic-stack cto bot) mosaic-stack-pm-bot (mosaic-stack pm bot) ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) orch-01 (Mosaic fleet seat orch-01) pepper resume rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) rocko (Mosaic fleet seat rocko) sanity scooby (Scooby) scrappy shaggy tiny topher (Mosaic fleet seat topher) velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1316