[Wave 4] Runtimes & their plugins (9 units) — COMPLETE · all sub-waves IMPL-EVAL PASS · closeout → track

.agents/skills/aspire/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: aspire
+description: "Orchestrates Aspire distributed applications using the Aspire CLI for running, debugging, and managing distributed apps. USE FOR: aspire start, aspire stop, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire logs, add aspire resource, aspire dashboard, update aspire apphost. DO NOT USE FOR: non-Aspire .NET apps (use dotnet CLI), container-only deployments (use docker/podman), Azure deployment after local testing (use azure-deploy skill). INVOKES: Aspire CLI commands (aspire start, aspire describe, aspire otel logs, aspire docs search, aspire add), bash. FOR SINGLE OPERATIONS: Use Aspire CLI commands directly for quick resource status or doc lookups."
+---
+
+# Aspire Skill
+
+This repository uses Aspire to orchestrate its distributed application. Resources are defined in the AppHost project (`apphost.cs` or `apphost.ts`).
+
+## CLI command reference
+
+| Task | Command |
+|---|---|
+| Start the app | `aspire start` |
+| Start isolated (worktrees) | `aspire start --isolated` |
+| Restart the app | `aspire start` (stops previous automatically) |
+| Wait for resource healthy | `aspire wait <resource>` |
+| Stop the app | `aspire stop` |
+| List resources | `aspire describe` or `aspire resources` |
+| Run resource command | `aspire resource <resource> <command>` |
+| Start/stop/restart resource | `aspire resource <resource> start|stop|restart` |
+| Rebuild a .NET project resource | `aspire resource <resource> rebuild` |
+| View console logs | `aspire logs [resource]` |
+| View structured logs | `aspire otel logs [resource]` |
+| View traces | `aspire otel traces [resource]` |
+| Logs for a trace | `aspire otel logs --trace-id <id>` |
+| Add an integration | `aspire add` |
+| List running AppHosts | `aspire ps` |
+| Update AppHost packages | `aspire update` |
+| Search docs | `aspire docs search <query>` |
+| Get doc page | `aspire docs get <slug>` |
+| List doc pages | `aspire docs list` |
+| Environment diagnostics | `aspire doctor` |
+| List resource MCP tools | `aspire mcp tools` |
+| Call resource MCP tool | `aspire mcp call <resource> <tool> --input <json>` |
+
+Most commands support `--format Json` for machine-readable output. Use `--apphost <path>` to target a specific AppHost.
+
+## Key workflows
+
+### Running in agent environments
+
+Use `aspire start` to run the AppHost in the background. When working in a git worktree, use `--isolated` to avoid port conflicts and to prevent sharing user secrets or other local state with other running instances:
+
+```bash
+aspire start --isolated
+```
+
+Use `aspire wait <resource>` to block until a resource is healthy before interacting with it:
+
+```bash
+aspire start --isolated
+aspire wait myapi
+```
+
+### Applying code changes
+
+Choose the right action based on what changed:
+
+| What changed | Action | Why |
+|---|---|---|
+| AppHost project (`apphost.cs`/`apphost.ts`) | `aspire start` | Resource graph changed; full restart required |
+| Compiled .NET project resource | `aspire resource <name> rebuild` | Rebuilds and restarts only that resource |
+| Interpreted resource (JavaScript, Python) | Typically nothing — most run with file watchers | Restart the resource if no watch mode is configured |
+
+**Never restart the entire AppHost just because a single resource changed.** Use `aspire resource <name> rebuild` for .NET project resources — it coordinates stop, build, and restart for just that resource. Use `aspire describe --format Json` to check which commands a resource supports.
+
+### Debugging issues
+
+Before making code changes, inspect the app state:
+
+1. `aspire describe` — check resource status
+2. `aspire otel logs <resource>` — view structured logs
+3. `aspire logs <resource>` — view console output
+4. `aspire otel traces <resource>` — view distributed traces
+
+### Adding integrations
+
+Use `aspire docs search` to find integration documentation, then `aspire docs get` to read the full guide. Use `aspire add` to add the integration package to the AppHost.
+
+After adding an integration, restart the app with `aspire start` for the new resource to take effect.
+
+### Using resource MCP tools
+
+Some resources expose MCP tools (e.g. `WithPostgresMcp()` adds SQL query tools). Discover and call them via CLI:
+
+```bash
+aspire mcp tools                                              # list available tools
+aspire mcp tools --format Json                                # includes input schemas
+aspire mcp call <resource> <tool> --input '{"key":"value"}'   # invoke a tool
+```
+
+## Important rules
+
+- **Always start the app first** (`aspire start`) before making changes to verify the starting state.
+- **To restart, just run `aspire start` again** — it automatically stops the previous instance. NEVER use `aspire stop` then `aspire run`. NEVER use `aspire run` at all.
+- **Only restart the AppHost when AppHost code changes.** For .NET project resources, use `aspire resource <name> rebuild` instead.
+- Use `--isolated` when working in a worktree.
+- **Avoid persistent containers** early in development to prevent state management issues.
+- **Never install the Aspire workload** — it is obsolete.
+- **For Aspire API reference and documentation, prefer `aspire docs search <query>` and `aspire docs get <slug>`** over searching NuGet package caches or XML doc files. The CLI provides up-to-date content from aspire.dev.
+- Prefer `aspire.dev` and `learn.microsoft.com/microsoft/aspire` for official documentation.
+
+## Playwright CLI
+
+If configured, use Playwright CLI for functional testing of resources. Get endpoints via `aspire describe`. Run `playwright-cli --help` for available commands.

