chore/deps-hygiene — dependency-shape tooling (Group 2 of release/jsr-readiness)

[rickylabs]

Group 2 sub-PR of the release/jsr-readiness umbrella (#53). Dependency-shape enforcement tooling + deno task hygiene — does NOT restructure the catalog.

Scope (5 deliverables): (1) JSR-version centralization scanner; (2) npm catalog-compliance scanner; (3) file:/link: audit; (4) deno task prune; (5) thin wrapper over native deno bump-version. Scanners land report-only then flip to FAIL, wired into ci + arch:check.

Catalog premise (corrected): the catalog IS live — members declare npm deps as catalog: in their package.json (Deno 2.8 protocol), resolved by the root deno.json catalog. See drift D-G2-2. The npm-compliance scanner enforces that live invariant.

Plan & Design (ready for the Plan-Gate):

• .llm/tmp/run/chore-deps-hygiene--deps/research.md
• .llm/tmp/run/chore-deps-hygiene--deps/plan.md
• .llm/tmp/run/chore-deps-hygiene--deps/worklog.md (## Design)

Status: Draft. Awaiting PLAN-EVAL (OpenHands / minimax M3, separate session) before any implementation slice (WSL Codex, daemon-attached). Merges --no-ff into the umbrella on PASS.

🤖 Generated with Claude Code

[rickylabs]

@openhands-agent model=openrouter/minimax/minimax-m3 output=pr-comment iterations=800 use harness

ROLE: PLAN-EVAL (plan-gate evaluator) for the chore/deps-hygiene group of the release/jsr-readiness umbrella. You are a SEPARATE evaluator session — do NOT implement, edit framework code, restructure the catalog, or rewrite the plan. Judge the plan only.

Read first (authoritative protocol):

• .llm/harness/evaluator/plan-protocol.md
• .llm/harness/gates/plan-gate.md
• .llm/harness/evaluator/verdict-definitions.md

Then read the run (this PR's branch, chore/deps-hygiene):

• .llm/tmp/run/chore-deps-hygiene--deps/research.md
• .llm/tmp/run/chore-deps-hygiene--deps/plan.md
• .llm/tmp/run/chore-deps-hygiene--deps/worklog.md (especially the ## Design section)
• .llm/tmp/run/chore-deps-hygiene--deps/drift.md (note: D-G2-1 is SUPERSEDED by D-G2-2 — read D-G2-2)
• the relevant archetype profile + .llm/harness/debt/arch-debt.md

Task (follow plan-protocol.md exactly):

1. Walk the Plan-Gate checklist box-by-box; mark each pass/fail with concrete evidence.
2. Open-decision sweep: every open question in research.md must be RESOLVED or explicitly deferred with rationale.
3. Confirm the slice list is ordered, each slice is small (single concern, < ~30 LOC), and each names its proving gate + the files it touches.
4. CRITICAL load-bearing spot-check for this group — drift entry D-G2-2 asserts the npm catalog IS live: workspace members declare npm deps as a catalog: value in their package.json (the Deno 2.8 catalog: protocol), resolved against the root deno.json catalog block — NOT via member deno.json. Verify this directly in the tree: grep package.json under plugins/* and packages/* for dependency values equal to catalog:, and confirm the root deno.json catalog block defines those versions. Then confirm the planned npm-catalog-compliance scanner enforces that LIVE invariant (flagging inline npm: pins where a catalog: ref is required — e.g. npm:amqplib@^0.10.3 in the queue adapter — and stale catalog entries). Confirm JSR deps stay inline jsr: per member (Deno has no JSR catalog) and the JSR-centralization scanner is a report→FAIL gate. Confirm NOTHING in the plan de-catalogs, edits version pins, or touches scaffold-versions.ts, and that every scanner lands report-only before flipping to FAIL (no CI false-positive lockout).

Verdict: write .llm/tmp/run/chore-deps-hygiene--deps/plan-eval.md (the workflow commits it back to the branch). Emit exactly one of PASS or FAIL_PLAN with specifics. Put the verdict + a one-paragraph rationale in OPENHANDS_SUMMARY_PATH; do NOT post your own PR comment (the workflow posts the status). No implementation slice may begin before PASS.

[rickylabs]

OpenHands Agent — Completed

Model: openrouter/minimax/minimax-m3
Provider: OPENROUTER
Job status: success
Trace: .llm/tmp/run/openhands/pr-55/run-27755191977-1 (committed to the PR branch)
Artifact: openhands-agent-27755191977-1

PLAN-EVAL verdict — chore-deps-hygiene--deps

Verdict

PASS

One-paragraph rationale

The plan (chore/deps-hygiene Group 2 of release/jsr-readiness) passes the Plan-Gate: research is present and rebaselined (with D-G2-1 explicitly superseded by D-G2-2 confirming the npm catalog: protocol IS live), all four locked decisions (DH-1..DH-4) are concrete with rationale, the open-decision sweep resolves every entry (the one deferred item is performed inside the catalog-census slice), the six commit slices (D-1 census, D-2 npm compliance, D-3 JSR centralization, D-4 file/link audit, D-5 task prune, D-6 bump wrapper) are each single-concern, name a proving gate, and stay under ~30 LOC; the risk register explicitly mitigates scanner false-positive lockout via report-only → FAIL sequencing. The load-bearing spot-check for this group — that workspace members declare npm deps as catalog: in each member's package.json (the Deno 2.8 protocol), resolved against the root deno.json catalog block — was verified live (18 member package.json files using catalog:; root catalog defines amqplib: "^2.0.1", ioredis, @preact/signals, clsx, preact, tailwind-merge, etc.), the planned compliance scanner correctly targets the only real inline npm: pin in source (packages/queue/adapters/amqp.adapter.ts — npm:amqplib@^0.10.3 vs catalog ^2.0.1), and the JSR-centralization scanner finds zero cross-member divergences on the current tree (clean baseline, so the report→FAIL flip has zero CI-lockout risk). One non-blocking NIT for the D-2 implementer: explicitly handle (via parser design or allow-list) the two string-literal sites that contain "npm:…" substrings but are not real Deno imports — packages/cli/src/kernel/constants/windows.ts (compile-bundle external map) and packages/fresh-ui/registry.manifest.ts (user-facing dependency array). The plan correctly forbids catalog restructuring, version-pin edits, and any touch to scaffold-versions.ts (DH-1 / Non-Scope). Implementation may begin.

Summary

• Session role: PLAN-EVAL (separate evaluator session; no implementation)
• Deliverable: .llm/tmp/run/chore-deps-hygiene--deps/plan-eval.md (rendered, verdict PASS)
• Branch under eval: chore/deps-hygiene (off release/jsr-readiness)
• Drift active: D-G2-2 supersedes D-G2-1

Changes

• Created .llm/tmp/run/chore-deps-hygiene--deps/plan-eval.md with full checklist + verdict
• No source edits, no version-control operations, no PR comments (workflow owns PR comments per trigger contract)

Validation

• Read .llm/harness/evaluator/plan-protocol.md, .llm/harness/gates/plan-gate.md, .llm/harness/evaluator/verdict-definitions.md
• Read all run artifacts: research.md, plan.md, worklog.md, drift.md
• Confirmed D-G2-2 supersedes D-G2-1 (catalog: protocol IS live)
• Verified 18 package.json files use catalog: protocol
• Verified root deno.json catalog block defines versions (lines 92-126)
• Inspected inline npm: sites in source — one real (amqp.adapter.ts:10), two string-literal (windows.ts, registry.manifest.ts)
• Verified cross-member JSR version invariants (no divergence: jsr:@zod/zod@4.4.3 ×13, jsr:@hono/hono@4.12.24 ×7, jsr:@standard-schema/spec@1.1.0 ×5)
• Verified zero file:/link: specifiers in workspace members
• Confirmed arch:check is per-package + not in ci today; plan correctly addresses both
• Confirmed deno task ci = deno ci && deno task ci:quality && deno task coverage:functions && deno task publish:dry-run && deno task audit:critical

Responses to review comments or issue comments

(n/a — evaluator session; the workflow posts the verdict to the PR, not this session)

Remaining risks

• One non-blocking NIT for the D-2 implementer: detection rule for inline npm: specifiers should anchor on import/export … from "npm:…" statement contexts (and the imports/scopes keys of deno.json), not on substring npm: inside arbitrary string literals. Known string-literal false-positive sites: packages/cli/src/kernel/constants/windows.ts (compile-bundle external map), packages/fresh-ui/registry.manifest.ts (user-facing dependency array). Plan slice D-2 should name these as known-allow-listed at landing.
• Catalog amqplib: "^2.0.1" entry is the load-bearing case the compliance scanner must surface (real pin in amqp.adapter.ts is ^0.10.3). Plan correctly identifies this as the canonical scanner case but does not pre-write the fix.
• The bespoke bump tool the D-6 wrapper replaces was not located in .llm/tools/ at quick scan — implementer must find it before snapshotting parity. Plan text is sufficient ("wrap native, preserve structured output, snapshot parity test").
  Run: https://github.com/rickylabs/netscript/actions/runs/27755191977

[rickylabs]

Implementation progress — WSL Codex (thread 019edaa8-af32…, mobile-visible, daemon-managed)

Slices landed (gates green):

Slice	Commit	Summary	Notes
D-1	dcc5c87a	Dependency census baseline — .llm/tools/deps/census.ts + workspace.ts; deps:census task	deno.json change is task-only (no catalog/pin touch); establishes the empirical baseline before scanners decide what is "divergent"

Catalog-premise drift (D-G2-1 → corrected by D-G2-2) is the inherited planning-phase note; the catalog IS live via member package.json catalog: — scanners enforce that live invariant. No de-catalog. IMPL-EVAL (OpenHands qwen-3.7-max, separate session) after all slices land.

[rickylabs]

Progress — WSL Codex (thread 019edaa8-af32…) — all three scanners landed report-only first (exit 0) per the roll-out design (flip-to-FAIL + CI/arch:check wiring is a later slice).

Slice	Commit	Summary	Gate
D-2	6648177a	npm catalog-compliance scanner	report-only exit 0; 27 WARN on real dep surfaces incl. amqp.adapter.ts:10; D-2 NIT honored — anchors on package.json/deno.json imports+scopes/real npm: imports, windows.ts + registry.manifest.ts excluded as data
D-3	355cf1a7	JSR-version centralization scanner	report-only exit 0; zero findings (1/^1 major ranges normalized)
D-4	041e3d28	file:/link: audit	report-only exit 0; zero findings

Remaining: scanner flip-to-FAIL + CI/arch:check wiring, D-5 task prune, D-6 bump-version wrapper. No de-catalog; no pin edits.

[rickylabs]

Progress — WSL Codex (thread 019edaa8-af32…)

Slice	Commit	Summary	Gate
D-5	587de5dc	deno task prune — drop redundant Fresh dry-run alias (canonical publish:dry-run retained)	packages/fresh publish:dry-run PASS 0 slow types; census confirms alias absent; ref check no matches

Remaining (turn still active): D-6 bump-version wrapper, and the enforcement wiring — flip the clean scanners (D-3 jsr-centralization, D-4 file/link) to FAIL-on-violation + wire a deps:check aggregator into CI/arch:check. Per the accepted D-G2-1/D-G2-2 reframe, the npm catalog-compliance scanner (D-2) stays a report-only adoption/divergence census (it would otherwise FAIL on every legitimately-inline npm pin, which "never de-catalog" forbids fixing this run). Supervisor is tracking that wiring as the gate for Group 2 completeness.

[rickylabs]

Progress — WSL Codex (thread 019edaa8-af32…)

Slice	Commit	Summary
D-6	ec50a3d6	Wrap native deno bump-version (Conventional-Commit-derived) — replaces bespoke bump tool, preserves structured output; parity test

All six enumerated deliverables (D-1…D-6) are in. Still outstanding for Group 2 completeness: the enforcement wiring — flip the clean scanners (D-3 jsr-centralization, D-4 file/link) to FAIL-on-violation and add a deps:check aggregator into ci/arch:check (D-2 npm stays report-only census per the accepted reframe). The turn is still active; supervisor will confirm this lands (and steer the thread if not) before Group 2 is handed to IMPL-EVAL.

[rickylabs]

Group 2 implementation COMPLETE — WSL Codex (thread 019edaa8-af32…)

Slice	Commit	Summary
D-7	3cf314b5	Wire dep scanners into CI + arch:check — deps:check aggregator added to ci:quality and arch:check

deps:check = scan-jsr-centralization --fail-on-violation && audit-file-link --fail-on-violation && scan-npm-catalog-compliance (npm report-only census, no fail flag). Verified deno task deps:check exits 0 on the clean tree (jsr + file/link clean; npm emits 27 WARN census findings, non-failing). arch-debt entry records the npm report-only rationale + convergence target.

All 7 slices in (D-1…D-7). Catalog law intact (no de-catalog / no pin edits / scaffold-versions.ts untouched); D-2 NIT honored; publish:dry-run unaffected. Handoff notes updated; ready for IMPL-EVAL.

Note: arch:check remains red on pre-existing repo-wide doctrine findings unrelated to dependencies (the new deps:check step itself is green) — flagged for the evaluator.

[rickylabs]

@openhands-agent model=openrouter/qwen/qwen3.7-max output=pr-comment iterations=800 use harness

Run IMPL-EVAL (final post-implementation evaluator pass) for the chore/deps-hygiene run (run id chore-deps-hygiene--deps). You are a SEPARATE evaluator session from the implementer — do NOT implement or fix; evaluate and write the verdict.

Read first: .llm/harness/evaluator/protocol.md and .llm/harness/evaluator/verdict-definitions.md, then .llm/tmp/run/chore-deps-hygiene--deps/plan.md, worklog.md (incl. ## Design + ## Gate Results + Handoff Notes), context-pack.md, drift.md, commits.md, and the gate docs the plan references.

Evaluate slices D-1…D-7 against the LOCKED plan. Verdict-critical checks:

1. Catalog law intact — no de-catalog, no version-pin edits, scaffold-versions.ts untouched, no release-time deno.json transform. Confirm via git diff release/jsr-readiness...chore/deps-hygiene -- deno.json and the catalog block.
2. D-2 NIT honored — scan-npm-catalog-compliance anchors on real npm: import statements + deno.json imports/scopes (NOT substring), and excludes packages/cli/src/kernel/constants/windows.ts + packages/fresh-ui/registry.manifest.ts as data.
3. Enforcement wired (DH-3 + deliverables S0: initial public repo genesis #1/S1: package quality — slow-types + docs (supervisor) — Waves 0–6 ✅ merged  #2) — deps:check is in BOTH ci:quality and arch:check; scan-jsr-centralization and audit-file-link run --fail-on-violation; scan-npm-catalog-compliance is intentionally report-only census (justified by D-G2-1/D-G2-2 reframe + arch-debt note — failing it would force de-cataloging, which is forbidden). Run deno task deps:check and confirm exit 0 on the clean tree.
4. No regressions — deno task publish:dry-run still green (27 units, 0 slow types); bump-version wrapper parity test green. Note: arch:check is red on PRE-EXISTING repo-wide doctrine findings unrelated to dependencies — verify the new deps:check step itself is green and do not attribute the pre-existing doctrine red to this run.
5. Scanners (.llm/tools/deps/) match the sibling contract to check-doctrine.ts: Finding[] + --json + non-zero exit on FAIL.

Write the verdict to .llm/tmp/run/chore-deps-hygiene--deps/evaluate.md (PASS / FAIL_FIX / FAIL_RESCOPE / FAIL_DEBT). Write your summary to OPENHANDS_SUMMARY_PATH; do NOT post your own PR comment (the workflow owns the status comment). Do not de-catalog, edit pins, delete lock/cache files, or upgrade dependencies.

[rickylabs]

OpenHands Agent — Completed

Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Job status: success
Trace: .llm/tmp/run/openhands/pr-55/run-27760239494-1 (committed to the PR branch)
Artifact: openhands-agent-27760239494-1

Summary

IMPL-EVAL executed for chore/deps-hygiene (Group 2, run id chore-deps-hygiene--deps) and issued the verdict PASS.

Changes

Evaluated slices D-1 through D-7 against the LOCKED plan:

• D-1: catalog-resolve tooling (census + prod-install wrapper, gate-0 smoke); catalog block intact.
• D-2: scan-npm-catalog-compliance (report-only launch) — anchors on real npm:/deno.json surfaces, excludes windows.ts + registry.manifest.ts as data (NIT honored).
• D-3: scan-jsr-centralization (zero findings, --fail-on-violation).
• D-4: audit-file-link (zero findings, --fail-on-violation).
• D-5: fresh task prune (dry-run alias removed).
• D-6: bump-version wrapper + parity test (1 passed | 0 failed).
• D-7: deps:check aggregator wired into ci:quality and arch:check.

Validation

• deno task deps:check → exit 0 (3 JSR centralization + file/link audits clean; 27 npm-catalog WARN findings are the designed report-only census).
• deno task publish:dry-run → exit 0 (25 publishable units, no slow-type failures; baseline also reports 25 units, so the "27" figure in the plan was a documentation drift, not a regression).
• deno task version:bump:test → 1 passed, 0 failed.
• deno task arch:check → deps:check step exits 0; the subsequent doctrine step fails with pre-existing repo-wide findings (FAIL=58 / WARN=147 / INFO=1) that are not attributable to this run.
• git diff release/jsr-readiness...chore/deps-hygiene -- deno.json shows no de-catalog, no version-pin edits, no scaffold-versions.ts touch, no release-time deno.json transform.
• Scanners in .llm/tools/deps/ match the check-doctrine.ts sibling contract: Finding[] shape, --json flag, non-zero exit on FAIL.

Responses to review comments

Not applicable for this run — IMPL-EVAL is a separate evaluator session; the implementer already addressed all prior plan-eval and implementor NITs (D-2 scanner anchoring, D-G2-1/D-G2-2 catalog-law reframe, D-6 parity test).

Remaining risks

• 27 WARN-level npm-catalog findings are expected report-only census of inline npm: uses that already agree with the catalog version (or are intentional scope exceptions such as queue/amqplib). Failing the scanner would force de-cataloging, which is forbidden — arch-debt note recommended for the queue/amqplib ^0.10.3 vs ^2.0.1 divergence so a future slice can converge it.
• Pre-existing arch:check doctrine baseline is red (A14 / AP-19 / AP-23 / etc.). This is not a Group-2 regression and must not be attributed to this run.

Verdict

PASS — written to .llm/tmp/run/chore-deps-hygiene--deps/evaluate.md.

Run: https://github.com/rickylabs/netscript/actions/runs/27760239494