plan(seed): Fable 5 long-range remediation roadmap (planning-only, drafts)

[rickylabs]

Summary

Planning-only seed run that produced and then, after explicit owner ratification, filed the complete long-range NetScript remediation roadmap: master plan with a 12-fork owner sweep, milestone train, 41 issues, two RFC entry points, existing-owner amendments, Wave-7 measured-adoption design, implementation handoff, and a cited research corpus.

GitHub is now authoritative. This draft PR preserves the planning rationale and filing receipts; it must not be merged.

Scope

• Archetype / area: docs and run artifacts only (.llm/runs/plan-fable5-remediation-roadmap--seed/)
• Seed run per .llm/harness/workflow/seed-run.md; profile SCOPE-docs
• No product/framework source touched

Slices

• S1 Bootstrap — run dir, supervisor identity, owner eval waivers, draft PR
• S2 Discovery corpus — prior waves, live board, repo/docs audit, external bar
• S3 Synthesis — gap taxonomy, adjudications, T1–T8 packs, train direction
• S4 Design packs — 41 issue drafts, RFC-A/RFC-B, amendments, dedup table
• S5 Plan lock — master plan, implementation handoff, run close
• S6 Stage-H filing — milestone insertion, 41 live issues, dependency and amendment reconciliation

Stage H — owner-ratified filing

