chore(release-prep): alpha.3 gate — docs redeploy-on-release + scaffold version zero-drift

[rickylabs]

Release-prep gate for v0.0.1-alpha.3

The last two pieces that must land on main before publishing the alpha.3 JSR release train.
Realizes task #112 (the release-triggered docs redeploy) + scaffold version zero-drift.

Why this exists

A release must (a) refresh the live docs site with the new version and (b) not break CI when the
workspace bumps alpha.2 → alpha.3. Investigation found almost all of #112 is already in place:

Piece	State
Docs read version from manifest (docs/site/_data.ts → packages/cli/deno.json)	✅ already on main (PR #106)
Pages builds from main, main allow-listed in github-pages env	✅ already configured
main docs/site ⊇ docs/user-site (0 divergence)	✅ verified
Release-triggered docs rebuild workflow	❌ missing — never landed
CLI scaffold test fixtures hardcode @0.0.1-alpha.2	❌ break on bump

Slices

• S1 (CI): add .github/workflows/pages.yml to main, triggered on release: published
  (+ push to docs/site/** + workflow_dispatch); build docs/site (Deno 2.9.0) and deploy to
  Pages. Build/deploy steps ported verbatim from the docs/user-site copy — only the trigger block
  and pinned Deno version change. docs/user-site becomes preview-only.
• S2 (CLI test fixtures): derive expected @netscript versions from NETSCRIPT_RELEASE_VERSION
  instead of hardcoding @0.0.1-alpha.2, plus a guard test forbidding stray literal version pins.
  Runtime scaffold output is already drift-free via jsr-specifiers.ts; this makes the test suite
  bump-safe.

Not in this PR

The actual deno bump-version prerelease, tag v0.0.1-alpha.3, and GitHub Release happen as a
separate step after this merges — which then fires publish.yml + e2e-cli-prod.yml + the new
pages.yml.

Harness run: .llm/tmp/run/chore-release-prep-alpha3--release-prep/.

🤖 Generated with Claude Code

[rickylabs]

@openhands-agent model=openrouter/minimax/minimax-m3 provider=openrouter output=pr-comment iterations=300

use harness

You are running PLAN-EVAL (separate evaluator session, before any implementation) for the
chore/release-prep-alpha3 branch / this PR — the last pre-release gate before publishing the JSR
0.0.1-alpha.3 release train. This is a supervisor/CI + test-fixture slice: no packages/
runtime source changes, no plugins/ changes. Emit a PASS or FAIL_PLAN verdict comment.

SKILL

• .agents/skills/netscript-harness — PLAN-EVAL protocol, plan-gate, verdict definitions.
• .agents/skills/netscript-deno-toolchain — bump-version semantics, deno doc, publish dry-run.
• .agents/skills/netscript-tools — scoped check/lint wrappers, lock hygiene, raw git verification.
• .agents/skills/jsr-audit — JSR publish surface + version-alignment expectations.
• .agents/skills/deno-fresh / SCOPE-docs — docs-site (Lume) build + Pages deploy surface.

What to read

• .llm/tmp/run/chore-release-prep-alpha3--release-prep/research.md and plan.md on this branch.
• .llm/harness/gates/plan-gate.md, .llm/harness/evaluator/plan-protocol.md.

What the plan proposes (verify each is grounded and correct)

1. Slice 1 (CI): add .github/workflows/pages.yml to main triggered on push (main,
   docs/site/**), release: { types: [published] }, and workflow_dispatch; build docs/site
   (Deno 2.9.0, matching chore(deno-2.9): adoption track — toolchain bump + native task parallelism/input-cache + publish resilience (C0-C4) #128) and deploy to the github-pages environment. The build/deploy
   steps are ported verbatim from docs/user-site:.github/workflows/pages.yml.
2. Slice 2 (CLI test fixtures): replace hardcoded @0.0.1-alpha.2 literals in the listed CLI
   test files with values derived from NETSCRIPT_RELEASE_VERSION
   (packages/cli/src/kernel/constants/jsr-specifiers.ts), plus one guard test forbidding stray
   literal @0.0.1-alpha.N JSR specifiers under packages/cli/src/**. No change to
   packages/cli/deno.json version field.

Hard checks (refute or confirm with evidence)

1. F1 grounding: confirm main:docs/site/_data.ts already imports packages/cli/deno.json and
   exports releaseVersion/releaseSpecifier. If true, no docs-side version code is needed.
2. F2 grounding: confirm via gh api repos/<owner>/<repo>/pages that Pages build_type is
   workflow and source.branch is main; confirm the github-pages environment allow-lists
   main; confirm docs/site content does not diverge between main and docs/user-site
   (gh api .../compare/main...docs/user-site). If main is NOT allow-listed or Pages source is
   not main, that is a FAIL_PLAN gap the plan must own.
3. F3 grounding: confirm pages.yml is absent on main and that release: events only fire
   workflows from the default branch — i.e. Slice 1 really is the missing redeploy trigger.
4. F4 grounding: confirm the listed CLI test files assert literal @0.0.1-alpha.2 (so a bump
   breaks them) AND that jsr-specifiers.ts derives the version from cli/deno.json (so runtime
   scaffold output is already drift-free). Confirm Slice 2's derivation approach actually removes the
   break without weakening the assertions (the test must still assert the correct specifier, just
   computed not hardcoded).
5. Scope/lane: confirm no packages/ runtime source or plugins/ source is in scope; Slice 2 is
   test-only + one doc comment; zero-cast rule respected; no deno.lock churn planned.
6. Sequencing soundness: the plan keeps the actual version bump/tag/release OUT of this PR
   (separate step after merge). Confirm that is correct and that this PR alone leaves main green
   (no bump applied here, so existing alpha.2 fixtures still pass on this PR; the derivation makes
   them bump-safe for the later release PR). Flag if the derivation would break the CURRENT
   (unbumped) suite.

Verdict

PASS only if all six checks hold and the plan is implementable as written with no missing gate.
Otherwise FAIL_PLAN with the specific gap(s). Write your verdict to
.llm/tmp/run/chore-release-prep-alpha3--release-prep/plan-eval.md and post it as a PR comment.
Do not implement anything.

[rickylabs]

OpenHands Agent — Agent failed

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

OpenHands Agent Summary

The agent run failed before producing a summary.

This is a workflow failure, not a task verdict.

Diagnostics

• Bootstrap: success
• Agent: failure
• Model: openrouter/minimax/minimax-m3
• Provider: OPENROUTER
• Output mode: pr-comment
• Run: https://github.com/rickylabs/netscript/actions/runs/28196492395

See the uploaded Actions artifact for bootstrap.log and agent.log when present.

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

[rickylabs]

@openhands-agent model=openrouter/minimax/minimax-m3 provider=openrouter output=pr-comment iterations=300

use harness

You are running PLAN-EVAL (separate evaluator session, before any implementation) for the
chore/release-prep-alpha3 branch / this PR — the last pre-release gate before publishing the JSR
0.0.1-alpha.3 release train. This is a supervisor/CI + test-fixture slice: no packages/
runtime source changes, no plugins/ changes. Emit a PASS or FAIL_PLAN verdict comment.

SKILL

• .agents/skills/netscript-harness — PLAN-EVAL protocol, plan-gate, verdict definitions.
• .agents/skills/netscript-deno-toolchain — bump-version semantics, deno doc, publish dry-run.
• .agents/skills/netscript-tools — scoped check/lint wrappers, lock hygiene, raw git verification.
• .agents/skills/jsr-audit — JSR publish surface + version-alignment expectations.
• .agents/skills/deno-fresh / SCOPE-docs — docs-site (Lume) build + Pages deploy surface.

What to read

• .llm/tmp/run/chore-release-prep-alpha3--release-prep/research.md and plan.md on this branch.
• .llm/harness/gates/plan-gate.md, .llm/harness/evaluator/plan-protocol.md.

What the plan proposes (verify each is grounded and correct)

1. Slice 1 (CI): add .github/workflows/pages.yml to main triggered on push (main,
   docs/site/**), release: { types: [published] }, and workflow_dispatch; build docs/site
   (Deno 2.9.0, matching chore(deno-2.9): adoption track — toolchain bump + native task parallelism/input-cache + publish resilience (C0-C4) #128) and deploy to the github-pages environment. The build/deploy
   steps are ported verbatim from docs/user-site:.github/workflows/pages.yml.
2. Slice 2 (CLI test fixtures): replace hardcoded @0.0.1-alpha.2 literals in the listed CLI
   test files with values derived from NETSCRIPT_RELEASE_VERSION
   (packages/cli/src/kernel/constants/jsr-specifiers.ts), plus one guard test forbidding stray
   literal @0.0.1-alpha.N JSR specifiers under packages/cli/src/**. No change to
   packages/cli/deno.json version field.

Hard checks (refute or confirm with evidence)

1. F1 grounding: confirm main:docs/site/_data.ts already imports packages/cli/deno.json and
   exports releaseVersion/releaseSpecifier. If true, no docs-side version code is needed.
2. F2 grounding: confirm via gh api repos/<owner>/<repo>/pages that Pages build_type is
   workflow and source.branch is main; confirm the github-pages environment allow-lists
   main; confirm docs/site content does not diverge between main and docs/user-site
   (gh api .../compare/main...docs/user-site). If main is NOT allow-listed or Pages source is
   not main, that is a FAIL_PLAN gap the plan must own.
3. F3 grounding: confirm pages.yml is absent on main and that release: events only fire
   workflows from the default branch — i.e. Slice 1 really is the missing redeploy trigger.
4. F4 grounding: confirm the listed CLI test files assert literal @0.0.1-alpha.2 (so a bump
   breaks them) AND that jsr-specifiers.ts derives the version from cli/deno.json (so runtime
   scaffold output is already drift-free). Confirm Slice 2's derivation approach actually removes the
   break without weakening the assertions (the test must still assert the correct specifier, just
   computed not hardcoded).
5. Scope/lane: confirm no packages/ runtime source or plugins/ source is in scope; Slice 2 is
   test-only + one doc comment; zero-cast rule respected; no deno.lock churn planned.
6. Sequencing soundness: the plan keeps the actual version bump/tag/release OUT of this PR
   (separate step after merge). Confirm that is correct and that this PR alone leaves main green
   (no bump applied here, so existing alpha.2 fixtures still pass on this PR; the derivation makes
   them bump-safe for the later release PR). Flag if the derivation would break the CURRENT
   (unbumped) suite.

Verdict

PASS only if all six checks hold and the plan is implementable as written with no missing gate.
Otherwise FAIL_PLAN with the specific gap(s). Write your verdict to
.llm/tmp/run/chore-release-prep-alpha3--release-prep/plan-eval.md and post it as a PR comment.
Do not implement anything.

[rickylabs]

OpenHands Agent — Completed

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

Summary — pr-129 / run-28197363632-1

Summary

PLAN-EVAL evaluator session for the chore/release-prep-alpha3 branch (PR #129). Verdict:
PASS — plan is implementable as written; no missing gate; sequencing is sound; scope is
clean.

Changes

• Verified all six hard checks against current main independently (not just relying on the prior
  plan-eval.md).
• Wrote fresh plan-eval.md at
  .llm/tmp/run/chore-release-prep-alpha3--release-prep/plan-eval.md with my own verification
  evidence (overwrites the prior session's verdict file with this session's independent verdict).
• No implementation committed. No packages/ runtime or plugins/ source touched. No deno.lock
  churn.

Evidence collected this session

• F1: docs/site/_data.ts:14-16 reads cliPackageJson.version from
  packages/cli/deno.json; packages/cli/deno.json:3 = "0.0.1-alpha.2" confirmed.
• F2: gh api repos/rickylabs/netscript/pages →
  build_type: "workflow", source.branch: "main", path: "/", https_enforced: true.
  gh api .../environments/github-pages/deployment-branch-policies →
  allow-listed: docs/user-site, main, release/jsr-readiness.
  gh api .../compare/main...docs/user-site → 0 files under docs/site/** differ.
• F3: git ls-tree origin/main .github/workflows/pages.yml → empty. git ls-tree origin/docs/user-site .github/workflows/pages.yml → blob present. Precedent confirmed:
  publish.yml + e2e-cli-prod.yml already use on: release: { types: [published] } +
  workflow_dispatch:.
• F4: 21 literal @0.0.1-alpha.2 occurrences verified at the exact line numbers research
  listed (across 5 test files + 1 doc-comment).
  packages/cli/src/kernel/constants/jsr-specifiers.ts:8-22 derives NETSCRIPT_RELEASE_VERSION
  from cliPackageJson.version and exposes netscriptJsrSpecifier(...); runtime scaffold output
  is already drift-free.
• Scope/lane: Only .github/workflows/pages.yml (new) + 5 listed CLI test files + 1 doc
  comment + 1 new guard test file in scope. No packages/ runtime, no plugins/, no deno.lock
  churn. Zero-cast rule respected (no new casts introduced).
• Sequencing: packages/cli/deno.json and packages/cli/e2e/deno.json still
  0.0.1-alpha.2 on this branch — bump is correctly kept out of this PR. Derivation approach
  does not break the current suite (both sides evaluate to 0.0.1-alpha.2 until the bump PR).

Plan-Gate checklist

Item	Result
Research present and current	PASS
Decisions locked	PASS
Open-decision sweep	PASS
Commit slices (< 30, gate + files each)	PASS (2 slices)
Risk register	PASS
Gate set selected	PASS
Deferred scope explicit	PASS
jsr-audit surface scan	N/A (no JSR surface change)

Validation

• gh api queries against the live GitHub repo for Pages config, environment allow-list, and
  branch comparison.
• git ls-tree for workflow presence on main vs docs/user-site.
• Direct file inspection (docs/site/_data.ts, packages/cli/src/kernel/constants/jsr-specifiers.ts,
  all listed test fixtures) to confirm literals and import patterns.
• grep -rn "0\.0\.1-alpha\.2" packages/cli/src/ to enumerate every hardcoded literal location
  (21 matches across 6 files, matching research F4 exactly).
• No deno check/deno test/deno task runs required — this is a PLAN-EVAL pass, not an
  implementation pass. The plan's gate (actionlint, deno test green-at-bumped-version) is for the
  implementation slices.

Responses to review comments or issue comments

None — PLAN-EVAL is a separate pre-implementation evaluator pass with no prior PR review comments
to address. The verdict comment itself will be posted by the workflow owner (the operational
contract says I must not post GitHub comments directly).

Remaining risks

• The plan depends on the post-merge bump-version step being executed in a separate PR — if
  someone merges the bump into this PR, the test-fixture derivation would still be correct (since
  both sides move together) but the JSR-publish-surface change would slip into a PR that didn't
  advertise it. The plan explicitly addresses this via Sequencing Wave 0b·B — .agents/docs + skills cluster #5; the IMPL-EVAL session should
  re-verify the bump stays out.
• The github-pages environment's custom_branch_policies setting is what makes the allow-list
  authoritative; if GitHub repo settings change between now and merge, F2 needs re-checking.
• Drift-guard test (packages/cli/src/kernel/constants/version-drift_test.ts) is new and
  unproven — IMPL-EVAL should confirm the grep pattern excludes deno.json correctly and that
  the test actually fails when a stray @0.0.1-alpha.N literal is reintroduced.
  Run: https://github.com/rickylabs/netscript/actions/runs/28197363632

[rickylabs]

Implementation complete — both slices on ac50af45

PLAN-EVAL PASS (run-28197363632, all 6 hard checks verified independently). Implemented via
Claude (IMPL-EVAL skipped by maintainer decision — simple, fully-verified slice).

S2 — scaffold version zero-drift (a4e65f99, test-only + 1 doc comment)

• All 21 literal @0.0.1-alpha.2 occurrences across 5 test files replaced with
  netscriptJsrSpecifier(pkg, subpath?) derived from NETSCRIPT_RELEASE_VERSION; subpaths
  preserved exactly. Doc comment in import-resolver.ts → version-neutral @<release>.
• New guard packages/cli/src/kernel/constants/version-drift_test.ts fails if any
  packages/cli/src/** file (excluding deno.json + itself) reintroduces a hardcoded
  jsr:@netscript/...@0.0.1-alpha.N pin.
• Bump-safety proven: 6 suites green at alpha.2 (12 passed), deno bump-version prerelease
  → alpha.3, same 6 suites green at alpha.3 (12 passed), reverted. Guard-failure proven against a
  throwaway probe. deno check clean (518 files). deno.lock unchanged.

S1 — release-triggered docs redeploy (edcb6ac1)

• New .github/workflows/pages.yml on this branch (→ main on merge): builds docs/site and
  deploys to Pages on release: published (+ push to docs/site/** on main + workflow_dispatch).
• Ported verbatim from docs/user-site:.github/workflows/pages.yml — git diff --no-index shows
  exactly 3 deltas: branch docs/user-site→main, added release: [published], Deno v2.x→2.9.0.
• Because docs/site/_data.ts already reads releaseVersion from packages/cli/deno.json, a
  release (tag on the bumped main) rebuilds docs at the new version automatically — no fetch, no
  branch sync.

docs/user-site is now preview-only. Bump/tag/release stays out of this PR (separate step after
merge → fires publish.yml + e2e-cli-prod.yml + this pages.yml).