.agents/skills/netscript-doctrine/SKILL.md

@@ -114,6 +114,10 @@ migration plan and debt entry explicitly cover them.
   The doctrine is the single source of truth.
 - **Ignoring debt registry** — New violations must be recorded with a closing gate and owner.
   Unrecorded violations are `FAIL_DEBT`.
+- **Using raw root CLI output as package evidence** — For package/plugin quality gates, check, lint,
+  and formatting evidence should use the scoped wrappers under `.llm/tools/` with explicit roots,
+  `--ext ts,tsx`, and generated/future-wave excludes. Use doctrine file 09 for the full fitness-gate
+  rule.
 
 ## Reference Files
 

.agents/skills/netscript-harness/SKILL.md

@@ -62,6 +62,12 @@ this skill tells you what to load and in what order.
   self-certify.
 - **Carried-in plans as ground truth** — Re-baseline against current `main` before locking the plan.
 - **Monolithic commits** — Commit by slice, not by monolith. Each slice has its own gate.
+- **Raw root CLI noise as a verdict** — Package-quality check/lint/fmt evidence should use the
+  scoped wrappers `.llm/tools/run-deno-check.ts`, `.llm/tools/run-deno-lint.ts`, and
+  `.llm/tools/run-deno-fmt.ts`. They select explicit roots, file extensions, and excludes, then emit
+  compact structured output. Raw root `deno fmt --check` over Markdown, generated targets, or legacy
+  line-ending drift is not a package-quality verdict source unless the plan explicitly owns
+  repo-wide formatting.
 
 ## Run Artifacts
 

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

@@ -167,7 +167,12 @@ 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-09 — Wave 4c slice C13 split the saga transport monoliths in
+  `@netscript/plugin-sagas-core`: `src/transports/list-transport.ts` now owns the transport class
+  and stable public re-exports while list command/key/recovery mechanics live in
+  `src/transports/list-transport-commands.ts`; `src/transports/redis-transport.ts` was split the
+  same way into `src/transports/redis-transport-commands.ts`. All four files are below the F-1 cap
+  and the transport entrypoint still passes raw `deno check --unstable-kv`.
 - **Gate:** F-1, F-13
 
 ## packages/fresh — AP-1 / doctrine verdict Restructure (builders/mod.ts 1,110 LOC)
@@ -229,6 +234,38 @@ Seeded from
 - **Status:** open
 - **Gate:** PLG-WALKER-AST, F-5, F-11
 
+## packages/plugin-streams-core — AP-13 console.warn runtime reporting
+
+- **Reason:** `DurableStreamProducer` currently uses `console.warn` for connection, pending-event,
+  serialization, and primary-key visibility in published runtime code. The warnings are intentionally
+  retained for alpha operator visibility; replacing them correctly requires a structured telemetry or
+  logger dependency that is outside Wave 4a's package-quality scope.
+- **Owner:** `@netscript/plugin-streams-core` maintainers.
+- **Target:** Telemetry-integration wave before beta runtime stabilization.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave4-runtimes--4a-streams-watchers/plan.md`
+  (D6, slice 4).
+- **Created:** 2026-06-08
+- **Status:** open, DEBT_ACCEPTED.
+- **Gate:** F-14, AP-13; close when `DurableStreamProducer` emits through a structured reporter and
+  `console.warn` is absent from
+  `packages/plugin-streams-core/src/application/create-durable-stream.ts`.
+
+## packages/watchers — AP-13 console.warn runtime reporting
+
+- **Reason:** `FileWatcher` and `HybridWatchStrategy` currently use `console.warn` for native
+  watcher fallback and runtime access-failure visibility. The warnings are intentionally retained
+  for alpha operator diagnostics; replacing them correctly requires a structured telemetry or logger
+  dependency that is outside Wave 4a's package-quality scope.
+- **Owner:** `@netscript/watchers` maintainers.
+- **Target:** Telemetry-integration wave before beta runtime stabilization.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave4-runtimes--4a-streams-watchers/plan.md`
+  (S23 final debt sweep).
+- **Created:** 2026-06-08
+- **Status:** open, DEBT_ACCEPTED.
+- **Gate:** F-14, AP-13; close when watcher runtime warnings emit through a structured reporter and
+  `console.warn` is absent from `packages/watchers/src/file-watcher.ts` and
+  `packages/watchers/src/strategies/hybrid.ts`.
+
 ## packages/cli — AP-1 / doctrine verdict Restructure
 
 - **Reason:** `pipeline.ts` and `official-plugin-copier.ts` are monoliths; package should move

