test: pin the ship→document-release Step 18 wiring with a free tripwire

Five substring/structure asserts across the carved section, the Claude
skeleton's three touchpoints, the manifest trigger, and the codex/factory
goldens (inlined Step 18 ordered before Step 19). Claude-golden asserts
deliberately omitted: host-config.test.ts already enforces golden ==
generated byte-for-byte.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test/ship-document-release-dispatch.test.ts

@@ -0,0 +1,116 @@
+/**
+ * /ship → /document-release Step 18 dispatch stays wired AND visible.
+ *
+ * The v1.54.0.0 carve (46c1fae7) moved Step 18 (documentation sync) out of
+ * the ship skeleton into sections/pr-body.md. The wiring survived, but on
+ * the Claude host the skeleton stopped saying "document-release" anywhere
+ * in the workflow body — the dispatch became invisible at the decision
+ * points and "the idea of running document-release as part of ship got
+ * lost". This tripwire pins both halves so neither can silently regress:
+ *
+ *  - the carved section keeps the full dispatch contract (imperative,
+ *    subagent_type, JSON return keys, non-blocking failure), and
+ *  - the Claude skeleton names "the /document-release subagent" at its
+ *    three touchpoints (manifest trigger via section-index + STOP pointer,
+ *    Step 17 handoff, hoisted doc-sync invariant) while the imperative
+ *    itself stays carved.
+ *
+ * Structural backstop lives in test/helpers/carve-guards.ts (ship entry);
+ * this named test documents the regression story. Behavioral proof is the
+ * ship-docsync E2E (test/skill-e2e-ship-docsync.test.ts).
+ */
+import { describe, test, expect } from 'bun:test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ROOT = path.join(import.meta.dir, '..');
+
+const SECTION_SITES = [
+  path.join(ROOT, 'ship', 'sections', 'pr-body.md'),
+  path.join(ROOT, 'ship', 'sections', 'pr-body.md.tmpl'),
+];
+
+// ship/SKILL.md only — NOT the claude golden: test/host-config.test.ts
+// already enforces golden == generated byte-for-byte, so substring asserts
+// on the golden would be pure duplication. The codex/factory goldens ARE
+// asserted below because for them the check is content (the inlined
+// section survived generation), which byte-equality alone doesn't prove.
+const CLAUDE_SKELETON = path.join(ROOT, 'ship', 'SKILL.md');
+const INLINED_GOLDENS = [
+  path.join(ROOT, 'test', 'fixtures', 'golden', 'codex-ship-SKILL.md'),
+  path.join(ROOT, 'test', 'fixtures', 'golden', 'factory-ship-SKILL.md'),
+];
+
+const CARVED_IMPERATIVE = 'Dispatch /document-release as a subagent';
+
+describe('/ship Step 18 dispatches /document-release (carve visibility)', () => {
+  test('carved section carries the full dispatch contract', () => {
+    for (const file of SECTION_SITES) {
+      const content = fs.readFileSync(file, 'utf-8');
+      expect(content).toContain(
+        '## Step 18: Documentation sync (via subagent, before PR creation)'
+      );
+      expect(content).toContain(CARVED_IMPERATIVE);
+      expect(content).toContain('subagent_type: "general-purpose"');
+      // The JSON return contract Step 19 bakes into the PR body.
+      expect(content).toContain('"files_updated"');
+      expect(content).toContain('"commit_sha"');
+      expect(content).toContain('"pushed"');
+      expect(content).toContain('"documentation_section"');
+      // Deliberate design: docs sync never holds a ship hostage.
+      expect(content).toContain('Do not block /ship on subagent failure');
+    }
+  });
+
+  test('claude skeleton names the subagent at all three touchpoints', () => {
+    const content = fs.readFileSync(CLAUDE_SKELETON, 'utf-8');
+    // Manifest trigger — renders into the section-index row AND the STOP
+    // pointer, so it must appear at least twice.
+    const trigger =
+      'dispatching the /document-release subagent to sync docs (Step 18) and then creating or updating the PR/MR (Step 19)';
+    expect(content.split(trigger).length - 1).toBeGreaterThanOrEqual(2);
+    // Step 17 handoff.
+    expect(content).toContain(
+      'Step 18 (dispatch the /document-release subagent to sync docs)'
+    );
+    // Hoisted doc-sync invariant (beside the PR-title invariant).
+    expect(content).toContain('**Doc-sync invariant');
+    expect(content).toContain('dispatches the /document-release subagent');
+    // The STOP-Read pointer still routes to the carved section.
+    expect(content).toMatch(
+      /> \*\*STOP\.\*\*[^\n]*Read `[^`]*ship\/sections\/pr-body\.md`/
+    );
+  });
+
+  test('the dispatch imperative stays carved out of the claude skeleton', () => {
+    const content = fs.readFileSync(CLAUDE_SKELETON, 'utf-8');
+    expect(content).not.toContain(CARVED_IMPERATIVE);
+  });
+
+  test('manifest trigger names the subagent', () => {
+    const manifest = JSON.parse(
+      fs.readFileSync(
+        path.join(ROOT, 'ship', 'sections', 'manifest.json'),
+        'utf-8'
+      )
+    );
+    const prBody = manifest.sections.find(
+      (s: { id: string }) => s.id === 'pr-body'
+    );
+    expect(prBody).toBeDefined();
+    expect(prBody.trigger).toContain('the /document-release subagent');
+  });
+
+  test('codex + factory goldens inline Step 18 before Step 19', () => {
+    for (const file of INLINED_GOLDENS) {
+      const content = fs.readFileSync(file, 'utf-8');
+      const step18 = content.indexOf(
+        '## Step 18: Documentation sync (via subagent, before PR creation)'
+      );
+      const step19 = content.indexOf('## Step 19: Create PR/MR');
+      expect(step18).toBeGreaterThan(-1);
+      expect(step19).toBeGreaterThan(step18);
+      expect(content).toContain(CARVED_IMPERATIVE);
+    }
+  });
+});