refactor(governance): dependency pin policy + validation-library decision (#1233 B2.11)

[SisyphusZheng]

Problem

Audit L10 (#1233, stage #1288, umbrella #1155): the repository had no documented policy for exact pins vs caret ranges across its deno.json import maps and workflows, the zod/valibot duality had never been adjudicated, and duplicated generic validation had never been ruled out. Acceptance: a documented pin policy and a single validation-library decision (or an explicit, justified dual decision), recorded in governance docs.

Owner

Implementer, dispatch packet B2.11 (issue #1233), under ADR-0151 Beta.2.

Before

• No governance document named a pin policy; exact pins (vite, @playwright/test, @zag-js/*, urlpattern-polyfill, …) and caret ranges (@std/*, hono, preact, …) coexisted without a stated rule.
• zod and valibot both sat in the root import map and the request-time fixture with no recorded decision on whether the duality was justified or accidental.
• No mechanical assertion kept a schema-validation library out of the published package surface (packages/*/src).

After

• docs/governance/DEPENDENCY_POLICY.md records:
  • Enforcement inventory (§1): one mechanism per layer, one owner each — Actions SHA pins (tools/check-action-pins.ts), CI binaries (version + SHA-256 inline), JSR/npm resolved versions (committed deno.lock + vendor/ + deno install --frozen + git diff --exit-code -- deno.lock), Dependabot (github-actions only, weekly + cooldown), dependency-review-action, validation boundary. No layer had two mechanisms asserting the same policy, so nothing was consolidated (net-reduction satisfied by recording, not merging).
  • Pin policy (§2): the lockfile is the pin; specifier style records update intent. Exact pins where drift must be a deliberate diff (build/test/e2e tooling, widget/runtime libs pinned for e2e/visual stability, the URLPattern polyfill guarding semantic parity with the platform-standard owner); caret ranges for shared platform libraries and fixture recipe libraries. Published-package deps flow verbatim into npm tarballs (tools/publish-npm.ts), so they prefer caret ranges to avoid diamond duplication for consumers.
  • Validation-library decision (§3): explicit dual, justified — zod (/register) and valibot (/subscribe) each appear exactly once in the request-time interop fixture as the executable proof that the ADR-0120 action loop is library-agnostic, gated in three browser engines by fixture:request-time:gate. Neither ships in any published package. Convergence would weaken the interop evidence with no consumer-observable benefit. Boundary rule: packages/*/src imports no schema-validation library. Duplicated generic validation: none found — no repo code re-implements schema validation.
• New mechanical gate validation:boundary-check (tools/check-validation-boundary.ts + test) asserting the §3 boundary rule, registered in the AutoFlow gate registry at ci/release tiers.
• Pointers from docs/governance/PROJECT_WORKFLOW.md and docs/integrations/validation.md.

No dependency version was upgraded, downgraded or restyled; the diff is policy + one boundary gate.

Why-not-second-owner

The retained zod/valibot pair is not a duplicate implementation of a project-owned semantic surface: the canonical owner is the ADR-0120 action protocol (FormData in, fail(422)/redirect out); the two libraries are userland executors retained as the interop proof. Reason: two structurally different schema APIs are what makes the library-agnosticism claim falsifiable. Parity proof: fixture:request-time:gate asserts both routes (422/303 + echo) on Chromium, Firefox and WebKit in CI. No new duplicate-looking implementation is introduced; the new gate asserts a boundary, it does not re-implement one.

Evidence

Against commit 594b48d (branch 1233-dependency-pin-policy, base origin/dev 5ba5a47):

• deno test --allow-read --allow-env tools/check-validation-boundary.test.ts — exit 0 (4 passed; includes the real-tree assertion that no packages/*/src file imports zod/valibot). RED proven first: exit 1 with the checker module absent.
• deno task validation:boundary-check — exit 0.
• deno task test — exit 0 (1788 passed / 0 failed + starter 150 passed / 0 failed).
• deno task pack:dry-run — exit 0.
• deno task package-artifacts:check — exit 0 (5 packages).
• deno fmt --check (touched files) / deno lint — exit 0; deno task lint:markdown — 0 issues.
• deno test tools/autoflow/__tests__/policy.test.ts — 33 passed (registry integrity: every gate resolves to a task, no shared commands).
• deno task docs:check-role-neutral, workflow:check, docs:check-public, docs:check-claims, text-integrity:check, docs:check-strategy, docs:check-current — all exit 0.

Scope

Owned paths only: docs/governance/DEPENDENCY_POLICY.md (new), docs/governance/PROJECT_WORKFLOW.md, docs/integrations/validation.md, tools/check-validation-boundary.ts (new), tools/check-validation-boundary.test.ts (new), tools/autoflow/policy.ts, deno.json (one task entry). No frozen paths touched; no product code changed; no dependency versions changed.

Risk

None material. The new gate is additive and currently green; if a future change legitimately needs a schema library in published source, the gate fails closed and the policy doc must be amended in the same PR — that friction is intentional.

Closes #1233

[cloudflare-workers-and-pages]

Deploying openelement with    Cloudflare Pages

Latest commit:	594b48d
Status:	✅  Deploy successful!
Preview URL:	https://394751e5.lessjs.pages.dev
Branch Preview URL:	https://1233-dependency-pin-policy.lessjs.pages.dev

View logs

[github-actions]

APIError: Insufficient Balance

opencode session  |  github run