Retire PLAN.md: split into docs/ + AGENTS.md; dangling tasks -> issues #1-#16

PLAN.md's roles are redistributed:
- docs/architecture.md: goals/non-goals, compatibility targets, the
  architecture, the JSPI frame rule, concurrency, CABI decisions, perf,
  bindgen, caching (+ the trust-boundary lean), conformance, risks.
  Section numbers 1-11 preserved exactly so existing citations rewrite
  mechanically.
- docs/milestones.md: the verified milestone record (S0-C3), residuals
  pointing at tracking issues.
- docs/consumers.md: the polymorph adoption track (jco blocker mapping,
  Deno-substitutes-Node evidence, in-repo ports inventory).
- docs/references.md: canonical upstream links.
- AGENTS.md: the development protocol (authorities, gates, multi-agent
  dispatch/review/recovery rules) - loaded automatically by agent sessions.
- README: documentation index replaces the PLAN pointer.

Dangling tasks migrated to issues #1-#16 (wasmtime bump, mosh deep E2E,
webcrypto families, iroh UDP, bridge-exclusivity review, CI, code-cache
check, P1 executor, fuzzing, FinalizationRegistry policy, Safari/JSC,
memory64/threads, xfail residues, polymorph upstreaming, upstream filings,
versioned releases).

Reference sweep: ~90 files of PLAN.md citations rewritten to the new
locations (contracts, runtime/harness comments, generated bindgen headers
regenerated - digests unchanged, xfail reasons now cite issues). Gates:
runtime 318/0, bindgen+translator-shim green, conformance table
byte-identical (1250/0/99/41/5). Also fixes the PLAN reference in the
just-landed ci.yml (parallel work, e60ea4a).

Author: lann

.github/workflows/ci.yml

@@ -150,7 +150,8 @@ jobs:
       - name: firefox lane (required — JSPI pref set by the driver)
         run: deno run -A tools/browser/run-lane.ts firefox
 
-      # WebKit is best-effort per PLAN §13/§14: the lane's expectation overlay
+      # WebKit is best-effort per docs/architecture.md §3/§12 (issue #11): the
+      # lane's expectation overlay
       # encodes JSC's missing multi-memory; GH's ubuntu-24.04 matches the ABI
       # playwright's WebKit wants, so no library staging should be needed —
       # but the lane stays non-blocking until it has a track record.

AGENTS.md