.llm/harness/gates/static-gates.md

@@ -5,20 +5,22 @@ package scope is involved.
 
 ## Gate Definitions
 
-| Gate             | Default command                                                            | Required when                                                | Evidence                      |
-| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------- |
-| Narrow typecheck | `deno check --unstable-kv <file-or-entry>`                                 | Small focused changes where workspace config is not required | command output or parser JSON |
-| Slice typecheck  | `deno task check:<slice>` piped to `.llm/tools/parse-deno-check-errors.ts` | Significant work or workspace-config-sensitive code          | parser JSON summary           |
-| Format check     | `deno task fmt --check` or targeted equivalent                             | Any committed docs/code where formatting matters             | command output                |
-| Lint             | `deno task lint` or narrow lint target                                     | Code changes; docs-only runs may skip with rationale         | command output                |
-| Doc lint         | `deno doc --lint <module>`                                                 | Public package exports, README/API docs, JSR work            | command output                |
-| Publish dry-run  | `deno publish --dry-run` from package                                      | Published package/plugin changes                             | command output                |
-| Link/path check  | focused filesystem check                                                   | Docs that reference local paths                              | list of checked paths         |
+| Gate             | Default command                                   | Required when                                                | Evidence                      |
+| ---------------- | ------------------------------------------------- | ------------------------------------------------------------ | ----------------------------- |
+| Narrow typecheck | `deno check --unstable-kv <file-or-entry>`        | Small focused changes where workspace config is not required | command output or parser JSON |
+| Slice typecheck  | `.llm/tools/run-deno-check.ts -- <check command>` | Significant work or workspace-config-sensitive code          | wrapper JSON summary          |
+| Format check     | `deno task fmt --check` or targeted equivalent    | Any committed docs/code where formatting matters             | command output                |
+| Lint             | `deno task lint` or narrow lint target            | Code changes; docs-only runs may skip with rationale         | command output                |
+| Doc lint         | `deno doc --lint <module>`                        | Public package exports, README/API docs, JSR work            | command output                |
+| Publish dry-run  | `deno publish --dry-run` from package             | Published package/plugin changes                             | command output                |
+| Link/path check  | focused filesystem check                          | Docs that reference local paths                              | list of checked paths         |
 
 ## Parser Preference
 
-Use `.llm/tools/parse-deno-check-errors.ts` for `deno check` and `deno task check:<slice>` output
-when possible. Fall back to raw output only if the parser cannot run.
+Use `.llm/tools/run-deno-check.ts` for `deno check` and `deno task check:<slice>` output when
+possible. It can run a scoped file selection directly, parse a saved log with `--input`, parse stdin
+with `--stdin`, or wrap a command after `--`. Fall back to raw output only if the wrapper cannot
+run.
 
 ## Documentation-Only Runs
 

.llm/harness/lessons/platform.md

@@ -2,50 +2,66 @@
 
 Source: supervisor sessions for `feat/package-quality` Wave 2 (2a–2c).
 
-These are environment gotchas that silently corrupt harness bookkeeping if not
-known up front. All confirmed on Windows 11 + PowerShell + RTK shell hook.
+These are environment gotchas that silently corrupt harness bookkeeping if not known up front. All
+confirmed on Windows 11 + PowerShell + RTK shell hook.
 
 ## RTK serves stale git reads
 
 The shell hook rewrites `git …` → `rtk git …`, and rtk caches read commands, so
-`git log`/`git rev-parse`/`git status` can lag reality (especially right after a
-remote merge). Symptoms: a branch tip that "won't update," a merge that "didn't
-happen."
+`git log`/`git rev-parse`/`git status` can lag reality (especially right after a remote merge).
+Symptoms: a branch tip that "won't update," a merge that "didn't happen."
 
 Bypass for ground truth:
 
 - `rtk proxy git <args>` — runs the raw command, no cache.
 - **Preferred for scripts:** spawn git directly with no shell, e.g.
