Wave 3 — @netscript/plugin host (A4) [generator sub-branch]

.llm/harness/debt/arch-debt.md

@@ -197,9 +197,24 @@ Seeded from
 - **Target:** 2026-Q3 doctrine remediation.
 - **Linked plan:** `.llm/tmp/run/doc-harness-doctrine-refactor--harness-v2-plan/plan.md`
 - **Created:** 2026-04-29
-- **Status:** open
+- **Status:** closed 2026-06-08 — Wave 3 `@netscript/plugin` host track verified the old
+  monolithic `types.ts` no longer exists. The package now exposes role-named `src/domain/`,
+  `src/ports/`, `src/config/`, `src/cli/`, `src/sdk/`, `src/testing/`, and diagnostics surfaces
+  through curated entrypoints. Remaining builder size debt is tracked separately below.
 - **Gate:** F-1, F-3, F-5, F-11
 
+## packages/plugin/src/config/builders/plugin-builder.ts — F-1 size (360 LOC)
+
+- **Reason:** `plugin-builder.ts` remains above the doctrine 300 LOC planning cap (343 LOC at base
+  `89071df`, 360 LOC after Wave 3 added public JSDoc in slice 4). It is a typestate-generic fluent
+  builder and splitting it during Wave 3 risks breaking the public chain.
+- **Owner:** Wave 3 `@netscript/plugin` host generator.
+- **Target:** Pre-beta builder refactor.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave3-plugin--host/plan.md` (LD-3, slice 19).
+- **Created:** 2026-06-08
+- **Status:** open, DEBT_ACCEPTED
+- **Gate:** F-1, A4 builder split follow-up
+
 ## packages/plugin/src/sdk/discovery/ast-extractor.ts — PLG-WALKER-AST (extractor precision)
 
 - **Reason:** Group G needs walker-generated registries now, but a full TypeScript AST resolver with

.llm/tmp/run/feat-package-quality-wave3-plugin--host/commits.md

@@ -0,0 +1,61 @@
+# Commits — feat-package-quality-wave3-plugin--host
+
+Branch: `feat/package-quality-wave3-plugin-host` → umbrella `feat/package-quality-wave3-plugin`
+
+| # | SHA | Subject | Slice(s) |
+|---|-----|---------|----------|
+| seed | (this commit) | chore(wave3): seed @netscript/plugin host run docs | — |
+| 1 | 22557b8 | docs(wave3): record @netscript/plugin research, plan, and design checkpoint | Research + Plan & Design |
+| 2 | 0c1b2a1 | fix(plugin): clear private type refs | Slice 1 |
+| 3 | 19f2915 | docs(wave3): record slice 1 private-type-ref fix | Slice 1 docs |
+| 4 | 1a7e71e | docs(plugin): document abstract contributions part one | Slice 2 |
+| 5 | 2beed40 | docs(wave3): record slice 2 abstract docs | Slice 2 docs |
+| 6 | b598f3b | docs(plugin): document abstract contributions part two | Slice 3 |
+| 7 | c4abbde | docs(wave3): record slice 3 abstract docs | Slice 3 docs |
+| 8 | a308a2e | docs(plugin): document builder errors and memory adapter | Slice 4 |
+| 9 | 9cadaa4 | docs(wave3): record slice 4 builder docs | Slice 4 docs |
+| 10 | d4262ad | docs(plugin): document sdk discovery contracts | Slice 5 |
+| 11 | 02feec4 | docs(wave3): record slice 5 sdk docs | Slice 5 docs |
+| 12 | 177ed3c | docs(plugin): document cli and port contracts | Slice 6 |
+| 13 | 5e51001 | docs(wave3): record slice 6 cli docs | Slice 6 docs |
+| 14 | 65a7c41 | docs(plugin): verify config and testing docs | Slice 7 |
+| 15 | 290de80 | docs(wave3): record slice 7 doc verification | Slice 7 docs |
+| 16 | bd1e594 | test(plugin): verify full export doc lint | Slice 8 |
+| 17 | 2fda337 | docs(wave3): record slice 8 doc-lint gate | Slice 8 docs |
+| 18 | f6e7189 | docs(plugin): expand readme quality sections | Slice 9 |
+| 19 | 63976f5 | docs(wave3): record slice 9 readme expansion | Slice 9 docs |
+| 20 | 5d7ed3a | test(plugin): align readme examples with quick start | Slice 10 |
+| 21 | 2bdc7af | docs(wave3): record slice 10 readme doctest | Slice 10 docs |
+| 22 | 5e9f751 | docs(plugin): document sdk dynamic import caveat | Slice 11 |
+| 23 | de6eda5 | docs(wave3): record slice 11 sdk caveat | Slice 11 docs |
+| 24 | f283836 | chore(plugin): add lint and fmt tasks | Slice 12 |
+| 25 | c7feaf3 | docs(wave3): record slice 12 task hygiene | Slice 12 docs |
+| 26 | 17d60ea | chore(plugin): check all public entrypoints | Slice 13 |
+| 27 | 846d85e | docs(wave3): record slice 13 check task | Slice 13 docs |
+| 28 | 7de2e22 | test(plugin): cover domain errors and core types | Slice 14 |
+| 29 | 1092b17 | docs(wave3): record slice 14 domain tests | Slice 14 docs |
+| 30 | 33b1a59 | test(plugin): cover memory file system adapter | Slice 15 |
+| 31 | f50d4b8 | docs(wave3): record slice 15 adapter test | Slice 15 docs |
+| 32 | b8e44c6 | test(plugin): cover watcher cleanup handle | Slice 16 |
+| 33 | 0bcbaa8 | docs(wave3): record slice 16 watcher test | Slice 16 docs |
+| 34 | 214a9a3 | test(plugin): cover plugin manifest loader | Slice 17 |
+| 35 | 7997c5a | docs(wave3): record slice 17 loader test | Slice 17 docs |
+| 36 | 3279d7b | test(plugin): verify full test suite | Slice 18 |
+| 37 | f0de70f | docs(wave3): record slice 18 full tests | Slice 18 docs |
+| 38 | 8f3c204 | docs(arch): update plugin builder debt | Slice 19 |
+| 39 | d2cf7fb | docs(wave3): record slice 19 arch debt | Slice 19 docs |
+| 40 | 4968dd5 | docs(wave3): record plugin fitness evidence | Slice 20 |
+| 41 | 3fac166 | docs(wave3): record slice 20 evidence update | Slice 20 docs |
+| 42 | 7a24d51 | test(plugin): verify cli consumer imports | Slice 21 |
+| 43 | 055b2d0 | docs(wave3): record slice 21 cli consumer | Slice 21 docs |
+| 44 | c2c1eec | test(plugin): verify plugin package consumers | Slice 22 |
+| 45 | b29969f | docs(wave3): record slice 22 plugin consumers | Slice 22 docs |
+| 46 | 9f96342 | test(plugin): verify final static gates | Slice 23 |
+| 47 | cd66346 | docs(wave3): record slice 23 static gates | Slice 23 docs |
+| 48 | 0458b4d | test(plugin): run merge readiness e2e cli | Slice 24 |
+| 49 | (this commit) | docs(wave3): record slice 24 e2e carry-forward | Slice 24 docs |
+
+(append one row per slice during Implement; pair each slice commit with its
+`docs(wave3): record …` run-doc commit, per the Wave 2 cadence.)
+- 10da21e: docs(wave3): record PLAN-EVAL PASS + lock LD-8 for @netscript/plugin host
+- eed130d: docs(wave3): record IMPL-EVAL PASS for @netscript/plugin host + fix builder LOC drift

.llm/tmp/run/feat-package-quality-wave3-plugin--host/context-pack.md

@@ -0,0 +1,167 @@
+# Context Pack — Wave 3 host: `@netscript/plugin` (A4)
+
+Run ID: `feat-package-quality-wave3-plugin--host`
+Branch: `feat/package-quality-wave3-plugin-host`
+Base: umbrella `feat/package-quality-wave3-plugin` @ `89071df` (= track `f2a7ff2` + umbrella seed)
+PR target: `feat/package-quality-wave3-plugin` (umbrella) — **not** the track.
+Role: SEED for the Research → Plan & Design phases, authored by the SUPERVISOR
+session. **Not** a PLAN-EVAL or IMPL-EVAL artifact.
+
+> Read the **umbrella context-pack** first — it holds the full deep-dive:
+> `.llm/tmp/run/feat-package-quality-wave3-plugin--umbrella/context-pack.md`.
+> This file is the generator-facing entry point and does not duplicate it.
+
+## Phase status
+
+- Research + Plan & Design: complete (committed).
+- **PLAN-EVAL: PASS** (2026-06-08, separate session) — see `plan-eval.md`. One
+  rework-forcing decision resolved in-line as **LD-8** (upstream-typed `private-type-ref`
+  → package-owned structural types, not upstream re-export; preserves F-15/AP-14). Carry
+  LD-8 into slice 1. **Implementation may now begin.**
+- Implementation: slice 1 complete. Commit `0c1b2a1` fixes all `private-type-ref` errors; full-export
+  doc-lint now has no `private-type-ref` matches and 100 planned `missing-jsdoc` errors for slices
+  2-7.
+- Implementation: slice 2 complete. Commit `1a7e71e` documents the first abstract contribution
+  group and reduces full-export doc-lint to 86 remaining missing-JSDoc errors.
+- Implementation: slice 3 complete. Commit `b598f3b` documents the remaining abstract contribution
+  group and reduces full-export doc-lint to 69 remaining missing-JSDoc errors.
+- Implementation: slice 4 complete. Commit `a308a2e` documents builder/error/adapter exports and
+  reduces full-export doc-lint to 48 remaining missing-JSDoc errors.
+- Implementation: slice 5 complete. Commit `d4262ad` documents SDK discovery/application/runtime
+  members and reduces full-export doc-lint to 23 remaining missing-JSDoc errors.
+- Implementation: slice 6 complete. Commit `177ed3c` documents CLI/base contracts and
+  `FileSystemPort`; full-export `deno doc --lint` now passes across all 8 entrypoints. Slice 7 is
+  a no-op verification/doc-record slice because the planned config/testing JSDoc targets already
+  have no remaining lint errors.
+- Implementation: slice 7 complete. Empty commit `65a7c41` records the no-op verification for
+  config-domain/validators/testing JSDoc targets; full-export doc-lint remains clean.
+- Implementation: slice 8 complete. Empty commit `bd1e594` verifies full-export doc-lint remains
+  clean across all 8 entrypoints. Phase A is complete.
+- Implementation: slice 9 complete. Commit `f6e7189` expands README to 165 LOC and adds
+  Observability, Compatibility, and Required Permissions sections.
+- Implementation: slice 10 complete. Commit `5d7ed3a` aligns the README fixture with the current
+  quick start and passes the focused doctest fixture.
+- Implementation: slice 11 complete. Commit `5e9f751` documents the `./sdk`
+  `ModuleManifestResolver` dynamic-import caveat; publish dry-run succeeds with the expected warning.
+- Implementation: slice 12 complete. Commit `f283836` adds package-local `lint` and `fmt` tasks,
+  fixes task-surfaced `require-await` findings in synchronous promise-returning stubs, and verifies
+  lint/fmt/check/doc-lint gates.
+- Implementation: slice 13 complete. Commit `17d60ea` expands `tasks.check` to all 8 public
+  entrypoints with `--unstable-kv`.
+- Implementation: slice 14 complete. Commit `7de2e22` adds dedicated domain tests for errors and
+  core types; 3 focused tests pass.
+- Implementation: slice 15 complete. Commit `33b1a59` adds memory file-system adapter conformance
+  coverage; 1 focused test passes.
+- Implementation: slice 16 complete. Commit `b8e44c6` adds watcher cleanup coverage; 2 focused
+  tests pass.
+- Implementation: slice 17 complete. Commit `214a9a3` adds plugin manifest loader coverage; 2
+  focused tests pass.
+- Implementation: slice 18 complete. Empty commit `3279d7b` records full package test-suite
+  verification: 21 passed, 0 failed.
+- Implementation: slice 19 complete. Commit `8f3c204` closes obsolete `types.ts` debt and opens
+  accepted F-1 debt for `plugin-builder.ts` size with a pre-beta target.
+- Implementation: slice 20 complete. Commit `4968dd5` adds manual F-1..F-18 evidence to
+  `worklog.md`; F-13 is recorded as n/a for A4.
+- Implementation: slice 21 complete. Empty commit `7a24d51` records `packages/cli`
+  consumer-import validation; `deno check --unstable-kv mod.ts` and `deno task check` pass.
+- Implementation: slice 22 complete. Empty commit `c2c1eec` records `plugins/*`
+  consumer-import validation; all first-party plugin package checks pass.
+- Implementation: slice 23 complete. Empty commit `9f96342` records the final static
+  gate sweep: publish dry-run succeeds with 0 slow types and the documented dynamic-import
+  warning; check, lint, fmt --check, and full-export doc-lint pass.
+- Implementation: slice 24 complete. Empty commit `0458b4d` records the merge-readiness
+  `e2e:cli` run: 35 gates passed, `behavior.triggers-health` failed with the locked LD-4
+  `localhost:8093/health` connection refusal, and cleanup passed. This remains a Wave 4
+  carry-forward, not a Wave 3 implementation blocker.
+- Generator handoff status: ready for separate IMPL-EVAL. Do not merge PR #15 from this
+  session.
+- **IMPL-EVAL: PASS** (2026-06-08, separate session) — see `evaluate.md`. Evaluator
+  independently re-ran static + fitness gates (`check`/`lint`/`fmt --check`/full-export
+  `doc --lint` = 0/`test` = 21 pass/`publish:dry-run` = 0 slow types) and the `packages/cli`
+  consumer gate; verified LD-8 (package-owned schema types, F-15 clean) and the debt delta.
+  One low-severity drift corrected in-line (builder 343→360 LOC). `e2e:cli` triggers-health
+  is the locked LD-4 Wave 4 carry-forward. **Wave 3 host unit is merge-ready into the umbrella.**
+
+## One-unit wave
+
+`@netscript/plugin` only. Archetype **A4 — DSL/Builder (plugin host)**. Gate set
+**F-1..F-12, F-14..F-18** (F-13 n/a) + required consumer-import validation + static
+gates, per `.llm/harness/gates/archetype-gate-matrix.md`. No sub-wave split.
+
+## Phase 0 reading (read only what the task needs)
+
+1. Umbrella context-pack (above) — scope, baseline, deltas, caveats, Concept of Done.
+2. `.llm/harness/archetypes/ARCHETYPE-4-*.md` + `gates/archetype-gate-matrix.md` (A4 row).
+3. `.llm/harness/lessons/{package-quality-archetype,validation,sub-wave-orchestration,platform}.md`
+   — the Wave 2 playbook. **package-quality is architectural, not type/lint cleanup.**
+4. Canonical (stale, structural intent only):
+   `…/copilot-evaluate-…/plan_plugin.md` §§2–5, `evaluate_plugin.md`. Treat all
+   numbers as pre-rewrite.
+5. Focused code: `packages/plugin/deno.json`, `mod.ts`, `src/public/mod.ts`, the 8
+   exports entrypoints, `loader.ts`, `src/config/builders/plugin-builder.ts`,
+   `src/sdk/runtime/*`, `src/diagnostics/inspect-plugin.ts`.
+
+For internal API shape prefer `deno doc packages/plugin/mod.ts` and
+`deno doc --filter <symbol>` over reading whole files.
+
+## Research step (MEASURE-FIRST — mandatory before locking the plan)
+
+The canonical evaluate (5 files, 33 slow types, 0 tests) is **stale**; the package
+is already hexagonal with docs + tests. Re-measure at base `89071df` and record real
+numbers in `research.md` / `drift.md`:
+
+- `deno publish --dry-run --allow-dirty` from `packages/plugin` (real slow-type count).
+- Full-export `deno doc --lint` over **all 8** entrypoints (`.`, `./abstracts`,
+  `./config`, `./cli`, `./loader`, `./sdk`, `./testing`, `./templates`) — root-only
+  undercounts; see `lessons/validation.md`.
+- README length / 14-section coverage (currently 139 LOC).
+- Test adequacy vs A4 layers (doctest · domain · port-contract · adapter conformance ·
+  runtime lifecycle · DSL/builder ergonomics).
+- `deno check --unstable-kv` over all entrypoints (the shipped `tasks.check` only
+  covers `mod.ts` — F-6 gap).
+
+## Open questions for Plan & Design (resolve in the plan; do not pre-decide)
+
+- **OQ-A `./loader` dynamic import:** does `loader.ts`'s `await import(source)` still
+  block publish (slow types / unanalyzable) ? Keep `./loader` public, internalize it,
+  or document the runtime-resolvability caveat? Decide with dry-run evidence.
+- **OQ-B vocabulary reconciliation:** canonical `plan_plugin.md` §2 wants
+  `src/{public,domain,ports,application,adapters,runtime,presentation,diagnostics,
+  testing,internal}`. Repo already has most, plus `config/`, `cli/`, `sdk/`,
+  `abstracts/`, `kernel/`. Align names or accept the rewrite's vocabulary? Verify
+  zero external consumers before any subpath/folder rename (alpha = no shims, but
+  prove it first). F-11 forbids `utils/`/`interfaces/`; F-16 cardinality must hold.
+- **OQ-C file-size (F-1):** `plugin-builder.ts` 344 LOC and `docs/plugin-author-guide.md`
+  372 LOC vs the doctrine cap — split, or accept with debt?
+- **OQ-D `e2e:cli` triggers-health:** is the `localhost:8093/health` failure a
+  plugin-host bootstrap defect (in `src/sdk/runtime/`) or downstream `plugin-triggers`
+  (Wave 4)? Investigate before scoping; if downstream, record as carried-forward, do
+  not fix here.
+- **OQ-E `./testing` + defensive I/O:** the host owns watchers/timers
+  (`sdk/discovery/watcher.ts`, `presets/start-watcher.ts`). Plan an abort/cleanup test
+  and confirm the `./testing` contract surface is exercised.
+- **OQ-F diagnostic axis:** confirm `inspectPlugin` is exported from `mod.ts` and
+  returns a structured `InspectionReport`.
+
+## Concept of Done
+
+See the umbrella context-pack § "Concept of Done". In short: dry-run 0 slow types;
+full-export doc-lint 0; README/docs at STANDARDS bar + doctested; A4 test layers;
+F-1..F-18 (minus F-13) green or accepted-debt; consumer-import validation green;
+task hygiene (`check` all entrypoints + `lint`/`fmt`/`publish:dry-run`).
+
+## Slice discipline (carry the Wave 2 cadence)
+
+One commit per slice, each with a single named gate, paired with a
+`docs(wave3): record …` run-doc commit. Renames as `git mv`-only slices with the
+static gate deferred to the retarget slice (record the transient-failure expectation
+in `drift.md`). Final slices: consumer-import gate, then `deno task e2e:cli` once as
+merge-readiness (escalate out-of-scope runtime failures, do not block — see
+`lessons/validation.md`).
+
+## Process boundaries (Harness v2)
+
+- Generator, PLAN-EVAL, IMPL-EVAL are each a SEPARATE session. Evaluator ≠ generator.
+- Never delete lock files/caches; never `deno cache --reload` without approval.
+- Record every plan deviation in `drift.md`.
+- Targeted `deno check` must pass `--unstable-kv`.