fix: harden install planning and sync tracked catalogs

2026-04-01 22:53:27 +08:00 · 2026-03-31 22:57:48 -07:00
parent 03c4a90ffa
commit e1bc08fa6e
19 changed files with 970 additions and 118 deletions
--- a/scripts/ci/catalog.js
+++ b/scripts/ci/catalog.js
@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 /**
- * Verify repo catalog counts against README.md and AGENTS.md.
+ * Verify repo catalog counts against tracked documentation files.
 *
 * Usage:
 *   node scripts/ci/catalog.js
 *   node scripts/ci/catalog.js --json
 *   node scripts/ci/catalog.js --md
 *   node scripts/ci/catalog.js --text
+ *   node scripts/ci/catalog.js --write --text
 */

 'use strict';
@@ -17,6 +18,10 @@ const path = require('path');
 const ROOT = path.join(__dirname, '../..');
 const README_PATH = path.join(ROOT, 'README.md');
 const AGENTS_PATH = path.join(ROOT, 'AGENTS.md');
+const README_ZH_CN_PATH = path.join(ROOT, 'README.zh-CN.md');
+const DOCS_ZH_CN_README_PATH = path.join(ROOT, 'docs', 'zh-CN', 'README.md');
+const DOCS_ZH_CN_AGENTS_PATH = path.join(ROOT, 'docs', 'zh-CN', 'AGENTS.md');
+const WRITE_MODE = process.argv.includes('--write');

 const OUTPUT_MODE = process.argv.includes('--md')
  ? 'md'
