fix(spec): keep internal tracker ids out of the published skill catalog

`check:doc-authoring` went red the moment `automation/io-node-config.zod.ts`
joined a package list: the generator publishes the first sentence of a module's
doc block, and that file's opens with a bare tracker citation. The gate has no
per-passage exemption, by design, and its argument is the audience -- `skills`
ships to customer projects and is loaded WHOLE into customer context windows,
where a tracker id resolves to nothing for the people paying for the tokens.

The gate prescribes stripping the id AT THE SOURCE and regenerating. That
remedy is not taken here, and the reasons are specific rather than convenient:
the source is a `.zod.ts` this card is forbidden to edit; it is a file the
package PUBLISHES, so editing it would change what `@objectstack/spec` ships
and reopen the changeset decision this PR settled from precedent; and the same
sentence is also projected to `content/docs/references/automation`, which would
drag a second generated tree into a diff whose surface is the skill catalog.
Three surfaces to remove one token.

The decisive measurement is that the gate does NOT flag that identical sentence
on the docs page: the rule is about the skill catalog specifically. So the
strip is applied at the boundary INTO that catalog, where the rule lives. Every
future pointer row is covered, rather than this one being corrected once.

The criterion is the gate's own, restated with a pin over the shapes that must
and must not match -- an ordinal, a hex colour, an over-long number and a
doubled hash all survive untouched.

This is a deviation from the gate's stated remedy and is flagged as such in the
PR body for a reviewer to overrule.

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

Author: claude

packages/spec/scripts/build-skill-references.ts

@@ -34,6 +34,7 @@ import {
   checkCoreEntryShape,
   checkSingleOwner,
   checkTransitiveAllowlist,
+  stripInternalIssueIds,
 } from './lib/skill-map-guards';
 
 // ── Paths ────────────────────────────────────────────────────────────────────
@@ -301,11 +302,11 @@ function extractDescription(filePath: string): string {
     const firstLine = lines[0];
     if (firstLine && firstLine.length > 5) {
       const clean = firstLine.replace(/^#+\s*/, '');
-      const sentence = clean.split(/\.\s/)[0];
+      const sentence = stripInternalIssueIds(clean.split(/\.\s/)[0]);
       return sentence.length > 120 ? sentence.slice(0, 117) + '...' : sentence;
     }
   }
-  return exportListDescription(content) ?? '';
+  return stripInternalIssueIds(exportListDescription(content) ?? '');
 }
 
 // ── Index generator ──────────────────────────────────────────────────────────

packages/spec/scripts/lib/skill-map-guards.ts

@@ -37,6 +37,56 @@
  * in the map.
  */
 
+// ── What the catalog may publish ─────────────────────────────────────────────
+
+/**
+ * The gate's criterion for an internal tracker id, restated.
+ *
+ * Same shape as `scripts/check-doc-authoring.mjs`'s `INTERNAL_ID_SOURCE`: three
+ * to five digits, so the ordinal "the #1 mistake" and a six-digit hex colour
+ * are both below/above it, and neither `##` nor an HTML entity's `&#` counts.
+ * Restated rather than imported because that gate is a `.mjs` in the repo root
+ * `scripts/` tree and exports nothing; the pin in
+ * `skill-map-guards.test.ts` holds the two spellings together by asserting the
+ * shapes that must and must not match.
+ */
+const INTERNAL_ISSUE_ID = /(?<![#&])#[0-9]{3,5}(?![0-9A-Za-z])/g;
+
+/**
+ * Drop internal issue ids from a line about to be published to `skills/**`.
+ *
+ * `skills/**` ships to customer projects and is loaded WHOLE into customer
+ * agent context windows, so `check:doc-authoring` refuses a tracker id there
+ * with no per-passage exemption -- a reader in a customer session has no
+ * tracker, no `git log` and no ADRs, and the token resolves to nothing for the
+ * audience paying for it (maintainer ruling 2026-08-12).
+ *
+ * The index rows are PROJECTED from module doc blocks in `packages/spec/src`,
+ * so a citation written for a repo reader becomes catalog prose the moment its
+ * schema joins a package's list -- which is exactly how
+ * `automation/io-node-config.zod.ts` arrived with `(#4045)` in its opening
+ * sentence. The same sentence is also published to
+ * `content/docs/references/**`, and the gate does NOT flag it there: the rule
+ * is about the skill catalog specifically. So the strip belongs at the BOUNDARY
+ * into that catalog rather than in the source, where it would rewrite a
+ * legitimate repo-facing citation, change bytes the package publishes, and drag
+ * the generated docs tree along.
+ *
+ * Sanitising here rather than refusing is deliberate and is the narrower of the
+ * two: a refusal would be satisfiable only by editing the schema source, which
+ * is what the paragraph above argues against. The class becomes impossible
+ * rather than corrected once -- no future pointer row can carry an id.
+ */
+export function stripInternalIssueIds(text: string): string {
+  return text
+    .replace(/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?=#[0-9]{3,5}(?![0-9A-Za-z]))/g, '')
+    .replace(INTERNAL_ISSUE_ID, '')
+    .replace(/\(\s*[,;·]?\s*\)/g, '')
+    .replace(/[ \t]{2,}/g, ' ')
+    .replace(/\s+([.,;:])/g, '$1')
+    .trim();
+}
+
 /** A `SKILL_MAP`-shaped value: skill name → its core schema paths. */
 export type SkillCoreMap = Record<string, readonly string[]>;
 

packages/spec/scripts/skill-map-guards.test.ts

@@ -38,6 +38,7 @@ import {
   checkCoreEntryShape,
   checkSingleOwner,
   checkTransitiveAllowlist,
+  stripInternalIssueIds,
   type SkillCoreMap,
 } from './lib/skill-map-guards';
 
@@ -181,6 +182,37 @@ describe('checkTransitiveAllowlist — a constraint that constrains nothing is r
   });
 });
 
