refactor(core): move review skill incident narratives to DESIGN.md

packages/core/src/skills/bundled/review/SKILL.test.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2026 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const skillDir = path.dirname(fileURLToPath(import.meta.url));
+
+// Titles may end in one parenthesized qualifier, e.g. "The two-dot phantom
+// regressions (PR #6626)", so the match allows a single nested group.
+const POINTER_RE = /\(measured; DESIGN\.md — ([^()\n]+(?:\([^()\n]*\))?)\)/g;
+const POINTER_OPEN = '(measured; DESIGN.md — ';
+
+function skillBody(): string {
+  return fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+}
+
+function incidentPointers(body: string): string[] {
+  return [...body.matchAll(POINTER_RE)].map(([, title]) => title.trim());
+}
+
+function incidentHeadings(): string[] {
+  const design = fs.readFileSync(path.join(skillDir, 'DESIGN.md'), 'utf8');
+  const start = design.indexOf('## Measured incidents');
+  const end = design.indexOf('\n## ', start + 1);
+  const section = end === -1 ? design.slice(start) : design.slice(start, end);
+  return [...section.matchAll(/^### (.+)$/gm)].map(([, title]) => title.trim());
+}
+
+describe('bundled review skill', () => {
+  it('anchors every SKILL.md incident pointer at a DESIGN.md heading', () => {
+    const body = skillBody();
+    const pointers = incidentPointers(body);
+    expect(pointers.length).toBeGreaterThan(0);
+
+    // A pointer the regex cannot parse must fail loudly, not drop silently:
+    // every literal opener owes exactly one match.
+    let opens = 0;
+    for (
+      let i = body.indexOf(POINTER_OPEN);
+      i !== -1;
+      i = body.indexOf(POINTER_OPEN, i + POINTER_OPEN.length)
+    ) {
+      opens++;
+    }
+    expect(pointers).toHaveLength(opens);
+
+    const headings = new Set(incidentHeadings());
+    for (const title of pointers) {
+      expect(
+        headings.has(title),
+        `SKILL.md points at a missing DESIGN.md heading: "### ${title}"`,
+      ).toBe(true);
+    }
+  });
+
+  it('leaves no DESIGN.md incident heading without a SKILL.md pointer', () => {
+    const referenced = new Set(incidentPointers(skillBody()));
+    for (const title of incidentHeadings()) {
+      expect(
+        referenced.has(title),
+        `DESIGN.md incident heading has no SKILL.md pointer: "### ${title}"`,
+      ).toBe(true);
+    }
+  });
+
+  it('keeps the runtime guard against reading DESIGN.md mid-review', () => {
+    expect(skillBody()).toContain(
+      'Never `read_file` DESIGN.md during a review.',
+    );
+  });
+
+  it('pins the setup-batch ordering constraints', () => {
+    const body = skillBody();
+    expect(body).toContain('`fetch-pr` before all of them');
+    expect(body).toContain('`agent-prompt --roster` after the rules load');
+  });
+});

scripts/copy_bundle_assets.js

@@ -70,7 +70,11 @@ export function copyBundleAssets({ root = defaultRoot } = {}) {
     const destBundledDir = join(distDir, 'bundled');
     fs.rmSync(destBundledDir, { recursive: true, force: true });
     copyRecursiveSync(bundledSkillsDir, destBundledDir, {
-      skipEntry: isBundledSkillTestFile,
+      // DESIGN.md files are maintainer design narratives, not runtime inputs;
+      // shipping one would hand a review a ~125 KB read_file target that
+      // outweighs the context the slimmed skill saves.
+      skipEntry: (entry) =>
+        isBundledSkillTestFile(entry) || entry === 'DESIGN.md',
     });
     console.log('Copied bundled skills to dist/bundled/');
   } else {

scripts/copy_files.js

@@ -22,12 +22,20 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-
-const sourceDir = path.join('src');
-const targetDir = path.join('dist', 'src');
+import { fileURLToPath } from 'node:url';
 
 const extensionsToCopy = ['.md', '.json', '.sb'];
 
+function isBundledSkillDesignDoc(normalizedPath) {
+  // DESIGN.md files are maintainer design narratives, not runtime inputs
+  // (see copy_bundle_assets.js); the transpiled build loads bundled skills
+  // from dist/src/, so they must stay out of it too.
+  return (
+    normalizedPath.startsWith('skills/bundled/') &&
+    path.basename(normalizedPath) === 'DESIGN.md'
+  );
+}
+
 function copyFilesRecursive(source, target, rootSourceDir) {
   if (!fs.existsSync(target)) {
     fs.mkdirSync(target, { recursive: true });
@@ -49,38 +57,56 @@ function copyFilesRecursive(source, target, rootSourceDir) {
       const normalizedPath = relativePath.replace(/\\/g, '/');
       const isLocaleJs =
         ext === '.js' && normalizedPath.startsWith('i18n/locales/');
-      if (extensionsToCopy.includes(ext) || isLocaleJs) {
+      if (
+        (extensionsToCopy.includes(ext) || isLocaleJs) &&
+        !isBundledSkillDesignDoc(normalizedPath)
+      ) {
         fs.copyFileSync(sourcePath, targetPath);
       }
     }
   }
 }
 
-if (!fs.existsSync(sourceDir)) {
-  console.error(`Source directory ${sourceDir} not found.`);
-  process.exit(1);
-}
+export function copyFiles({ root = process.cwd() } = {}) {
+  const sourceDir = path.join(root, 'src');
+  const targetDir = path.join(root, 'dist', 'src');
 
-copyFilesRecursive(sourceDir, targetDir, sourceDir);
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`Source directory ${sourceDir} not found.`);
+    process.exit(1);
+  }
 
-// Copy example extensions into the bundle.
-const packageName = path.basename(process.cwd());
-if (packageName === 'cli') {
-  const examplesSource = path.join(
-    sourceDir,
-    'commands',
-    'extensions',
-    'examples',
-  );
-  const examplesTarget = path.join(
-    targetDir,
-    'commands',
-    'extensions',
-    'examples',
-  );
-  if (fs.existsSync(examplesSource)) {
-    fs.cpSync(examplesSource, examplesTarget, { recursive: true });
+  copyFilesRecursive(sourceDir, targetDir, sourceDir);
+
+  // Copy example extensions into the bundle.
+  const packageName = path.basename(root);
+  if (packageName === 'cli') {
+    const examplesSource = path.join(
+      sourceDir,
+      'commands',
+      'extensions',
+      'examples',
+    );
+    const examplesTarget = path.join(
+      targetDir,
+      'commands',
+      'extensions',
+      'examples',
+    );
+    if (fs.existsSync(examplesSource)) {
+      fs.cpSync(examplesSource, examplesTarget, { recursive: true });
+    }
   }
+
+  console.log('Successfully copied files.');
 }
 
-console.log('Successfully copied files.');
+if (isDirectRun()) {
+  copyFiles();
+}
+
+function isDirectRun() {
+  return process.argv[1]
+    ? fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
+    : false;
+}

scripts/tests/package-assets.test.js

@@ -18,6 +18,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { copyBundleAssets } from '../copy_bundle_assets.js';
+import { copyFiles } from '../copy_files.js';
 import { preparePackage } from '../prepare-package.js';
 
 describe('package asset scripts', () => {
@@ -102,6 +103,11 @@ describe('package asset scripts', () => {
       'packages/core/src/skills/bundled/dataviz/references/palette.md',
       '# Palette\n',
     );
+    writeFile(
+      rootDir,
+      'packages/core/src/skills/bundled/dataviz/DESIGN.md',
+      '# Design notes\n',
+    );
     writeFile(rootDir, 'dist/bundled/dataviz/scripts/stale.test.js', 'stale\n');
     stubConsole();
 
@@ -203,6 +209,38 @@ describe('package asset scripts', () => {
         ),
       ),
     ).toBe(true);
+    expect(
+      existsSync(path.join(rootDir, 'dist', 'bundled', 'dataviz', 'DESIGN.md')),
+    ).toBe(false);
+  });
+
+  it('keeps bundled-skill DESIGN.md out of the per-package dist/src copy', () => {
+    const rootDir = createFixtureRoot();
+    writeFile(
+      rootDir,
+      'packages/core/src/skills/bundled/review/SKILL.md',
+      '---\nname: review\ndescription: Review changes\n---\nBody\n',
+    );
+    writeFile(
+      rootDir,
+      'packages/core/src/skills/bundled/review/DESIGN.md',
+      '# Design notes\n',
+    );
+    writeFile(rootDir, 'packages/core/src/notes/DESIGN.md', '# Keep\n');
+    stubConsole();
+
+    copyFiles({ root: path.join(rootDir, 'packages', 'core') });
+
+    const distSrc = path.join(rootDir, 'packages', 'core', 'dist', 'src');
+    expect(
+      existsSync(path.join(distSrc, 'skills', 'bundled', 'review', 'SKILL.md')),
+    ).toBe(true);
+    expect(
+      existsSync(
+        path.join(distSrc, 'skills', 'bundled', 'review', 'DESIGN.md'),
+      ),
+    ).toBe(false);
+    expect(existsSync(path.join(distSrc, 'notes', 'DESIGN.md'))).toBe(true);
   });
 
   it('includes extension examples in the prepared dist package', () => {