@@ -43,8 +48,9 @@ function listMatchingFiles(relativeDir, matcher) {
 function buildCatalog() {
  const agents = listMatchingFiles('agents', entry => entry.isFile() && entry.name.endsWith('.md'));
  const commands = listMatchingFiles('commands', entry => entry.isFile() && entry.name.endsWith('.md'));
-  const skills = listMatchingFiles('skills', entry => entry.isDirectory() && fs.existsSync(path.join(ROOT, 'skills', entry.name, 'SKILL.md')))
-    .map(skillDir => `${skillDir}/SKILL.md`);
+  const skills = listMatchingFiles('skills', entry => (
+    entry.isDirectory() && fs.existsSync(path.join(ROOT, 'skills', entry.name, 'SKILL.md'))
+  )).map(skillDir => `${skillDir}/SKILL.md`);

  return {
    agents: { count: agents.length, files: agents, glob: 'agents/*.md' },
@@ -61,6 +67,22 @@ function readFileOrThrow(filePath) {
  }
 }

+function writeFileOrThrow(filePath, content) {
+  try {
+    fs.writeFileSync(filePath, content, 'utf8');
+  } catch (error) {
+    throw new Error(`Failed to write ${path.basename(filePath)}: ${error.message}`);
+  }
+}
+
+function replaceOrThrow(content, regex, replacer, source) {
+  if (!regex.test(content)) {
+    throw new Error(`${source} is missing the expected catalog marker`);
+  }
+
+  return content.replace(regex, replacer);
+}
+
 function parseReadmeExpectations(readmeContent) {
  const expectations = [];

@@ -95,6 +117,120 @@ function parseReadmeExpectations(readmeContent) {
    });
  }

+  const parityPatterns = [
+    {
+      category: 'agents',
+      regex: /^\|\s*(?:\*\*)?Agents(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*Shared\s*\(AGENTS\.md\)\s*\|\s*Shared\s*\(AGENTS\.md\)\s*\|\s*12\s*\|$/im,
+      source: 'README.md parity table'
+    },
+    {
+      category: 'commands',
+      regex: /^\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*Shared\s*\|\s*Instruction-based\s*\|\s*31\s*\|$/im,
+      source: 'README.md parity table'
+    },
+    {
+      category: 'skills',
+      regex: /^\|\s*(?:\*\*)?Skills(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*Shared\s*\|\s*10\s*\(native format\)\s*\|\s*37\s*\|$/im,
+      source: 'README.md parity table'
+    }
+  ];
+
+  for (const pattern of parityPatterns) {
+    const match = readmeContent.match(pattern.regex);
+    if (!match) {
+      throw new Error(`${pattern.source} is missing the ${pattern.category} row`);
+    }
+
+    expectations.push({
+      category: pattern.category,
+      mode: 'exact',
+      expected: Number(match[1]),
+      source: `${pattern.source} (${pattern.category})`
+    });
+  }
+
+  return expectations;
+}
+
+function parseZhRootReadmeExpectations(readmeContent) {
+  const match = readmeContent.match(/你现在可以使用\s+(\d+)\s+个代理、\s*(\d+)\s*个技能和\s*(\d+)\s*个命令/i);
+  if (!match) {
+    throw new Error('README.zh-CN.md is missing the quick-start catalog summary');
+  }
+
+  return [
+    { category: 'agents', mode: 'exact', expected: Number(match[1]), source: 'README.zh-CN.md quick-start summary' },
+    { category: 'skills', mode: 'exact', expected: Number(match[2]), source: 'README.zh-CN.md quick-start summary' },
+    { category: 'commands', mode: 'exact', expected: Number(match[3]), source: 'README.zh-CN.md quick-start summary' }
+  ];
+}
+
+function parseZhDocsReadmeExpectations(readmeContent) {
+  const expectations = [];
+
+  const quickStartMatch = readmeContent.match(/你现在可以使用\s+(\d+)\s+个智能体、\s*(\d+)\s*项技能和\s*(\d+)\s*个命令了/i);
+  if (!quickStartMatch) {
+    throw new Error('docs/zh-CN/README.md is missing the quick-start catalog summary');
+  }
+
+  expectations.push(
+    { category: 'agents', mode: 'exact', expected: Number(quickStartMatch[1]), source: 'docs/zh-CN/README.md quick-start summary' },
+    { category: 'skills', mode: 'exact', expected: Number(quickStartMatch[2]), source: 'docs/zh-CN/README.md quick-start summary' },
+    { category: 'commands', mode: 'exact', expected: Number(quickStartMatch[3]), source: 'docs/zh-CN/README.md quick-start summary' }
+  );
+
+  const tablePatterns = [
+    { category: 'agents', regex: /\|\s*智能体\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s*个\s*\|/i, source: 'docs/zh-CN/README.md comparison table' },
+    { category: 'commands', regex: /\|\s*命令\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s*个\s*\|/i, source: 'docs/zh-CN/README.md comparison table' },
+    { category: 'skills', regex: /\|\s*技能\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s*项\s*\|/i, source: 'docs/zh-CN/README.md comparison table' }
+  ];
+
+  for (const pattern of tablePatterns) {
+    const match = readmeContent.match(pattern.regex);
+    if (!match) {
+      throw new Error(`${pattern.source} is missing the ${pattern.category} row`);
+    }
+
+    expectations.push({
+      category: pattern.category,
+      mode: 'exact',
+      expected: Number(match[1]),
+      source: `${pattern.source} (${pattern.category})`
+    });
+  }
+
+  const parityPatterns = [
+    {
+      category: 'agents',
+      regex: /^\|\s*(?:\*\*)?智能体(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*共享\s*\(AGENTS\.md\)\s*\|\s*共享\s*\(AGENTS\.md\)\s*\|\s*12\s*\|$/im,
+      source: 'docs/zh-CN/README.md parity table'
+    },
+    {
+      category: 'commands',
+      regex: /^\|\s*(?:\*\*)?命令(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*共享\s*\|\s*基于指令\s*\|\s*31\s*\|$/im,
+      source: 'docs/zh-CN/README.md parity table'
+    },
+    {
+      category: 'skills',
+      regex: /^\|\s*(?:\*\*)?技能(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*共享\s*\|\s*10\s*\(原生格式\)\s*\|\s*37\s*\|$/im,
+      source: 'docs/zh-CN/README.md parity table'
+    }
+  ];
+
+  for (const pattern of parityPatterns) {
+    const match = readmeContent.match(pattern.regex);
+    if (!match) {
+      throw new Error(`${pattern.source} is missing the ${pattern.category} row`);
+    }
+
+    expectations.push({
+      category: pattern.category,
+      mode: 'exact',
+      expected: Number(match[1]),
+      source: `${pattern.source} (${pattern.category})`
+    });
+  }
+
  return expectations;
 }

@@ -153,6 +289,61 @@ function parseAgentsDocExpectations(agentsContent) {
  return expectations;
 }

+function parseZhAgentsDocExpectations(agentsContent) {
+  const summaryMatch = agentsContent.match(/提供\s+(\d+)\s+个专业代理、\s*(\d+)(\+)?\s*项技能、\s*(\d+)\s+条命令/i);
+  if (!summaryMatch) {
+    throw new Error('docs/zh-CN/AGENTS.md is missing the catalog summary line');
+  }
+
+  const expectations = [
+    { category: 'agents', mode: 'exact', expected: Number(summaryMatch[1]), source: 'docs/zh-CN/AGENTS.md summary' },
+    {
+      category: 'skills',
+      mode: summaryMatch[3] ? 'minimum' : 'exact',
+      expected: Number(summaryMatch[2]),
+      source: 'docs/zh-CN/AGENTS.md summary'
+    },
+    { category: 'commands', mode: 'exact', expected: Number(summaryMatch[4]), source: 'docs/zh-CN/AGENTS.md summary' }
+  ];
+
+  const structurePatterns = [
+    {
+      category: 'agents',
+      mode: 'exact',
+      regex: /^\s*agents\/\s*[—–-]\s*(\d+)\s+个专业子代理\s*$/im,
+      source: 'docs/zh-CN/AGENTS.md project structure'
+    },
+    {
+      category: 'skills',
+      mode: 'minimum',
+      regex: /^\s*skills\/\s*[—–-]\s*(\d+)(\+)?\s+个工作流技能和领域知识\s*$/im,
+      source: 'docs/zh-CN/AGENTS.md project structure'
+    },
+    {
+      category: 'commands',
+      mode: 'exact',
+      regex: /^\s*commands\/\s*[—–-]\s*(\d+)\s+个斜杠命令\s*$/im,
+      source: 'docs/zh-CN/AGENTS.md project structure'
+    }
+  ];
+
+  for (const pattern of structurePatterns) {
+    const match = agentsContent.match(pattern.regex);
+    if (!match) {
+      throw new Error(`${pattern.source} is missing the ${pattern.category} entry`);
+    }
+
+    expectations.push({
+      category: pattern.category,
+      mode: pattern.mode === 'minimum' && match[2] ? 'minimum' : pattern.mode,
+      expected: Number(match[1]),
+      source: `${pattern.source} (${pattern.category})`
+    });
+  }
+
+  return expectations;
+}
+
 function evaluateExpectations(catalog, expectations) {
  return expectations.map(expectation => {
    const actual = catalog[expectation.category].count;
@@ -173,6 +364,208 @@ function formatExpectation(expectation) {
  return `${expectation.source}: ${expectation.category} documented ${comparator} ${expectation.expected}, actual ${expectation.actual}`;
 }

+function syncEnglishReadme(content, catalog) {
+  let nextContent = content;
+
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(access to\s+)(\d+)(\s+agents,\s+)(\d+)(\s+skills,\s+and\s+)(\d+)(\s+commands)/i,
+    (_, prefix, __, agentsSuffix, ___, skillsSuffix, ____, commandsSuffix) =>
+      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsSuffix}${catalog.commands.count}${commandsSuffix}`,
+    'README.md quick-start summary'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(\|\s*(?:\*\*)?Agents(?:\*\*)?\s*\|\s*(?:(?:PASS:|\u2705)\s*)?)(\d+)(\s+agents\s*\|)/i,
+    (_, prefix, __, suffix) => `${prefix}${catalog.agents.count}${suffix}`,
+    'README.md comparison table (agents)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*(?:(?:PASS:|\u2705)\s*)?)(\d+)(\s+commands\s*\|)/i,
+    (_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,
+    'README.md comparison table (commands)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(\|\s*(?:\*\*)?Skills(?:\*\*)?\s*\|\s*(?:(?:PASS:|\u2705)\s*)?)(\d+)(\s+skills\s*\|)/i,
+    (_, prefix, __, suffix) => `${prefix}${catalog.skills.count}${suffix}`,
+    'README.md comparison table (skills)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\|\s*(?:\*\*)?Agents(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*Shared\s*\(AGENTS\.md\)\s*\|\s*Shared\s*\(AGENTS\.md\)\s*\|\s*12\s*\|)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.agents.count}${suffix}`,
+    'README.md parity table (agents)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*Shared\s*\|\s*Instruction-based\s*\|\s*31\s*\|)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,
+    'README.md parity table (commands)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\|\s*(?:\*\*)?Skills(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*Shared\s*\|\s*10\s*\(native format\)\s*\|\s*37\s*\|)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.skills.count}${suffix}`,
+    'README.md parity table (skills)'
+  );
+
+  return nextContent;
+}
+
+function syncEnglishAgents(content, catalog) {
+  let nextContent = content;
+
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(providing\s+)(\d+)(\s+specialized agents,\s+)(\d+)(\+?)(\s+skills,\s+)(\d+)(\s+commands)/i,
+    (_, prefix, __, agentsSuffix, ___, skillsPlus, skillsSuffix, ____, commandsSuffix) =>
+      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsPlus}${skillsSuffix}${catalog.commands.count}${commandsSuffix}`,
+    'AGENTS.md summary'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\s*agents\/\s*[—–-]\s*)(\d+)(\s+specialized subagents\s*)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.agents.count}${suffix}`,
+    'AGENTS.md project structure (agents)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\s*skills\/\s*[—–-]\s*)(\d+)(\+?)(\s+workflow skills and domain knowledge\s*)$/im,
+    (_, prefix, __, plus, suffix) => `${prefix}${catalog.skills.count}${plus}${suffix}`,
+    'AGENTS.md project structure (skills)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\s*commands\/\s*[—–-]\s*)(\d+)(\s+slash commands\s*)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,
+    'AGENTS.md project structure (commands)'
+  );
+
+  return nextContent;
+}
+
+function syncZhRootReadme(content, catalog) {
+  return replaceOrThrow(
+    content,
+    /(你现在可以使用\s+)(\d+)(\s+个代理、\s*)(\d+)(\s*个技能和\s*)(\d+)(\s*个命令[。.!！]?)/i,
+    (_, prefix, __, agentsSuffix, ___, skillsSuffix, ____, commandsSuffix) =>
+      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsSuffix}${catalog.commands.count}${commandsSuffix}`,
+    'README.zh-CN.md quick-start summary'
+  );
+}
+
+function syncZhDocsReadme(content, catalog) {
+  let nextContent = content;
+
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(你现在可以使用\s+)(\d+)(\s+个智能体、\s*)(\d+)(\s*项技能和\s*)(\d+)(\s*个命令了[。.!！]?)/i,
+    (_, prefix, __, agentsSuffix, ___, skillsSuffix, ____, commandsSuffix) =>
+      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsSuffix}${catalog.commands.count}${commandsSuffix}`,
+    'docs/zh-CN/README.md quick-start summary'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(\|\s*智能体\s*\|\s*(?:(?:PASS:|\u2705)\s*)?)(\d+)(\s*个\s*\|)/i,
+    (_, prefix, __, suffix) => `${prefix}${catalog.agents.count}${suffix}`,
+    'docs/zh-CN/README.md comparison table (agents)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(\|\s*命令\s*\|\s*(?:(?:PASS:|\u2705)\s*)?)(\d+)(\s*个\s*\|)/i,
+    (_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,
+    'docs/zh-CN/README.md comparison table (commands)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(\|\s*技能\s*\|\s*(?:(?:PASS:|\u2705)\s*)?)(\d+)(\s*项\s*\|)/i,
+    (_, prefix, __, suffix) => `${prefix}${catalog.skills.count}${suffix}`,
+    'docs/zh-CN/README.md comparison table (skills)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\|\s*(?:\*\*)?智能体(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*共享\s*\(AGENTS\.md\)\s*\|\s*共享\s*\(AGENTS\.md\)\s*\|\s*12\s*\|)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.agents.count}${suffix}`,
+    'docs/zh-CN/README.md parity table (agents)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\|\s*(?:\*\*)?命令(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*共享\s*\|\s*基于指令\s*\|\s*31\s*\|)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,
+    'docs/zh-CN/README.md parity table (commands)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\|\s*(?:\*\*)?技能(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*共享\s*\|\s*10\s*\(原生格式\)\s*\|\s*37\s*\|)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.skills.count}${suffix}`,
+    'docs/zh-CN/README.md parity table (skills)'
+  );
+
+  return nextContent;
+}
+
+function syncZhAgents(content, catalog) {
+  let nextContent = content;
+
+  nextContent = replaceOrThrow(
+    nextContent,
+    /(提供\s+)(\d+)(\s+个专业代理、\s*)(\d+)(\+?)(\s*项技能、\s*)(\d+)(\s+条命令)/i,
+    (_, prefix, __, agentsSuffix, ___, skillsPlus, skillsSuffix, ____, commandsSuffix) =>
+      `${prefix}${catalog.agents.count}${agentsSuffix}${catalog.skills.count}${skillsPlus}${skillsSuffix}${catalog.commands.count}${commandsSuffix}`,
+    'docs/zh-CN/AGENTS.md summary'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\s*agents\/\s*[—–-]\s*)(\d+)(\s+个专业子代理\s*)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.agents.count}${suffix}`,
+    'docs/zh-CN/AGENTS.md project structure (agents)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\s*skills\/\s*[—–-]\s*)(\d+)(\+?)(\s+个工作流技能和领域知识\s*)$/im,
+    (_, prefix, __, plus, suffix) => `${prefix}${catalog.skills.count}${plus}${suffix}`,
+    'docs/zh-CN/AGENTS.md project structure (skills)'
+  );
+  nextContent = replaceOrThrow(
+    nextContent,
+    /^(\s*commands\/\s*[—–-]\s*)(\d+)(\s+个斜杠命令\s*)$/im,
+    (_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,
+    'docs/zh-CN/AGENTS.md project structure (commands)'
+  );
+
+  return nextContent;
+}
+
+const DOCUMENT_SPECS = [
+  {
+    filePath: README_PATH,
+    parseExpectations: parseReadmeExpectations,
+    syncContent: syncEnglishReadme,
+  },
+  {
+    filePath: AGENTS_PATH,
+    parseExpectations: parseAgentsDocExpectations,
+    syncContent: syncEnglishAgents,
+  },
+  {
+    filePath: README_ZH_CN_PATH,
+    parseExpectations: parseZhRootReadmeExpectations,
+    syncContent: syncZhRootReadme,
+  },
+  {
+    filePath: DOCS_ZH_CN_README_PATH,
+    parseExpectations: parseZhDocsReadmeExpectations,
+    syncContent: syncZhDocsReadme,
+  },
+  {
+    filePath: DOCS_ZH_CN_AGENTS_PATH,
+    parseExpectations: parseZhAgentsDocExpectations,
+    syncContent: syncZhAgents,
+  },
+];
+
 function renderText(result) {
  console.log('Catalog counts:');
  console.log(`- agents: ${result.catalog.agents.count}`);
@@ -215,12 +608,20 @@ function renderMarkdown(result) {

 function main() {
  const catalog = buildCatalog();
-  const readmeContent = readFileOrThrow(README_PATH);
-  const agentsContent = readFileOrThrow(AGENTS_PATH);
-  const expectations = [
-    ...parseReadmeExpectations(readmeContent),
-    ...parseAgentsDocExpectations(agentsContent)
-  ];
+
+  if (WRITE_MODE) {
+    for (const spec of DOCUMENT_SPECS) {
+      const currentContent = readFileOrThrow(spec.filePath);
+      const nextContent = spec.syncContent(currentContent, catalog);
+      if (nextContent !== currentContent) {
+        writeFileOrThrow(spec.filePath, nextContent);
+      }
+    }
+  }
+
+  const expectations = DOCUMENT_SPECS.flatMap(spec => (
+    spec.parseExpectations(readFileOrThrow(spec.filePath))
+  ));
  const checks = evaluateExpectations(catalog, expectations);
  const result = { catalog, checks };

--- a/scripts/gan-harness.sh
+++ b/scripts/gan-harness.sh
@@ -54,7 +54,7 @@ NC='\033[0m'

 log()    { echo -e "${BLUE}[GAN-HARNESS]${NC} $*"; }
 ok()     { echo -e "${GREEN}[✓]${NC} $*"; }
-warn()   { echo -e "${YELLOW}[⚠]${NC} $*"; }
+warn()   { echo -e "${YELLOW}[WARN]${NC} $*"; }
 fail()   { echo -e "${RED}[✗]${NC} $*"; }
 phase()  { echo -e "\n${PURPLE}═══════════════════════════════════════════════${NC}"; echo -e "${PURPLE}  $*${NC}"; echo -e "${PURPLE}═══════════════════════════════════════════════${NC}\n"; }

@@ -159,7 +159,7 @@ for (( i=1; i<=MAX_ITERATIONS; i++ )); do
  log "━━━ Iteration $i / $MAX_ITERATIONS ━━━"

  # ── GENERATE ──
-  echo -e "${GREEN}▶ GENERATOR (iteration $i)${NC}"
+  echo -e "${GREEN}>> GENERATOR (iteration $i)${NC}"

  FEEDBACK_CONTEXT=""
  if [ $i -gt 1 ] && [ -f "${FEEDBACK_DIR}/feedback-$(printf '%03d' $((i-1))).md" ]; then
@@ -181,7 +181,7 @@ Update gan-harness/generator-state.md." \
  ok "Generator completed iteration $i"

  # ── EVALUATE ──
-  echo -e "${RED}▶ EVALUATOR (iteration $i)${NC}"
+  echo -e "${RED}>> EVALUATOR (iteration $i)${NC}"

  claude -p --model "$EVALUATOR_MODEL" \
    --allowedTools "Read,Write,Bash,Grep,Glob" \
@@ -217,7 +217,7 @@ Include the weighted TOTAL score in the format: | **TOTAL** | | | **X.X** |" \
  # ── CHECK PASS ──
  if score_passes "$SCORE" "$PASS_THRESHOLD"; then
    echo ""
-    ok "🎉 PASSED at iteration $i with score $SCORE (threshold: $PASS_THRESHOLD)"
+    ok "PASSED at iteration $i with score $SCORE (threshold: $PASS_THRESHOLD)"
    break
  fi

@@ -256,7 +256,7 @@ cat > "${HARNESS_DIR}/build-report.md" << EOF
 # GAN Harness Build Report

 **Brief:** $BRIEF
-**Result:** $(score_passes "$FINAL_SCORE" "$PASS_THRESHOLD" && echo "✅ PASS" || echo "❌ FAIL")
+**Result:** $(score_passes "$FINAL_SCORE" "$PASS_THRESHOLD" && echo "PASS" || echo "FAIL")
 **Iterations:** $NUM_ITERATIONS / $MAX_ITERATIONS
 **Final Score:** $FINAL_SCORE / 10.0 (threshold: $PASS_THRESHOLD)
 **Elapsed:** $ELAPSED
@@ -287,9 +287,9 @@ ok "Report written to ${HARNESS_DIR}/build-report.md"
 echo ""
 log "━━━ Final Results ━━━"
 if score_passes "$FINAL_SCORE" "$PASS_THRESHOLD"; then
-  echo -e "${GREEN}  Result:     PASS ✅${NC}"
+  echo -e "${GREEN}  Result:     PASS${NC}"
 else
-  echo -e "${RED}  Result:     FAIL ❌${NC}"
+  echo -e "${RED}  Result:     FAIL${NC}"
 fi
 echo -e "  Score:      ${CYAN}${FINAL_SCORE}${NC} / 10.0"
 echo -e "  Iterations: ${NUM_ITERATIONS} / ${MAX_ITERATIONS}"
--- a/scripts/lib/install-manifests.js
+++ b/scripts/lib/install-manifests.js
@@ -1,7 +1,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { planInstallTargetScaffold } = require('./install-targets/registry');
+const { getInstallTargetAdapter, planInstallTargetScaffold } = require('./install-targets/registry');

 const DEFAULT_REPO_ROOT = path.join(__dirname, '../..');
 const SUPPORTED_INSTALL_TARGETS = ['claude', 'cursor', 'antigravity', 'codex', 'gemini', 'opencode', 'codebuddy'];
@@ -76,6 +76,48 @@ function dedupeStrings(values) {
  return [...new Set((Array.isArray(values) ? values : []).map(value => String(value).trim()).filter(Boolean))];
 }

+function readOptionalStringOption(options, key) {
+  if (
+    !Object.prototype.hasOwnProperty.call(options, key)
+    || options[key] === null
+    || options[key] === undefined
+  ) {
+    return null;
+  }
+
+  if (typeof options[key] !== 'string' || options[key].trim() === '') {
+    throw new Error(`${key} must be a non-empty string when provided`);
+  }
+
+  return options[key];
+}
+
+function readModuleTargetsOrThrow(module) {
+  const moduleId = module && module.id ? module.id : '<unknown>';
+  const targets = module && module.targets;
+
+  if (!Array.isArray(targets)) {
+    throw new Error(`Install module ${moduleId} has invalid targets; expected an array of supported target ids`);
+  }
+
+  const normalizedTargets = targets.map(target => (
+    typeof target === 'string' ? target.trim() : ''
+  ));
+
+  if (normalizedTargets.some(target => target.length === 0)) {
+    throw new Error(`Install module ${moduleId} has invalid targets; expected an array of supported target ids`);
+  }
+
+  const unsupportedTargets = normalizedTargets.filter(target => !SUPPORTED_INSTALL_TARGETS.includes(target));
+  if (unsupportedTargets.length > 0) {
+    throw new Error(
+      `Install module ${moduleId} has unsupported targets: ${unsupportedTargets.join(', ')}`
+    );
+  }
+
+  return normalizedTargets;
+}
+
 function assertKnownModuleIds(moduleIds, manifests) {
  const unknownModuleIds = dedupeStrings(moduleIds)
    .filter(moduleId => !manifests.modulesById.has(moduleId));
@@ -125,6 +167,11 @@ function loadInstallManifests(options = {}) {
    ? profilesData.profiles
    : {};
  const components = Array.isArray(componentsData.components) ? componentsData.components : [];
+
+  for (const module of modules) {
+    readModuleTargetsOrThrow(module);
+  }
+
  const modulesById = new Map(modules.map(module => [module.id, module]));
  const componentsById = new Map(components.map(component => [component.id, component]));

@@ -361,6 +408,16 @@ function resolveInstallPlan(options = {}) {
      `Unknown install target: ${target}. Expected one of ${SUPPORTED_INSTALL_TARGETS.join(', ')}`
    );
  }
+  const validatedProjectRoot = readOptionalStringOption(options, 'projectRoot');
+  const validatedHomeDir = readOptionalStringOption(options, 'homeDir');
+  const targetPlanningInput = target
+    ? {
+      repoRoot: manifests.repoRoot,
+      projectRoot: validatedProjectRoot || manifests.repoRoot,
+      homeDir: validatedHomeDir || os.homedir(),
+    }
+    : null;
+  const targetAdapter = target ? getInstallTargetAdapter(target) : null;

  const effectiveRequestedIds = dedupeStrings(
    requestedModuleIds.filter(moduleId => !excludedModuleOwners.has(moduleId))
@@ -396,7 +453,13 @@ function resolveInstallPlan(options = {}) {
      return;
    }

-    if (target && !module.targets.includes(target)) {
+    const supportsTarget = !target
+      || (
+        readModuleTargetsOrThrow(module).includes(target)
+        && (!targetAdapter || targetAdapter.supportsModule(module, targetPlanningInput))
+      );
+
+    if (!supportsTarget) {
      if (dependencyOf) {
        skippedTargetIds.add(rootRequesterId || dependencyOf);
        return false;
@@ -444,9 +507,9 @@ function resolveInstallPlan(options = {}) {
  const scaffoldPlan = target
    ? planInstallTargetScaffold({
      target,
-      repoRoot: manifests.repoRoot,
-      projectRoot: options.projectRoot || manifests.repoRoot,
-      homeDir: options.homeDir || os.homedir(),
+      repoRoot: targetPlanningInput.repoRoot,
+      projectRoot: targetPlanningInput.projectRoot,
+      homeDir: targetPlanningInput.homeDir,
      modules: selectedModules,
    })
    : null;
--- a/scripts/lib/install-targets/antigravity-project.js
+++ b/scripts/lib/install-targets/antigravity-project.js
@@ -4,14 +4,28 @@ const {
  createFlatRuleOperations,
  createInstallTargetAdapter,
  createManagedScaffoldOperation,
+  normalizeRelativePath,
 } = require('./helpers');

+const SUPPORTED_SOURCE_PREFIXES = ['rules', 'commands', 'agents', 'skills', '.agents', 'AGENTS.md'];
+
+function supportsAntigravitySourcePath(sourceRelativePath) {
+  const normalizedPath = normalizeRelativePath(sourceRelativePath);
+  return SUPPORTED_SOURCE_PREFIXES.some(prefix => (
+    normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`)
+  ));
+}
+
 module.exports = createInstallTargetAdapter({
  id: 'antigravity-project',
  target: 'antigravity',
  kind: 'project',
  rootSegments: ['.agent'],
  installStatePathSegments: ['ecc-install-state.json'],
+  supportsModule(module) {
+    const paths = Array.isArray(module && module.paths) ? module.paths : [];
+    return paths.length > 0;
+  },
  planOperations(input, adapter) {
    const modules = Array.isArray(input.modules)
      ? input.modules
@@ -30,7 +44,9 @@ module.exports = createInstallTargetAdapter({

    return modules.flatMap(module => {
      const paths = Array.isArray(module.paths) ? module.paths : [];
-      return paths.flatMap(sourceRelativePath => {
+      return paths
+        .filter(supportsAntigravitySourcePath)
+        .flatMap(sourceRelativePath => {
        if (sourceRelativePath === 'rules') {
          return createFlatRuleOperations({
            moduleId: module.id,
@@ -62,8 +78,8 @@ module.exports = createInstallTargetAdapter({
          ];
        }

-        return [adapter.createScaffoldOperation(module.id, sourceRelativePath, planningInput)];
-      });
+          return [adapter.createScaffoldOperation(module.id, sourceRelativePath, planningInput)];
+        });
    });
  },
 });
--- a/scripts/lib/install-targets/helpers.js
+++ b/scripts/lib/install-targets/helpers.js
@@ -276,6 +276,13 @@ function createInstallTargetAdapter(config) {
        input
      ));
    },
+    supportsModule(module, input = {}) {
+      if (typeof config.supportsModule === 'function') {
+        return config.supportsModule(module, input, adapter);
+      }
+
+      return true;
+    },
    validate(input = {}) {
      if (typeof config.validate === 'function') {
        return config.validate(input, adapter);