@event4u/agent-config 14.23.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/layered-settings.md

@@ -0,0 +1,317 @@
+# Layered Settings
+
+Three-file settings model: **team defaults** (committed),
+**user-global DX-comfort defaults** (per-developer, cross-project), and
+**developer overrides** (per-project, git-ignored). Lets a project pin
+decisions, a developer carry DX preferences across every project, and
+project-local choices always win.
+
+Referenced by `road-to-project-memory.md` Phase 0 and
+`road-to-portable-dev-preferences.md`. Consumed by the centralized
+settings loader at
+[`scripts/_lib/agent_settings.ts`](../../../src/scripts/_lib/agent_settings.ts),
+the `/onboard` command, and any agent that edits `.agent-settings.yml`
+on user request.
+
+## The three files
+
+| File | Git | Scope | Owner | Example values |
+|---|---|---|---|---|
+| `.agent-project-settings.yml` | **committed** | team / repo | lead maintainer | `project.stack`, `quality.php.tools`, `memory.dogfood` |
+| `~/.event4u/agent-config/agent-settings.yml` | **n/a** (outside repo) | individual developer · cross-project | individual | `name`, `ide`, `rule_loading_tier`, `personal.bot_icon`, `personal.autonomy`, `memory.cadence` (legacy `~/.config/agent-config/agent-settings.yml` read as fallback) |
+| `agents/settings/.agent-settings.yml` | **gitignored** | individual developer · this project | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel`, `onboarding.onboarded` | <!-- ref-ignore -->
+
+> **Canonical location (ADR-038):** the developer file lives in the settings
+> layer at `agents/settings/.agent-settings.yml` (alongside <!-- ref-ignore -->
+> `.agent-settings.local.yml`, `contexts/`, `policies/`). A repo-root
+> `.agent-settings.yml` is read as a **back-compat fallback** and is migrated
+> into the canonical location by `install` on the next run.
+
+All three are YAML. Schemas:
+
+- Developer (project-local): [`agent-settings.md`](../../templates/agent-settings.md).
+- Team: [`agent-project-settings.example.yml`](../../../src/agent-src/templates/agents/agent-project-settings.example.yml).
+- User-global: six exact dotted paths — whitelist in
+  [`scripts/_lib/agent_settings.ts`](../../../src/scripts/_lib/agent_settings.ts).
+
+## Merge order
+
+Lowest priority → highest priority:
+
+```
+1. Package defaults                                   (shipped by event4u/agent-config)
+2. ~/.event4u/agent-config/agent-settings.yml         (user-global · whitelist-filtered · legacy ~/.config/agent-config/ read as fallback)
+3. .agent-project-settings.yml                        (team file, committed)
+4. agents/settings/.agent-settings.yml                (developer file, gitignored; legacy repo-root .agent-settings.yml read as fallback — ADR-038) <!-- ref-ignore -->
+```
+
+Keys from higher layers win unless a lower layer marks them
+`locked` (team file only). The user-global file does **not** support
+`locked` — its purpose is cross-project comfort, never policy.
+
+## User-global whitelist
+
+Only these exact dotted paths are mergeable from the user-global file;
+every other key is silently dropped by the loader. The whitelist is
+intentionally tiny — adding a key requires an ADR.
+
+```
+name
+ide
+rule_loading_tier
+personal.bot_icon
+personal.autonomy
+```
+
+Loader contract:
+
+- **Read-only.** The loader never creates, modifies, or deletes the
+  user-global file. Writes are the exclusive responsibility of the
+  `/onboard` command on explicit user opt-in.
+- **Tolerant.** Missing file, malformed YAML, empty file — all fall
+  back to the next tier without raising.
+- **Silent on out-of-whitelist keys.** `verbose=True` logs which keys
+  were dropped for debugging; default mode is silent.
+- **Never auto-creates `~/.event4u/agent-config/`** (nor the legacy
+  `~/.config/agent-config/`). The new directory is created by the
+  migration shim or by `/onboard` on opt-in; key installation also
+  `mkdir -p`s as needed.
+
+## Lock semantics
+
+`.agent-project-settings.yml` has a top-level `locked_keys` list.
+Any key listed there cannot be overridden from `.agent-settings.yml`:
+
+```yaml
+# .agent-project-settings.yml
+quality:
+  php:
+    tools: [phpstan, rector, ecs]
+
+locked_keys:
+  - quality.php.tools
+```
+
+Even if a developer's `.agent-settings.yml` sets
+`quality.php.tools: [pint]`, the resolved value stays
+`[phpstan, rector, ecs]`. The loader emits a one-line warning
+when it ignores a locked override.
+
+### When to lock
+
+- **Correctness** — test framework, database driver, seeder ordering.
+- **Compliance** — code style enforced by CI.
+- **Team-wide rituals** — mandatory pre-commit checks.
+
+### When NOT to lock
+
+- Personal preferences — IDE, output verbosity, name.
+- Performance knobs the developer should tune to their hardware.
+- Anything that slows down onboarding without a correctness payoff.
+
+Err on the side of **not** locking. Every locked key reduces
+autonomy. Unlock by removing the entry from `locked_keys` — no
+migration needed.
+
+## Migration from a single file
+
+Repos that currently ship only `.agent-settings.yml` (often
+mistakenly committed) migrate by:
+
+1. Create `.agent-project-settings.yml` from the example template.
+2. Move team-wide keys (`project.*`, `quality.*`, `memory.*`,
+   `review_routing.*`, `roles.*`) into the new file.
+3. Leave personal keys (`personal.*`, `subagents.*`, `github.*`)
+   in `.agent-settings.yml`.
+4. Commit `.agent-project-settings.yml`.
+5. Confirm `.agent-settings.yml` is in `.gitignore`; add it if not.
+6. Remove any previously-committed `.agent-settings.yml` from the
+   repo history only if it leaked personal tokens. Otherwise leave
+   it — future commits supersede.
+
+The `/onboard` command and any agent that edits settings on user
+request should walk steps 1–3 and 5 automatically when it detects
+a one-file setup.
+
+## .gitignore expectations
+
+```
+# .gitignore
+.agent-settings.yml              # developer-local, NEVER committed
+.agent-settings.backup.*         # migration backups
+!.agent-project-settings.yml     # explicitly NOT ignored
+```
+
+The final negated entry protects the team file if a broader
+pattern (e.g. `*.yml` in a nested folder) would otherwise match.
+
+## Consumption
+
+- **Skills** read settings via the loader, never by parsing YAML
+  directly. The loader returns the merged view already.
+- **Commands** that mutate settings must state which layer they
+  write to. Writing to the wrong layer is a spec bug.
+- Writes to either file MUST follow the [section-aware merge
+  rules](#section-aware-merge-rules) — preserve existing values,
+  template order, and comments. No ad-hoc YAML rewrites.
+
+## Module discovery
+
+Module-aware skills and commands (`module-management`, `/module
+explore`, `/module create`, roadmap-writing) consult the `modules:`
+block on the **team** layer
+([`agent-project-settings.example.yml`](../../../src/agent-src/templates/agents/agent-project-settings.example.yml))
+to find module roots, namespace conventions, and per-module
+`agents/` folders. Lives next to `project.stack` because it
+describes the same thing — repo layout.
+
+| Key | Default | Purpose |
+|---|---|---|
+| `modules.enabled` | `false` | Master switch; when off, every module-aware surface treats the repo as flat |
+| `modules.root_paths` | `[]` | Repo-relative directories whose direct children are modules |
+| `modules.namespace_template` | `""` | Substitution template (`{ModuleName}`) for stacks with a PHP-style namespace |
+| `modules.agent_folder` | `"agents"` | Per-module folder the agent auto-loads on `/module explore <Name>` |
+| `modules.skip_dirs` | `[".module-template", ".example"]` | Directory names skipped during enumeration |
+
+Stack-by-stack starting points (manual setup; the installer fills
+these on opt-in when it detects a known shape):
+
+```yaml
+# Laravel HMVC
+modules:
+  enabled: true
+  root_paths: [app/Modules]
+  namespace_template: "App\\Modules\\{ModuleName}\\App"
+
+# Symfony DDD-lite (or PHP with a single src tree)
+modules:
+  enabled: true
+  root_paths: [src]
+  namespace_template: "App\\{ModuleName}"
+
+# Node monorepo
+modules:
+  enabled: true
+  root_paths: [packages]
+  namespace_template: ""
+
+# Go internal layout
+modules:
+  enabled: true
+  root_paths: [internal]
+  namespace_template: ""
+```
+
+Multi-root repos list each root once; enumeration walks every
+listed root and merges results.
+
+Lock via `locked_keys: [modules.root_paths]` when the layout must
+not drift between developers — typical for compliance-critical or
+multi-team repos.
+
+## Persona-list merge semantics
+
+Persona configuration does **not** follow the simple "higher layer
+wins" rule — lists merge with explicit override and ignore hooks.
+
+| Key | Layer | Role |
+|---|---|---|
+| `personas.default` | project | Team default cast (list of ids) |
+| `personas.specialists.auto_include` | project | Specialists auto-added on every multi-lens run |
+| `personas.override` | developer | Full replacement of `personas.default` for this developer (empty = inherit) |
+| `personas.ignore` | developer | Ids dropped from the effective cast |
+| `.augmentignore` | workstation | Persona files physically hidden from the agent |
+
+**Resolution order** for the effective cast of a multi-lens skill:
+
+1. Start with `personas.default` from the project file.
+2. If `personas.override` is non-empty, **replace** the list (not merge).
+3. Add every id from `personas.specialists.auto_include`.
+4. Remove every id from `personas.ignore`.
+5. Remove every id whose file is matched by `.augmentignore`.
+6. If the skill's own frontmatter pins `personas: [...]`, that wins
+   over all of the above — the skill is the authority for its own
+   cast.
+
+An id removed in step 4 or 5 stays **invokable** via explicit
+`--personas=<id>` on the skill invocation. Ignore hides the id from
+the default cast; it does not blacklist it.
+
+If the project locks `personas.default` via `locked_keys`, steps 2
+and 4 are ignored with a one-line warning — the developer cannot
+narrow a team-locked cast.
+
+## Section-aware merge rules
+
+Any agent that writes `.agent-settings.yml` or
+`.agent-project-settings.yml` on the user's behalf (including
+`/onboard`, `/set-cost-profile`, and ad-hoc "change value X" requests)
+MUST follow these rules. Initial file creation and legacy migration
+are owned by `scripts/install.ts`; these rules govern every edit
+after that.
+
+The contract is **additive merge with user-line preservation** —
+the user's file is the ground truth, the template only contributes
+keys the user is missing. Round-trip parser and merger live in
+[`scripts/sync_yaml_rt.ts`](../../../src/scripts/sync_yaml_rt.ts); the
+supported YAML subset (block-mappings, scalars, lists, comments,
+CRLF/LF) is documented in its module docstring. The stdlib-only
+choice (vs. `ruamel.yaml`) and its revisit triggers are recorded in
+[`docs/contracts/adr-settings-sync-engine.md`](../../contracts/adr-settings-sync-engine.md).
+
+For each section in the template
+([`agent-settings.md`](../../templates/agent-settings.md)):
+
+- For each key under the section:
+  - **Key exists in user's file** → keep the user's line **verbatim**
+    (value, quoting, inline comment, indent — all preserved).
+  - **Key missing** → insert the template's line at the position
+    after the user's last preceding sibling that is also in the
+    template (max-index insertion).
+- **Unknown sections/keys** the user has added → preserved verbatim
+  at their existing position. They are not moved to a trailing
+  `_user:` block, not re-prefixed, not flattened.
+
+Invariants:
+
+- **User order wins.** Template order is only consulted to decide
+  where to insert missing keys; existing user keys are never
+  reordered.
+- Existing scalar values are **never overwritten** unless the user
+  asked for that specific change.
+- New keys added to the template land with their default value and
+  the template's leading comments.
+- **User comments are preserved verbatim** on every existing key.
+  Template comments only land with keys the merger inserts; once a
+  key is in the user's file, its surrounding comments are owned by
+  the user.
+- Legacy `_user._user.foo` corruption (accumulated by older buggy
+  syncs) heals on the next sync — the leading `_user.` chain is
+  stripped and the leaf is re-homed at its template path, or kept
+  as a single-level orphan under `_user:` if no template home
+  exists.
+- Write with 2-space indent, no tabs, no trailing whitespace.
+- Never commit — `.agent-settings.yml` is git-ignored.
+- If a legacy flat `.agent-settings` (key=value) is still present,
+  stop and tell the user to run `scripts/install` — migration is the
+  installer's job, never the agent's.
+
+Template drift (new keys shipped by a package update) is resolved by
+re-running `scripts/install` or by the agent walking these rules on
+the next explicit settings edit.
+
+## Anti-patterns
+
+- **Do NOT** commit `.agent-settings.yml`. It contains developer
+  identity and potentially secrets.
+- **Do NOT** put personal preferences in `.agent-project-settings.yml`.
+  The team file is not a place to publish your IDE choice.
+- **Do NOT** lock every key "just to be safe". Locking is an
+  intervention, not a default.
+- **Do NOT** merge settings in skill code. The loader owns the
+  merge; duplicating it creates drift.
+
+## See also
+
+- [`agent-settings.md`](../../templates/agent-settings.md) — dev-layer schema
+- [`agent-project-settings.example.yml`](../../../src/agent-src/templates/agents/agent-project-settings.example.yml) — team-layer template

package/dist/agent-src/guidelines/agent-infra/linked-projects-onboarding-gate.md

@@ -0,0 +1,80 @@
+# Linked-Projects Onboarding Gate
+
+> IDE-attached sibling repo detection, one-time opt-in flow, persistence shape, and the cross-repo behavioral directive
+
+_Origin: migrated from `src/rules/linked-projects-onboarding-gate.md` per the P4 pattern of `road-to-kernel-and-router.md`._
+
+**Iron Law.** When the IDE has attached a sibling repository to this project
+and the sibling is not yet recorded in `linked_projects`, prompt the developer
+**once** to opt it into scope, persist the choice local-only, and thereafter
+proactively flag cross-repo impact — never bulk-include the sibling's files.
+
+This closes the **proactivity gap**: the agent can already read/write a sibling
+repo, but it does not *consider* one unless told — and the developer who most
+needs cross-repo awareness is precisely the one who won't think to mention the
+sibling. Detection reads the relationship the developer already encoded by
+attaching the repo in their IDE (zero-knowledge). See the cross-repo guide
+(`docs/guides/cross-repo-linked-projects.md`) and ADR-032.
+
+## When this fires
+
+First substantive turn of a session (and on a new IDE attachment), when a
+detected sibling is absent from `linked_projects` in `.agent-settings.local.yml` (in agents/settings/).
+Inert when no sibling is attached, or when every detected sibling already has a
+recorded decision (opted-in or declined).
+
+## Detection
+
+Run the detector against the project root:
+
+```bash
+./scripts-run src/scripts/_lib/linked_projects detect .
+
+```
+
+It returns config-attached siblings only (PhpStorm `.idea/modules.xml` +
+`vcs.xml`, VS Code `*.code-workspace`) that resolve outside the project, exist,
+and are git repos. A sibling above `linked_projects_max_files` (default 20000)
+carries `"large": true` — surfaced as awareness only, never excluded.
+
+## Opt-in (one-time per sibling)
+
+For each detected sibling **not** already in `linked_projects`, ask once
+(numbered options per `user-interaction`): include it / decline it / always /
+never-ask. Persist to `.agent-settings.local.yml` (in agents/settings/) (the gitignored per-machine
+layer — never the committed `.agent-settings.yml`):
+
+```yaml
+linked_projects:
+  - path: /abs/path/to/sibling
+    include: true        # false = declined; never re-prompt
+```
+
+A declined sibling (`include: false`) is never prompted again.
+
+## Behavioral directive (for each `include: true` sibling)
+
+While that sibling is in scope, the agent:
+
+- **proactively checks cross-repo impact** when a change here may affect it —
+  API-contract changes, shared-type / enum drift, renamed routes the sibling
+  consumes — and **warns** before finishing;
+- **does not bulk-include** the sibling's files in context (passive awareness,
+  not implicit inclusion — large repos stay cheap);
+- treats out-of-root edits to the sibling as normal work, but the host agent's
+  own out-of-root **permission gate still applies** (no silent cross-repo write).
+
+## Kill-switch
+
+This is an experimental, removable rule. If opt-in is consistently declined or
+siblings are never cited, remove it — no telemetry, the signal is local.
+
+## Follow-up (not yet shipped)
+
+- Consumer-install detector reachability: ✅ shipped 2026-05-30 — the detector is
+  now exposed as `agent-config linked-projects:list` (closes the ADR-032
+  follow-up); cross-repo retrieval over opted-in siblings ships as
+  `/knowledge:cross-repo`.
+- Multi-agent verification: only Claude Code was empirically validated
+  (ADR-032). Cursor / Augment / Copilot behavior is unverified — the manual
+  fallback in the guide covers them until tested.

package/dist/agent-src/guidelines/agent-infra/mcp-request-signing.md

@@ -0,0 +1,197 @@
+# MCP Request Signing (HMAC-SHA256)
+
+Reference guideline for signing JSON-RPC requests crossing any non-stdio
+MCP transport — HTTP, SSE, WebSocket, anything routable. Stdio over a
+trusted parent-child pipe is **outside** the scope of this guideline; only
+network-exposed transports require signing.
+
+Lands ahead of any HTTP-MCP transport so the security floor is in place
+when one becomes a real consumer use case (paired with the allowlist
+gate tracked in the active mcp-server plate under `agents/roadmaps/`).
+
+Adapted from an external reference — the request-signing primitive
+(`CRYPTO_SEG`). The full Express bridge (~1.6k LOC) stays out of
+scope; this guideline takes the **primitive**, not the runtime.
+
+## When signing is mandatory
+
+- Any HTTP / SSE / WebSocket MCP transport — the wire is shared with
+  arbitrary callers.
+- Any cross-host stdio bridge (parent and child on different machines).
+- Any MCP server reachable from a browser context.
+
+## When signing is **not** required
+
+- Plain stdio MCP server invoked as a child process by one trusted client
+  on the same host. The OS pipe is the trust boundary.
+- Local-only loopback served behind a Unix domain socket with `0700`
+  permissions on the socket file.
+
+If unsure → sign. The cost is one HMAC per request.
+
+## Signing pattern (~30 LOC reference)
+
+`KERNEL_SECRET` is a per-installation shared secret loaded from env or a
+secrets store. Never commit it. `randomUUID()` is Node's
+`crypto.randomUUID`.
+
+```js
+import { createHmac, randomUUID } from 'node:crypto';
+
+const KERNEL_SECRET = process.env.MCP_KERNEL_SECRET;
+const KERNEL_ID = `mcp-kernel-${process.pid}`;
+
+function signRequest(payload) {
+  const timestamp = Date.now();
+  const nonce = randomUUID();
+  const data = `${timestamp}:${nonce}:${JSON.stringify(payload)}`;
+  const signature = createHmac('sha256', KERNEL_SECRET)
+    .update(data)
+    .digest('hex');
+  return { timestamp, nonce, signature, kernelId: KERNEL_ID };
+}
+
+// On every outbound MCP request:
+const sig = signRequest(body);
+headers['X-MCP-Kernel'] = sig.kernelId;
+headers['X-MCP-Signature'] = sig.signature;
+headers['X-MCP-Timestamp'] = String(sig.timestamp);
+headers['X-MCP-Nonce'] = sig.nonce;
+```
+
+Header names are project-namespaced; the upstream the external runtime file uses
+`X-RVF-*`, the convention here is `X-MCP-*`.
+
+## Verification pattern (server-side counterpart)
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const KERNEL_SECRET = process.env.MCP_KERNEL_SECRET;
+const MAX_SKEW_MS = 5 * 60 * 1000;        // 5 min
+const seenNonces = new Map();             // nonce -> expiresAt
+
+function verifyRequest(headers, rawBody) {
+  const ts = Number(headers['x-mcp-timestamp']);
+  const nonce = headers['x-mcp-nonce'];
+  const sig = headers['x-mcp-signature'];
+  if (!ts || !nonce || !sig) return false;
+  if (Math.abs(Date.now() - ts) > MAX_SKEW_MS) return false;
+  if (seenNonces.has(nonce)) return false;          // replay
+  const data = `${ts}:${nonce}:${rawBody}`;
+  const expected = createHmac('sha256', KERNEL_SECRET).update(data).digest();
+  const got = Buffer.from(sig, 'hex');
+  if (got.length !== expected.length) return false;
+  if (!timingSafeEqual(got, expected)) return false;
+  seenNonces.set(nonce, Date.now() + MAX_SKEW_MS);
+  return true;
+}
+```
+
+`timingSafeEqual` is non-negotiable — `===` on a hex string is a timing
+oracle. The nonce store must evict on `expiresAt` to bound memory; a
+plain `setInterval` sweep every minute is enough.
+
+## Threat model
+
+| Threat | Mitigation in this pattern |
+|---|---|
+| **Replay** — attacker captures a valid request and resends it | `nonce` + `seenNonces` set; replays inside the skew window are rejected, replays outside it fail the timestamp check |
+| **MITM (non-stdio)** — wire-level rewrite | HMAC over `${ts}:${nonce}:${body}` — any payload tamper invalidates the signature; pair with TLS in production |
+| **Clock skew abuse** — long-lived request | `MAX_SKEW_MS = 5 min` rejects out-of-window timestamps |
+| **Timing oracle on signature compare** | `timingSafeEqual`, never `===` |
+| **Secret exfil via repo / log** | `KERNEL_SECRET` from env or secrets store; never log raw headers; redact `X-MCP-Signature` in any audit trail |
+| **Allowlist bypass** | Signing **does not** authorize what's called — pair with the allowlist enforced at server boot (mcp-server plate under `agents/roadmaps/`, Phase 4 **D4**); a valid signature on a non-allowlisted tool name still rejects |
+
+## Citation hooks
+
+- mcp-server plate under `agents/roadmaps/` — **Phase 4 D4** allowlist
+  enforced at server boot. Signing layers *under* the allowlist: verify
+  signature → look up tool in allowlist → execute. Both gates must pass.
+- mcp-server plate under `agents/roadmaps/` — **Phase 6 F2 / F3** SSE
+  transport, cloud bundle. These are the triggers that make this
+  guideline load-bearing; until then it is reference material for the
+  deferred-with-trigger HTTP-bridge slot tracked
+  (Phase 2 P2.1) under `agents/roadmaps/`.
+
+## Operational notes
+
+- **Secret rotation** — rotate `MCP_KERNEL_SECRET` on a fixed cadence
+  (90 days minimum). Both client and server reload from env on the next
+  request; in-flight requests fail and retry with the new secret.
+- **Multi-client deployments** — give every client kernel a distinct
+  `KERNEL_ID` so logs attribute to a source even though all use the
+  same shared secret.
+- **Don't sign `tools/list`** — `tools/list` is read-only metadata; it
+  can stay unsigned in deployments where the metadata itself is public.
+  `tools/call` must always be signed.
+
+## Out-of-scope
+
+- The full Express bridge in the external reference (~1.6k LOC,
+  HTTP routing, SSE streaming, auth proxying) — out of scope,
+  not forked. If we ever need an HTTP-MCP server, build on this
+  guideline + the host's web framework, not on the external runtime.
+- Asymmetric signing (Ed25519, ECDSA). HMAC-SHA256 is sufficient for
+  shared-secret deployments. Asymmetric is only worth the complexity
+  when keys cross trust boundaries the shared-secret model can't
+  represent.
+
+## Appendix — HTTP-bridge `stdio-kernel` pattern (reference)
+
+Portable shape of an external reference's stdio kernel (~250 LOC), on
+hand for the day a real HTTP-MCP consumer surfaces (`road-to-mcp-server.md`
+Phase 6 F2 / F3). Full file stays **out of scope**.
+
+**Trigger to inline more:** both — (a) Phase 1 ships stdio prompt fetch
+in ≥1 confirmed client, (b) ≥1 consumer surfaces a concrete HTTP-MCP
+use case. Until then, this appendix is the reference.
+
+### Pattern shape
+
+The kernel sits between the HTTP transport and the spawned stdio MCP
+child. Inbound: HTTP → `verifyRequest` → JSON-RPC onto child stdin.
+Outbound: child stdout → parsed → signed response → HTTP.
+
+```
+client ──HTTP──▶ kernel.verify ──stdin──▶ stdio MCP child
+client ◀─HTTP── kernel.sign  ◀─stdout── stdio MCP child
+```
+
+Six load-bearing pieces:
+
+1. **Process supervisor** — spawn with `stdio: ['pipe', 'pipe', 'inherit']`,
+   restart on exit with bounded backoff, SIGTERM on shutdown.
+2. **JSON-RPC framing** — newline-delimited JSON; buffer partial
+   stdout reads; drop unparseable frames with a logged warning, never
+   crash the bridge.
+3. **Request-id correlation** — kernel generates outbound `id`, maps
+   `kernelId → clientId`; slow calls can't cross-talk between HTTP
+   clients.
+4. **Verification gate** — `verifyRequest` (above) before stdin write;
+   failure is a 401, never a 500; never log the raw signature.
+5. **Allowlist enforcement** — after verify, look up the JSON-RPC
+   `method` in the boot-time allowlist (`road-to-mcp-server.md` **D4**).
+   Non-allowlisted → JSON-RPC `-32601 Method not found`; no enumeration
+   leak.
+6. **Backpressure** — bound the in-flight queue per kernel (the external runtime
+   uses 32); beyond it, return `429`. Otherwise a flood OOMs the child.
+
+### Out of this appendix
+
+Express routes / middleware / SSE upgrade — host web framework.
+The external reference's marketplace + `mcp__claude-flow__*` tools —
+never adopted (see the related internal roadmap Sunset path).
+Multi-tenant routing — out-of-scope until a consumer surfaces a
+tenancy requirement.
+
+### Citation hooks
+
+- `road-to-mcp-server.md` **Phase 6 F2 / F3** — SSE / cloud-bundle work
+  starts here; the upstream link is the authoritative source.
+- An internal roadmap (local-only) **P2.1** — landed this appendix;
+  full bridge fork stays out-of-scope unless the dual trigger fires.
+- [`mcp-cloud-scope.md`](../../contracts/mcp-cloud-scope.md) —
+  operationalizes this pattern as a TypeScript Cloudflare Worker (no
+  spawned stdio child; R2 blob replaces the child process). HMAC
+  `verifyRequest` is deferred to MVP-2 alongside auth.