docs(release): codify same-semver republish recovery + min-dependency-age handling + first-publish checklist

[rickylabs]

Summary

Codifies two release patterns that were proven live during the v0.0.1-beta.10 cut (2026-07-17) into
the netscript-release skill source, per owner directive: future agents must reach for these before
defaulting to an unwanted stable-channel semver bump.

What changed

.agents/skills/netscript-release/SKILL.md (source) + .claude/skills/netscript-release/SKILL.md
(regenerated mirror via deno task agentic:sync-claude), additive only:

1. Same-Semver Republish (Partial-Publish Recovery) — new section. JSR version immutability
   binds only to published members; a failed/skipped member can still publish at the exact same
   semver, and workspace deno publish skips already-registered versions on the members that
   already succeeded. Recovery is fix-forward → tag fast-forward (only when every already-published
   member is byte-identical across the move) → re-dispatch publish.yml with the tag
workflow_dispatch input → the completion pair must go green on the re-dispatched run. Semver
   bump is documented as the fallback, only when already-published content changed.
2. Minimum-Dependency-Age At Release Time — new subsection under the merge/publish flow. Deno
   2.9's ~24h default rejects same-day publishes; the harness pins
   --minimum-dependency-age=0 on published-JSR invocations, and a second fix keeps fresh-plugin
   resolution in one Deno process (deno x's internal child-process re-exec drops the flag — the
   beta.10 double-failure). References the user-facing 24h window tracked in cli: fresh projects hit Deno's 24h minimum-dependency-age wall for every jsr:@netscript/* resolution in the first day after a release #818.
3. First-Publish Checklist — new short section. Provisioning is automated in publish.yml, but
   README production standard, tagline cap, license/exports, docs-site coverage, and live tool
   validation are still manual until release: canary publish channel — mandatory authenticated pre-publish gate with post-canary live production CI, + publish-readiness automation #811/feat(release): add mandatory canary publish gate #812's publish-readiness.ts canary-channel automation
   lands.

Evidence (verified against live GitHub Actions runs before writing)

• Original beta.10 publish.yml run 29558968037:
  33 members published, 10 failed on transient invalidBearerToken, @netscript/mcp failed on the
  registry-rejected text import (fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810), 26 more skipped as dependents (@netscript/cli among them).
• Fix-forward commit 8a8a9537 (fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810), tag fast-forwarded from a5adb706, re-dispatched via
  workflow_dispatch (tag=v0.0.1-beta.10, no new Release) →
  29562537123 green, mcp and
  cli publishing for the first time, all 33 prior members logging Skipping, already published.
• Min-dependency-age: fix(e2e): pin --minimum-dependency-age=0 on published-JSR invocations — prod suite must not fail for 24h after each release #813 (2a1c8ed9) pinned the flag, e2e-cli-prod run
  29564434302 still failed;
  fix(e2e): bypass Deno 2.9 x flag loss for fresh plugin releases #817 (aa14e452) fixed the deno x child-process flag loss →
  29566090314 green.
• release: canary publish channel — mandatory authenticated pre-publish gate with post-canary live production CI, + publish-readiness automation #811 (canary channel epic) and feat(release): add mandatory canary publish gate #812 (draft implementation PR) confirmed open/in-flight for the
  first-publish-checklist automation citation.

Gates run

• deno task docs:links — OK, 0 broken links/anchors/orphans.
• deno task agentic:sync-claude then deno task agentic:sync-claude:check — OK, mirror
  byte-identical to source.
• deno fmt --check on both touched files — clean.

Scope note