• Shifted existing milestone objects 0.0.6–0.0.13 to 0.0.8–0.0.15, highest-first.
• Created fresh 0.0.6 and 0.0.7 milestones and restored the complete old-0.0.6 membership before applying planned exceptions.
• Filed 41 issues (Epic: Typed SDK client contributions — credentials, transport policy, metadata, and cache-safe extensions #1348–test(e2e): the scaffold runtime auth gate proves only that an unauthenticated request succeeds #1388): 10 / 12 / 19 across 0.0.6 / 0.0.7 / 0.0.8.
• Reconciled internal dependencies to live issue numbers and posted 20 additive existing-owner amendments.
• Audited all new issues: open, milestone assigned, status:triage, and type/area/priority labels present. No issue was closed.

Full durable receipt: fable-5-remediation-plan/FILING-LOG.md at commit 1ef78e29f.

Validation and harness

• Docs/run-artifact-only PR: ci:skip-e2e + ci:skip-scaffold intentionally applied.
• Baseline at plan lock: origin/main @ fac9e339042c.
• PLAN-EVAL and IMPL-EVAL were owner-waived for this planning/filing run. The waiver does not extend to implementation.
• Workflows: wf_e2194004-808, wf_03b88126-e7e, wf_ebfe8327-306; 25 Opus 5 contributors, 0 workflow errors.

Do not merge: this draft PR is the durable planning record. The owner-ratified board filing is complete and GitHub issues are authoritative.

🤖 Generated with Claude Code

[rickylabs]

[PHASE: RESEARCH] — Stage A charter read-back (seed run plan-fable5-remediation-roadmap--seed)

Charter. Planning-only seed run: long-range NetScript remediation roadmap as drafts under .llm/runs/plan-fable5-remediation-roadmap--seed/fable-5-remediation-plan/. Supervisor: Claude Fable 5 · high (owner override of planning_decisions low), native Anthropic subscription, bypassPermissions, Remote Control enabled. Claude Workflows with Opus 5 subagents serve as research/synthesis contributors only.

Owner waivers (recorded in supervisor.md / worklog.md / drift.md): PLAN-EVAL waived; IMPL-EVAL waived. No formal evaluator, OpenHands, or OpenRouter session will be launched. Owner personally reviews the plan and decides on later adversarial passes / board filing.

Mutation boundary. Zero GitHub board mutation (issues/epics/milestones/labels/comments outside this PR). No framework/product source edits. Writable surfaces: this branch, its commits, this draft PR (body/comments/PR labels). Filing (stage H) is explicitly out of scope.

CI lane. ci:skip-e2e + ci:skip-scaffold applied intentionally: the entire diff is run-artifact/docs under .llm/runs/; scaffold-static and e2e are not applicable. ci:full remains the escape hatch if that ever changes (it will not — no code paths in scope).

Evidence inputs. (1) Codex pre-plan package (README / ISSUE-DEDUP-MATRIX / EVIDENCE-REGISTER); (2) all agent-posts waves (archive + waves 3–6); (3) live GitHub board (wins over carried-in reports); (4) deep repo + published-docs audit; (5) eis-chat + competing meta-frameworks + oRPC; (6) 0.0.5 milestone/orchestrator history.

Baseline. origin/main @ fac9e339042c — verified equal to HEAD at run start; will re-fetch read-only before plan lock.

Next: Stage B discovery corpus (S2).

[rickylabs]

[PHASE: RESEARCH] — S2a landed: prior-wave evidence + live board ground truth (d5b984044)

Workflow wf_e2194004-808 (7 Opus 5 subagents, 796k tokens, read-only) produced fable-5-remediation-plan/research/: prior-waves-early.md, wave-4.md, wave-5-6-plans.md, wave-6-runs.md, github-board-open.md (exhaustive 259-issue/13-milestone snapshot), github-board-history.md (0.0.5 train + orchestration plans v2/v3), github-conventions.md (live label/milestone/issue-form/RFC practice). Supervisor substantively reviewed all seven before this sign-off commit.

Load-bearing corrections vs the carried-in pre-plan (current GitHub wins):

• 259 open issues / 13 open milestones (0.0.2–0.0.13 + Backlog/Triage), not 265/11; no milestone has a due date.
• fix(scaffold): generated check misses TSX/plugin runtimes while bare lint/fmt report 154 scaffold-owned findings #1328 and sagas: generated runtime glue registers no KV adapter — saga runner crashes on a default scaffold #1184 are CLOSED; Epic: Scaffold conformance — generated surfaces match current docs, exports and idiomatic usage #1335's only sub-issue checkbox (fix(scaffold): generated check misses TSX/plugin runtimes while bare lint/fmt report 154 scaffold-owned findings #1328) is stale.
• Duplicate umbrella pairs needing supersession decisions: epic(quality): ratify and eliminate unsound types — no as-unknown-as, no arbitrary any, no conceded TS errors #1276≈Type soundness ratification: eliminate unsound and arbitrary types across the public surface and the docs #1278, epic(docs): migration chapter — migrate-from guides, capability equivalence matrix, and end-to-end migration recipes #1275≈docs: migration chapter — per-framework guides, compatibility matrix, and e2e migration recipes #1279; 20 open umbrellas, 9 with no machine-readable child list.
• 0.0.5 continuation plan is ~40% delivered: W2–W5 never dispatched — p0s fix(streams): DurableStreamProducer permanently drops writes after an initial connection failure; reconnect is never attempted #1326, fix(streams): documented SSE consumer shape differs from the wire protocol and does not specify the standard event/OTEL envelope #1329, fix(scaffold/frontend): make the default app an idiomatic eis-chat-grade reference and derive its name from the project #1333, docs(tutorials): no tutorial demonstrates the page builder — every tutorial underleverages NetScript, and the MCP-served docs will teach the wrong patterns #1208 still open in 0.0.5.
• House milestone-shift pattern (verified twice): rename-in-place highest→lowest, create freed title afterward, per-issue move reasons.
• RFC practice is RFC-shaped tracking issues (RFC: OpenAPI→MCP — making a service's own API legible to the agent building it (#1117) #1123 exemplar), not rfcs/NNNN-*.md files (zero exist on main).
• Label reality: 123 live vs 71 in labels.yml; status:close-gate-override/docs-eval:skip documented but absent live; wave:* labels dead in practice.

Note: this commit also carried the first 8 domain files under research/repo-audit/ written by the still-running second workflow (wf_03b88126-e7e); their supervisor review lands with S2b.

Next: S2b — repo/docs domain audit + external comparisons (eis-chat, meta-frameworks, oRPC).

[rickylabs]

[PHASE: RESEARCH] — S2b landed: repo/docs domain audit + external bar (e0d3c3883); Stage B complete

Workflow wf_03b88126-e7e (11 Opus 5 subagents, 1.78M tokens, 905 tool calls, read-only) delivered research/repo-audit/ (8 domains) + research/external/ (eis-chat, meta-frameworks, oRPC). Several verdicts are execution-verified (#1249 reproduced byte-identical; isDefinedError→never proven by executed deno check; registry 66-vs-50 counted by deno eval). Supervisor reviewed all 11 before this sign-off commit.

Highest-leverage findings:

• SDK/auth seam (pre-plan RFC A confirmed, sharpened): CreateServiceClientOptions is a closed 9-field record — no headers/interceptors/plugins/fetch/link seam; createHttpClientLink unexported; server auth reads Authorization/x-api-key but the typed client cannot send either. The scaffold's own template leaves /api public and a framework test codifies it.
• oRPC: pin 1.14.6 vs 1.14.15 public-export diff is identical — every extension gap is NetScript wrapper erasure, not the pin. oRPC ships 6 interceptor arrays + 3 plugin arrays + typed errors + RPCLink.headers (the native credential seam). v2 beta restricts RPC verbs → consolidate transport policy before v2.
• Generation seams: ui:add page emits a useSignal(0) counter + empty queryLoaders, and resolveProjectRoot targets the workspace root while the app lives in apps/<name>/ — the missing-seam story includes a mis-rooted existing verb. No verb emits the contract-derived client/query module for a second service.
• Docs: four P0 breaks all on the contract→client→page seam (three names for one module; two incompatible query APIs both taught as canonical); docs:accuracy is a fixed-string needle checker that passes through all of it.
• Runtime: shipped sample job discards the saga publish receipt (new uncovered p0, mirrored verbatim in docs); STREAMS_DATA_DIR referenced by nothing (durable streams always in-memory); background children have zero health checks — the root enabler of green-but-dead; 5 of 6 saga span factories have zero callers (compensation invisible in traces).
• Board corrections: fix(fresh/query): island query types reject the package's own documented patterns #1245 ~75% fixed by merged fix(fresh): converge SDK and island cache tiers #1265 (rescope, don't re-implement); Type soundness ratification: eliminate unsound and arbitrary types across the public surface and the docs #1278 inventory stale (one as unknown as left in the web layer); fix(triggers): generated background runtime omits the Redis adapter and crash-loops on the default Aspire cache #1325/fix(streams): DurableStreamProducer permanently drops writes after an initial connection failure; reconnect is never attempted #1326/fix(cli): db migrate reports success in headless mode without creating the migration implied by the command #1327/fix(streams): documented SSE consumer shape differs from the wire protocol and does not specify the standard event/OTEL envelope #1329/docs(data/contracts): show generated DB schemas as the normative predecessor to API contracts in DB-backed products #1332 open with zero landed commits.
• External bar: eis-chat proves every needed API exists — the gap is scaffold/generation + discovery; SvelteKit remote functions + TanStack Start serialization checks are the typed-data frontier; NetScript's genuine differentiation is first-party saga/compensation + Aspire graph + plugin-seam uniformity + agent-native surface.

Next: Stage C synthesis (SYNTHESIS.md) → Stage D design packs.

[rickylabs]

[PHASE: PLAN] — S4 landed: design packs (33adc65d7); Stage D complete

Workflow wf_ebfe8327-306 (7 Opus 5 subagents, 1.25M tokens) + supervisor additions delivered the full draft board:

• 41 issue drafts across three proposed milestone directories: 0.0.6-verification-docs-rfcs (13: RFC trackers, canonical-dialect docs p0, compile-the-docs gate, MCP wiring, quality/fresh-ui/doctrine hygiene), 0.0.7-typed-seams-generation (12: oRPC seam re-exposure, typed errors, transport consolidation, auth + trace-context contribution dogfoods, route-slice + client/query generators, resolveProjectRoot, ui:add triad, /design sync, defect fixes), 0.0.8-runtime-truth-service-slice (19: saga receipts p0, child liveness, stream durability, saga telemetry, auth defect cluster with four p0s, service layout, command kit, E2E truth gates, Wave-7 smoke as exit gate).
• RFC-A (SdkClientContribution, 755 lines) and RFC-B (command composition kit) as full drafts in rfcs/.
• EXISTING-ISSUE-AMENDMENTS.md (929 lines, 16 quotable amendment blocks: Type soundness ratification: eliminate unsound and arbitrary types across the public surface and the docs #1278 fold of epic(quality): ratify and eliminate unsound types — no as-unknown-as, no arbitrary any, no conceded TS errors #1276, docs: migration chapter — per-framework guides, compatibility matrix, and e2e migration recipes #1279 fold of epic(docs): migration chapter — migrate-from guides, capability equivalence matrix, and end-to-end migration recipes #1275, fix(fresh/query): island query types reject the package's own documented patterns #1245 rescope, fix(scaffold/frontend): make the default app an idiomatic eis-chat-grade reference and derive its name from the project #1333/Epic: Scaffold conformance — generated surfaces match current docs, exports and idiomatic usage #1335/docs(web-layer): differentiator deep-dives + competitive tutorial benchmark — per-API sub-pages for the page builder (withResource, Partials, …) #1210/docs(tutorials): no tutorial demonstrates the page builder — every tutorial underleverages NetScript, and the MCP-served docs will teach the wrong patterns #1208/Epic: Frontend contribution layer — plugins that ship UI #922 expansions, hygiene batch).
• ISSUE-DEDUP-AND-SUPERSESSION.md now carries the complete disposition of existing issues + all 41 new rows + a Stage-E ledger.

Quality note: every pack re-verified corpus claims at source before drafting, producing six corrections now recorded in the dedup §3.1 — most notably the wave-6 ServiceReferences claim has worktree counter-evidence (T4-07 drafted verify-first, not as implementation), and arch:check:repo's 7-week accepted-red decomposes into 52 A14 false positives + one missing --root (two cheap fixes, not package debt). Supervisor reviewed all packs before sign-off; deviations (TA-03 a/b/c split, two priority raises to p0) accepted with recorded rationale.

All 44 files carry the — DRAFT (no GitHub mutation; owner ratification pending) H1 marker (grep-verified). Zero board mutation performed.

Next: Stage E plan lock — MASTER-PLAN.md, IMPLEMENTATION-HANDOFF.md, plan.md, PR body refresh, closing statement.

[rickylabs]

[PHASE: PLAN] [VERDICT: LOCKED — awaiting owner review] — Stage E complete (1d6c6a70f); seed run finished

The complete long-range remediation plan is committed under .llm/runs/plan-fable5-remediation-roadmap--seed/fable-5-remediation-plan/. Reading order for review: MASTER-PLAN.md (start with §7, the 12-fork owner sweep) → MILESTONE-TRAIN.md → ISSUE-DEDUP-AND-SUPERSESSION.md (incl. §3 Stage-E ledger) → the three milestones/ directories (41 drafts) → rfcs/ (RFC-A, RFC-B) → EXISTING-ISSUE-AMENDMENTS.md → WAVE7-AND-AGENT-ADOPTION.md → IMPLEMENTATION-HANDOFF.md. Everything traces to the 19-artifact corpus in research/.

Program in one paragraph: the gap is not missing capability but a product surface that contradicts it — one central seam (contract → typed client → query → page) broken across docs, generation, API sealing, and runtime proof. The plan lands five contracts (typed extension chain RFC-A; generated canonical vertical slice; service slice + command kit RFC-B; runtime truth; agent-native surface) across two inserted milestones (0.0.7 typed seams + generation, 0.0.8 runtime truth + service slice) with 0.0.5 closing as scoped, RFCs ratifying in 0.0.6, existing 0.0.7–0.0.13 shifting to 0.0.9–0.0.15 by title-only rename (every issue retained), and a Wave-7 measured A/B/C adoption smoke as the exit gate before #922's train resumes.

Owner decisions requested: forks F1–F12 in MASTER-PLAN.md §7 (milestone insertion, #922 timing, duplicate-umbrella folds, RFC mechanism, dialect choice, receipt mechanism, Wave-7 scale, and five more) — each with a reversible default. Plus whether to run the later adversarial pass / PLAN-EVAL the waiver deferred.

Closing statement: No GitHub issue, epic, milestone, project, label-set, or comment mutation occurred in this run. The only GitHub writes were this draft PR's own branch/commits/body/comments/PR-labels. All 44 draft files carry the no-mutation H1 marker; filing happens once, from the committed manifest, only after owner ratification, in a separately authorized session. Evaluator waivers (PLAN-EVAL, IMPL-EVAL) are recorded in supervisor.md/worklog.md/drift.md and do not extend to future implementation runs. Worktree is clean; all 9 commits pushed with the explicit refspec.

[rickylabs]

[PHASE: FILING] [VERDICT: COMPLETE]

Owner-ratified Stage H is complete. The milestone train was shifted highest-first, fresh 0.0.6 and 0.0.7 milestones were created, the full former-0.0.6 membership was preserved, and all 41 roadmap issues (#1348–#1388) were filed and audited. Live dependencies use live issue numbers; 20 additive existing-owner amendments were posted; no issue was closed.

Durable receipt: fable-5-remediation-plan/FILING-LOG.md (1ef78e29f). GitHub is now authoritative; this PR remains draft and must not be merged.

[rickylabs]

[PHASE: REVIEW] — Cross-RFC PLAN-EVAL advisory (RFC-A #1390 × RFC-B #1389)

Both RFC PLAN-EVALs are complete (owner-designated cross-family evaluator: this Fable 5 session; generators: Codex Sol xhigh; deep dives: 3× Opus 5 xhigh, recorded). Both verdicts: CHANGES_REQUESTED, FAIL_PLAN cycle 1 — full findings on each PR and in each run's plan-eval.md (f1a29fe1a, 122301d25). Durable cross-RFC record: fable-5-remediation-plan/CROSS-RFC-REVIEW.md @ a4648d49d.

Cross-RFC verdict: they compose cleanly. No circular dependency (#1350 is a shared one-way stage-0/1 prerequisite); error policies are disjoint by construction (local preparation failures vs route-opt-in contract errors, both deferring client typing to #1350's literal-preserving spelling — whichever lands first establishes it, the other reuses it); context/telemetry ownership does not overlap (transport-owned trace headers vs persisted W3C row context). Sequencing matches the filed train (ratify 0.0.6 → RFC-A impl 0.0.7 → RFC-B impl 0.0.8).

Headline findings: RFC-A — the zero-oRPC-symbol gate fails on unchanged code (ContractLike carries '~orpc'), the server query-key algebra's public 3-tuples are unaddressed, streaming reconnect freezes credentials under prepare-once, the desktop transport bypasses contributions, and the v2 amendment has the GET decision inverted (GET is on today; v2 rejects it by default). RFC-B — the receipt-claim unique-violation algorithm is unspecified (PG transaction poisoning), relay-port package ownership is a hole that can invert the dependency arrow, and the reuse-vs-reinvent decision against @netscript/queue's existing claim/lease/DLQ mechanics is missing. Both cores survived adversarial verification — every repair is a scoped amendment.

Board: existing children #1348–#1364 are sufficient — no duplicates needed; the named amendments (#1351 OTel-rename/pin-policy/dedupe-trap, #1349 channel/port-location/key-algebra, #1350 stage-0 spelling, #1362/#1363 relay-ownership + PrismaTransactionClient deliverable) are listed in the cross-RFC record for owner-ratified application. Recommended after acceptance: one new oRPC-v2-migration RFC tracking issue with the exact scope/dependency list in CROSS-RFC-REVIEW.md §3 — not filed by this evaluator; no board mutation occurred.

Handoff: root orchestrator resumes both Codex generators with their finding lists (branch HEADs f1a29fe1a / 122301d25, both status:plan); cycle 2 is the last before escalation. The Qwen 3.8 Max adversarial pass waits until both RFCs reach APPROVED.

[rickylabs]

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

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: synthesized-after-iteration-limit
Housekeeping: ack=success trace=success commit-artifacts=success replies=skipped draft-pr=skipped
Trace: .llm/tmp/run/openhands/pr-1347/run-31279410211-1 (in the Actions artifact)
Artifact: openhands-agent-31279410211-1

OpenHands Agent Summary — INCOMPLETE (iteration limit)

The agent hit the maximum iterations limit (400) before
finishing the task. Any commits on the branch reflect partial work;
treat claims of completed artifacts as unverified.

Re-trigger with a narrower task or a higher iterations= value.

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