@@ -0,0 +1,109 @@
+# deltic — development protocol
+
+Instructions for agents (and context for humans) working in this repo. The
+repo was built by a multi-agent workflow and its discipline is part of the
+project: unusually dense objective gates are what make delegated
+implementation safe.
+
+## Authorities
+
+- Semantic tie-breaker for runtime behavior: the Component Model spec +
+  `design/mvp/canonical-abi/definitions.py` (in the
+  `third_party/component-model` submodule), with wasmtime as corroborating
+  evidence — never the other way around. See
+  [docs/architecture.md](docs/architecture.md) §1 for the parity policy.
+- Interface contracts between workstreams live in `contracts/` (plan format,
+  descriptor IR, intrinsics, digest, embedder API). **Contract changes are
+  versioned events made only by the orchestrator**; implementation tracks
+  report contract friction, they never edit around it.
+- Design and decisions: [docs/architecture.md](docs/architecture.md).
+  Milestone record: [docs/milestones.md](docs/milestones.md). Consumer
+  track: [docs/consumers.md](docs/consumers.md). Upstream links:
+  [docs/references.md](docs/references.md).
+
+## Gates (exact commands)
+
+Run the ones your change can affect; a full pass before commit looks like:
+
+```sh
+cargo build --workspace
+cargo test -p translator-shim -p bindgen -p testgen
+(cd runtime && deno task check && deno task test)
+(cd harness && deno task conformance)        # official CM suite, Deno lane
+(cd wasi-shims && deno task test)
+(cd ct-runner && deno task test)
+(cd ports/websocket && deno task test)       # + deno task conformance (spawns their echod)
+(cd ports/webcrypto && deno test --allow-read tests/)
+(cd ports/webrtc && deno test -A webrtc.test.ts)
+deno run -A tools/browser/run-lane.ts chromium   # firefox / webkit likewise
+deno run -A --unstable-net exams/iroh-endpoint/run.ts   # needs iroh-relay on PATH
+```
+
+Scheduler-order sensitivity: rerun affected suites with `DELTIC_SCHED_SEED=1`
+and `=4242` (seeded-shuffle mode; FIFO when unset).
+
+Conformance discipline: the harness fails loudly on unexpected failures *and*
+on stale xfails; per-browser deltas live in `harness/browser/expectations/`
+with stale-delta detection. Never absorb a regression into an xfail/overlay
+without a named class and a tracking issue.
+
+## Multi-agent protocol
+
+Work is parallelized across model-pinned subagents defined in the operator's
+**global** opencode config — deliberately not vendored into this repo, so all
+repo-specific context (contracts, spec authorities, gates) travels in each
+dispatch prompt.
+
+| Agent | Model | Role |
+|---|---|---|
+| orchestrator (primary session) | fable | planning, contracts, dispatch, integration, review, **all commits** |
+| `coder` | sonnet | implementation tracks against pinned contracts |
+| `coder-hard` | opus | subtle tracks: shim internals, CABI edge cases, scheduler periphery |
+| `reviewer` | fable | parallel code review when the orchestrator is the bottleneck |
+| `explore` | haiku | fast read-only codebase search |
+
+Dispatch rules:
+
+- Every track prompt names: **territory** (paths owned), **governing
+  contracts** (`contracts/*.md` + design-doc sections), and **gates** (exact
+  commands). Territories are disjoint across concurrent tracks.
+- Subagents never commit (permission-enforced); the orchestrator commits
+  after review.
+- The task-scheduler **core** is single-owner (coherence risk):
+  `coder-hard` at most, under close orchestrator review; parallelism stays at
+  the periphery.
+
+Review protocol: every track is reviewed against its contracts before commit
+— by the orchestrator inline, or by `reviewer` subagents in parallel. A
+review dispatch **must** name the diff scope, the governing `contracts/*.md`,
+and — for anything touching CABI/async semantics —
+[docs/architecture.md](docs/architecture.md) §5–§7 plus the spec sources
+(`definitions.py` as tie-breaker): the reviewer judges only against named
+authorities and flags unnamed ones rather than filling gaps from memory.
+Revision rounds go back to the *same* coder session via `task_id` (context
+intact), not a fresh agent.
+
+Failure recovery (content-filter false positives, driver interrupts): an
+aborted `task` call kills neither the child session (context persists in the
+opencode db) nor its effects (files/commands persist on disk). Ladder:
+
+1. Locate the orphan (`opencode-agent-sessions <parent-session-id>`, on
+   PATH); resume via `task_id` — "summarize status, then continue".
+2. Two failed resumes → assume poisoned context: fresh agent, handoff prompt
+   = original track + "partial work exists, audit state first" + artifact
+   pointers. Gates arbitrate what's already done.
+3. Repeated failures across fresh contexts → escalate to the human; the
+   trigger may live in the artifacts themselves.
+
+Standing rules:
+
+- After any fan-out, reconcile launched-vs-completed before proceeding — a
+  missing result is not missing work.
+- Consumer checkouts (the polymorph family, under `~/p/polymorph/`) are
+  **strictly read-only**: verify `git status` in any consumer tree you ran
+  commands near, before and after. Build artifacts go to `/tmp` or a
+  redirected `CARGO_TARGET_DIR`, never into consumer trees.
+- Findings against foreign repos go in the tracker files
+  (`upstream-component-model-repo-findings.md`,
+  `upstream-consumer-findings.md`), not inline notes; filing them is the
+  operator's call.