-  `deno eval 'new Deno.Command("git",{args:[...]})'`, or use
-  `.llm/tools/git-verify.ts`. No shell = no rewrite = no cache.
+  `deno eval 'new Deno.Command("git",{args:[...]})'`, or use `.llm/tools/git-verify.ts`. No shell =
+  no rewrite = no cache.
 
 (Also captured in auto-memory `rtk-stale-git-cache`.)
 
 ## MSYS mangles `ref:path` colons
 
-In the Bash tool (MSYS), `git show <ref>:<path>` and similar `rev:path` forms get
-their colon path-mangled and fail or read the wrong thing. Work around by spawning
-git directly via `deno eval` (no shell translation), not by escaping.
+In the Bash tool (MSYS), `git show <ref>:<path>` and similar `rev:path` forms get their colon
+path-mangled and fail or read the wrong thing. Work around by spawning git directly via `deno eval`
+(no shell translation), not by escaping.
 
 ## Bash tool ≠ PowerShell here-strings
 
-The Bash tool runs **bash**, not PowerShell. A PowerShell `@'…'@` here-string
-passed to `git commit -m` leaks a literal `@` into the commit subject (observed:
-`@ chore(2c)…`). In the Bash tool use bash quoting or multiple `-m` flags; reserve
-`@'…'@` for the PowerShell tool only. If it slips through on a PR-less seed branch,
-`git commit --amend` + `git push --force-with-lease` is safe.
+The Bash tool runs **bash**, not PowerShell. A PowerShell `@'…'@` here-string passed to
+`git commit -m` leaks a literal `@` into the commit subject (observed: `@ chore(2c)…`). In the Bash
+tool use bash quoting or multiple `-m` flags; reserve `@'…'@` for the PowerShell tool only. If it
+slips through on a PR-less seed branch, `git commit --amend` + `git push --force-with-lease` is
+safe.
 
 ## `gh` CLI not on the Bash PATH
 
-The GitHub CLI is not reliably on PATH in the Bash tool here. Use the GitHub MCP
-tools instead (`pull_request_read`, `update_pull_request`, `merge_pull_request`,
-`create_pull_request`, `get_file_contents`, `create_or_update_file`). They also
-integrate with the permission UI.
+The GitHub CLI is not reliably on PATH in the Bash tool here. Use the GitHub MCP tools instead
+(`pull_request_read`, `update_pull_request`, `merge_pull_request`, `create_pull_request`,
+`get_file_contents`, `create_or_update_file`). They also integrate with the permission UI.
 
 ## Syncing a local track worktree without touching lock files
 
-When a stale local track worktree blocks a supervisor-doc commit and `deno.lock`
-has uncommitted churn: `git stash push -- deno.lock` (preserves, does not delete),
-then `git merge --ff-only origin/<track>`. Never delete lock files or run
-`deno cache --reload` without approval (Golden Rule 6). Leave intentional lock
-churn parked in the stash rather than committing it into a docs commit.
+When a stale local track worktree blocks a supervisor-doc commit and `deno.lock` has uncommitted
+churn: `git stash push -- deno.lock` (preserves, does not delete), then
+`git merge --ff-only origin/<track>`. Never delete lock files or run `deno cache --reload` without
+approval (Golden Rule 6). Leave intentional lock churn parked in the stash rather than committing it
+into a docs commit.
+
+## Root quality gates must exclude scratch and future-wave surfaces
+
+Root package-quality gates are verdict sources only when their file selection matches the current
+wave. `deno check .`, raw `deno lint`, and raw `deno fmt --check` can walk `.llm/tmp` scratch
+workspaces, generated scaffold output, Markdown, and packages intentionally deferred to later waves.
+Use explicit roots and excludes:
+
+- `.llm/tools/run-deno-check.ts --root packages --root plugins --ext ts,tsx --exclude <future/generated>`
+  for type-check verdicts. It defaults to `--unstable-kv` and can also parse saved/stdin command
+  output.
+- `.llm/tools/run-deno-lint.ts --root packages --root plugins --ext ts,tsx --exclude <future/generated>`
+  for lint verdicts.
+- `.llm/tools/run-deno-fmt.ts --root <owned roots> --ext ts,tsx --exclude <future/generated>` for
+  formatting verdicts.
+
+If raw root formatting reports line-ending-only drift in untouched legacy files, record it as
+baseline drift instead of normalizing hundreds of files in an unrelated wave.