fix(spec): address CodeQL alerts in gen:schema/gen:docs scripts (#3012)

- build-schemas.ts: read the ratchet manifest directly and treat ENOENT
  as first-run bootstrap instead of existsSync-then-read (TOCTOU).
- build-docs.ts: escape backslashes before pipes in table-cell
  descriptions — an existing `\|` would otherwise decay into an escaped
  backslash followed by a live pipe, splitting the GFM cell.

No output changes: regenerated json-schema/ and references/ are
byte-identical.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fn6qMKtJeVbs2KzouWDHhB

Author: claude

packages/spec/scripts/build-docs.ts

@@ -213,9 +213,13 @@ function generateMarkdown(schemaName: string, schema: any, category: string, zod
       for (const [key, prop] of Object.entries(props) as [string, any][]) {
           const typeStr = formatType(prop).replace(/\|/g, '\\|');
           const isReq = required.has(key) ? '✅' : 'optional';
-          // Escape literal pipes last — this cell lives in a GFM table row, where
-          // an unescaped `|` (even inside a code span) splits the cell.
-          const desc = escapeMdxDescription((prop.description || '').replace(/\n/g, ' ')).replace(/\|/g, '\\|');
+          // Escape for the GFM table cell last: backslashes first (so an existing
+          // `\|` in a description can't decay into an escaped backslash + live
+          // pipe), then pipes — an unescaped `|` (even inside a code span)
+          // splits the cell.
+          const desc = escapeMdxDescription((prop.description || '').replace(/\n/g, ' '))
+            .replace(/\\/g, '\\\\')
+            .replace(/\|/g, '\\|');
           t += `| **${key}** | \`${typeStr}\` | ${isReq} | ${desc} |\n`;
       }
       return t + '\n';

packages/spec/scripts/build-schemas.ts

@@ -281,11 +281,13 @@ interface SchemaManifest {
 }
 
 let manifest: SchemaManifest | null = null;
-if (fs.existsSync(MANIFEST_PATH)) {
-  try {
-    manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf-8')) as SchemaManifest;
-  } catch (error) {
-    console.error(`\n❌ Failed to parse ${MANIFEST_PATH}: ${error}`);
+try {
+  manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf-8')) as SchemaManifest;
+} catch (error) {
+  // A missing manifest just means first run (bootstrap below); anything else
+  // (unreadable, invalid JSON) must fail rather than silently drop the ratchet.
+  if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+    console.error(`\n❌ Failed to read ${MANIFEST_PATH}: ${error}`);
     process.exit(1);
   }
 }