+describe('stripInternalIssueIds — the catalog carries no tracker ids', () => {
+  it('drops a trailing citation and the parenthesis it sat in', () => {
+    expect(
+      stripInternalIssueIds('Config contracts for the flat IO builtins — `notify` and `http` (#4045).'),
+    ).toBe('Config contracts for the flat IO builtins — `notify` and `http`.');
+  });
+
+  it('drops the owner/repo spelling whole', () => {
+    expect(stripInternalIssueIds('removed in objectstack-ai/objectstack#4286 — use the rule'))
+      .toBe('removed in — use the rule');
+  });
+
+  it('drops a mid-sentence id and leaves one space behind', () => {
+    expect(stripInternalIssueIds('Metadata Protection Model — Phase 1 (#1234) and later'))
+      .toBe('Metadata Protection Model — Phase 1 and later');
+  });
+
+  // The other half of the criterion: what must survive. Each of these is a
+  // shape `check:doc-authoring` explicitly allows, so stripping it here would
+  // silently rewrite prose the gate never objected to.
+  it.each([
+    ['the #1 authoring mistake', 'an ordinal is one digit, below the floor'],
+    ['colour #ff00aa is the accent', 'a hex colour starts with no digit'],
+    ['id #123456789 is not a tracker id', 'nine digits is above the ceiling'],
+    ['HTTP 404 is not a citation', 'no # at all'],
+    ['array##4045 is not a citation', 'a doubled # is excluded by the lookbehind'],
+  ])('leaves %j alone (%s)', (text) => {
+    expect(stripInternalIssueIds(text)).toBe(text);
+  });
+});
+
 describe('the generator wires the guards in', () => {
   const source = (): string => fs.readFileSync(GENERATOR, 'utf-8');
 
@@ -204,4 +236,9 @@ describe('the generator wires the guards in', () => {
     expect(source()).toContain('checkTransitiveAllowlist(SKILL_MAP, TRANSITIVE_ALLOWLIST, closures)');
     expect(source()).toContain('allowed.includes(f)');
   });
+
+  it('strips internal ids on the description path, not somewhere unreachable', () => {
+    expect(source()).toContain('stripInternalIssueIds(clean.split');
+    expect(source()).toContain('stripInternalIssueIds(exportListDescription(content)');
+  });
 });

skills/objectstack-automation/references/_index.md

@@ -13,7 +13,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/automation/builtin-node-config.zod.ts` — Config contracts for the remaining flat builtins — the CRUD quartet
 - `node_modules/@objectstack/spec/src/automation/execution.zod.ts` — Automation Execution Protocol
 - `node_modules/@objectstack/spec/src/automation/flow.zod.ts` — Exports: FlowNodeAction, FlowVariableSchema, FlowNodeSchema, FlowEdgeSchema, FlowSchema
-- `node_modules/@objectstack/spec/src/automation/io-node-config.zod.ts` — Config contracts for the flat IO builtins — `notify` and `http` (#4045).
+- `node_modules/@objectstack/spec/src/automation/io-node-config.zod.ts` — Config contracts for the flat IO builtins — `notify` and `http`.
 - `node_modules/@objectstack/spec/src/automation/node-executor.zod.ts` — Node Executor Plugin Protocol — Wait Node Pause/Resume
 - `node_modules/@objectstack/spec/src/automation/time-relative-trigger.zod.ts` — Time-Relative Trigger Protocol
 - `node_modules/@objectstack/spec/src/automation/webhook.zod.ts` — Exports: WebhookTriggerType, WebhookSchema