scaffold-aip reads vendored specs (#1207) - #1622

Closes #1207. Supersedes #1537 — credit @charan-rathore for the original approach (reading the vendored tree instead of the sibling checkout); this lands the same idea rebased on the post-#1554 world.

Why

scripts/scaffold-aip.mjs was the only ts consumer still reaching for a sibling ../agentproto checkout (SPEC_DIR = resolve(TS_ROOT, "../agentproto/specs")) — which doesn't exist in checkouts/CI. scripts/check-spec-drift.mjs staged an entire temp tree (copy of the scaffolder + symlinked specs + a stub mdx) purely to work around that sibling path.

What

• scaffold-aip.mjs: specs now resolve from the VENDORED specs/resources tree (RESOURCES_DIR, override with --resources-dir). gray-matter + the aip-<N>.mdx frontmatter read are gone — title/description come from the JSON draft's title/description fields (generated templates keep their own gray-matter import; untouched). Strict arg parsing: unknown flags, missing flag values, and missing required flags all exit 2. A missing JSON draft is a hard error (the hasSchema TODO-stub fallbacks are deleted).
• Fail-closed refs: walkExternal now throws on a broken external $ref (message includes the ref and the mapped file path) instead of warn-and-replace-with-{}.
• check-spec-drift.mjs: spawns the real scaffolder directly with cwd: ROOT and diffs stdout against the checked-in schema.ts — stageTempTree, specDirCandidates, KNOWN_CODEGEN_MISSING, normalizeSchemaSrc and their imports are deleted. Coverage stays sandbox-only (widening to the other 27 packages is a separate later PR).

Tests

New scripts/scaffold-aip.test.mjs (8 cases, node --test): schema-only emission from the vendored draft, full scaffold in a fixture tree with a poisoned sibling ../agentproto/specs/aip-99.mdx (WRONG SIBLING never appears in stdout — the sibling is never read), --resources-dir nonexistent → exit 2, explicit --resources-dir → same result as default, unknown flag → 2, valueless flag → 2, missing required flags → 2, broken external ref → non-zero exit with no "replacing with empty schema".

Note on the brief's title assertion: --schema-only output renders the draft's root description (.describe(...)) but not the title, so the Test Doc title is asserted on the full-scaffold path's spec: status line instead (asserted in the isolation test, which doubles as the sibling-proof). Changing the schema-only header would have regressed sandbox schema.ts byte-drift, which this PR must not touch.

scripts/check-spec-drift.test.mjs rewritten: passes on the real sandbox draft, fails with /not found/ for a doctype with no vendored draft.

How verified

• node --test scripts/scaffold-aip.test.mjs → exit 0 (8/8)
• node --test scripts/check-spec-drift.test.mjs → exit 0 (2/2)
• node --test scripts/sync-specs.test.mjs → exit 0
• pnpm check:spec-drift → exit 0 ("spec↔codegen in sync for @agentproto/sandbox"); regen of the sandbox schema.ts is byte-identical to the checked-in file
• pnpm test → exit 0, pnpm check-types → exit 0 (fresh worktree, no ../agentproto sibling present)

No changeset: the diff touches scripts/** only (not a publishable package); pnpm changeset:ai confirmed "No @agentproto/* packages changed".

_{🤖 @agentproto-bot — PR · session sess_dbebb183 · pi · model openrouter/z-ai/glm-5.3-flash · host mac.home · cwd agentproto/f1207-wt}