Documentation-only change to skill guidance text; no packages/**/plugins/** source touched, per
the CLAUDE.md documentation-authoring exception. Not merging — leaving at status:impl-eval for
owner/evaluator review.

[rickylabs]

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

use harness

SKILL

• netscript-harness — preserve evaluator separation and record a concise, evidence-based verdict.
• netscript-tools — use repository-native commands and keep lock/worktree state clean.
• openhands-handoff — honor the pr-comment output contract and write the required summary.
• netscript-cli — hand-test scaffold and documented CLI commands when executable claims exist.
• rtk — keep changed-file and command inspection compact.

Act as a cheap-and-quick documentation accuracy evaluator. Do not edit source, documentation,
deno.lock, or run artifacts, and do not create commits. Write the complete result to
OPENHANDS_SUMMARY_PATH; output mode pr-comment will publish that result as the single PR
comment.

1. Identify every changed documentation file in this PR and read each one fully. Include Markdown,
   MDX, READMEs, RFCs, harness/process docs, and skill instructions; do not review only the diff
   hunks.
2. For every executable claim, QUICKLY hand-test the exact documented command or snippet from the
   repository root. Use the smallest representative scaffold/workspace needed, compare real output
   and generated paths with the document's claim, and stop after the highest-value small checks. Do
   not substitute a full expensive E2E suite for a focused manual check.
3. If the changed set contains no executable command, snippet, flag, verb, or path claim, say
   exactly:
   No executable documentation claims in this changed set; manual command testing was not applicable.
   Full accuracy and hallucination review is still mandatory.
4. Check every named command verb, flag, file path, package, API, and expected output against the
   repository. Any hallucinated or nonexistent verb, flag, or path is a BLOCKING finding.
5. Return a compact per-file table with accurate, inaccurate, or unverifiable, the commands or
   snippets tested, observed-versus-claimed output, and blocking findings. End with one overall
   PASS or FAIL_FIX verdict and a short list of exact fixes.

Keep the iteration budget small. Prefer one to three decisive manual checks over broad exploration,
but never omit a changed documentation file from the per-file verdict table.

[rickylabs]

OpenHands Agent — Agent failed

OPENHANDS_VERDICT: NONE

Model: openrouter/minimax/minimax-m3
Provider: OPENROUTER
Job status: failure
Verdict source: none
Summary source: none
Housekeeping: ack=success trace=success commit-artifacts=success replies=skipped draft-pr=skipped
Trace: .llm/tmp/run/openhands/pr-819/run-29566797252-1 (in the Actions artifact)
Artifact: openhands-agent-29566797252-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/29566797252

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

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

[rickylabs]

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

use harness

SKILL

• netscript-harness — preserve evaluator separation and record a concise, evidence-based verdict.
• netscript-tools — use repository-native commands and keep lock/worktree state clean.
• openhands-handoff — honor the pr-comment output contract and write the required summary.
• netscript-cli — hand-test scaffold and documented CLI commands when executable claims exist.
• rtk — keep changed-file and command inspection compact.

Act as a cheap-and-quick documentation accuracy evaluator. Do not edit source, documentation,
deno.lock, or run artifacts, and do not create commits. Write the complete result to
OPENHANDS_SUMMARY_PATH; output mode pr-comment will publish that result as the single PR
comment.

1. Identify every changed documentation file in this PR and read each one fully. Include Markdown,
   MDX, READMEs, RFCs, harness/process docs, and skill instructions; do not review only the diff
   hunks.
2. For every executable claim, QUICKLY hand-test the exact documented command or snippet from the
   repository root. Use the smallest representative scaffold/workspace needed, compare real output
   and generated paths with the document's claim, and stop after the highest-value small checks. Do
   not substitute a full expensive E2E suite for a focused manual check.
3. If the changed set contains no executable command, snippet, flag, verb, or path claim, say
   exactly:
   No executable documentation claims in this changed set; manual command testing was not applicable.
   Full accuracy and hallucination review is still mandatory.
4. Check every named command verb, flag, file path, package, API, and expected output against the
   repository. Any hallucinated or nonexistent verb, flag, or path is a BLOCKING finding.
5. Return a compact per-file table with accurate, inaccurate, or unverifiable, the commands or
   snippets tested, observed-versus-claimed output, and blocking findings. End with one overall
   PASS or FAIL_FIX verdict and a short list of exact fixes.

Keep the iteration budget small. Prefer one to three decisive manual checks over broad exploration,
but never omit a changed documentation file from the per-file verdict table.

[rickylabs]

OpenHands Agent — Agent failed

OPENHANDS_VERDICT: NONE

Model: openrouter/minimax/minimax-m3
Provider: OPENROUTER
Job status: failure
Verdict source: none
Summary source: none
Housekeeping: ack=success trace=success commit-artifacts=success replies=skipped draft-pr=skipped
Trace: .llm/tmp/run/openhands/pr-819/run-29567679980-1 (in the Actions artifact)
Artifact: openhands-agent-29567679980-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/29567679980

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

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

[rickylabs]

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

use harness

SKILL

• netscript-harness — preserve evaluator separation and record a concise, evidence-based verdict.
• netscript-tools — use repository-native commands and keep lock/worktree state clean.
• openhands-handoff — honor the pr-comment output contract and write the required summary.
• netscript-cli — hand-test scaffold and documented CLI commands when executable claims exist.
• rtk — keep changed-file and command inspection compact.

Act as a cheap-and-quick documentation accuracy evaluator. Do not edit source, documentation,
deno.lock, or run artifacts, and do not create commits. Write the complete result to
OPENHANDS_SUMMARY_PATH; output mode pr-comment will publish that result as the single PR
comment.

1. Identify every changed documentation file in this PR and read each one fully. Include Markdown,
   MDX, READMEs, RFCs, harness/process docs, and skill instructions; do not review only the diff
   hunks.
2. For every executable claim, QUICKLY hand-test the exact documented command or snippet from the
   repository root. Use the smallest representative scaffold/workspace needed, compare real output
   and generated paths with the document's claim, and stop after the highest-value small checks. Do
   not substitute a full expensive E2E suite for a focused manual check.
3. If the changed set contains no executable command, snippet, flag, verb, or path claim, say
   exactly:
   No executable documentation claims in this changed set; manual command testing was not applicable.
   Full accuracy and hallucination review is still mandatory.
4. Check every named command verb, flag, file path, package, API, and expected output against the
   repository. Any hallucinated or nonexistent verb, flag, or path is a BLOCKING finding.
5. Return a compact per-file table with accurate, inaccurate, or unverifiable, the commands or
   snippets tested, observed-versus-claimed output, and blocking findings. End with one overall
   PASS or FAIL_FIX verdict and a short list of exact fixes.

Keep the iteration budget small. Prefer one to three decisive manual checks over broad exploration,
but never omit a changed documentation file from the per-file verdict table.

[rickylabs]

OpenHands Agent — Agent failed

OPENHANDS_VERDICT: NONE

Model: openrouter/minimax/minimax-m3
Provider: OPENROUTER
Job status: failure
Verdict source: none
Summary source: none
Housekeeping: ack=success trace=success commit-artifacts=success replies=skipped draft-pr=skipped
Trace: .llm/tmp/run/openhands/pr-819/run-29567998698-1 (in the Actions artifact)
Artifact: openhands-agent-29567998698-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/29567998698

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

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