@keber/qa-framework 1.12.0 → 1.13.1

package/scripts/init.js

@@ -16,7 +16,7 @@ const fs   = require('fs');
 const path = require('path');
 
 const { buildCommandContent, discoverSkillNames, commandFileName } = require('./lib/claude-commands');
-const { AGENT_NAMES, isSprintCycleEnabled, buildAgentContent, agentFileName } = require('./lib/claude-agents');
+const { AGENT_NAMES, isSprintCycleEnabled, renderAllAgents } = require('./lib/claude-agents');
 
 // --- Parse args ---
 const args            = process.argv.slice(2);
@@ -195,13 +195,26 @@ const SPEC_FILES = [
 
 const templateDir = path.resolve(__dirname, '..', 'templates', 'specification');
 
+// Spec folders carry the module-/submodule- prefix; automation folders and TC ids
+// use the bare key. See scripts/lib/module-keys.js for why the two differ.
+const {
+  moduleSpecDirName,
+  submoduleSpecDirName,
+  moduleBareName,
+  submoduleBareName,
+} = require('./lib/module-keys');
+
 for (const mod of modules) {
   const moduleKey = mod.key ?? mod.name.toLowerCase().replace(/\s+/g, '-');
+  const moduleDirName = moduleSpecDirName(moduleKey);
+  const moduleName = moduleBareName(moduleKey);
   const submodules = mod.submodules ?? [];
 
   for (const sub of submodules) {
     const subKey = sub.key ?? sub.name.toLowerCase().replace(/\s+/g, '-');
-    const subDir = path.join(qaRoot, '01-specifications', moduleKey, subKey);
+    const subDirName = submoduleSpecDirName(subKey);
+    const subName = submoduleBareName(subKey);
+    const subDir = path.join(qaRoot, '01-specifications', moduleDirName, subDirName);
     fs.mkdirSync(subDir, { recursive: true });
 
     for (const specFile of SPEC_FILES) {
@@ -213,8 +226,8 @@ for (const mod of modules) {
           content = content
             .replace(/\{\{MODULE_NAME\}\}/g, mod.name)
             .replace(/\{\{SUBMODULE_NAME\}\}/g, sub.name)
-            .replace(/\{\{MODULE\}\}/g, moduleKey.toUpperCase())
-            .replace(/\{\{SUB\}\}/g, subKey.toUpperCase());
+            .replace(/\{\{MODULE\}\}/g, moduleName.toUpperCase())
+            .replace(/\{\{SUB\}\}/g, subName.toUpperCase());
           fs.writeFileSync(dest, content, 'utf8');
         } else {
           fs.writeFileSync(dest, `# ${specFile}\n\n> Auto-generated placeholder\n`, 'utf8');
@@ -226,11 +239,11 @@ for (const mod of modules) {
     }
 
     // Create automation spec stub in e2e/tests/{module}/
-    const e2eDir = path.join(qaRoot, '07-automation', 'e2e', 'tests', moduleKey);
+    const e2eDir = path.join(qaRoot, '07-automation', 'e2e', 'tests', moduleName);
     fs.mkdirSync(e2eDir, { recursive: true });
-    const specTs = path.join(e2eDir, `${subKey}.spec.ts`);
+    const specTs = path.join(e2eDir, `${subName}.spec.ts`);
     if (!fs.existsSync(specTs)) {
-      fs.writeFileSync(specTs, specScaffold(mod.name, sub.name, moduleKey, subKey), 'utf8');
+      fs.writeFileSync(specTs, specScaffold(mod.name, sub.name, moduleName, subName), 'utf8');
       console.log(`  [created] ${path.relative(cwd, specTs)}`);
     }
   }
@@ -347,12 +360,19 @@ writeIfMissing(claudeRulesPath, claudeRulesContent);
 // --- .claude/agents/qa-*.md - optional ANALISIS/PLAN sprint-cycle mode (Claude Code only) ---
 // Gated by integrations.azureDevOps.sprintCycle.enabled. No .github/ equivalent: Claude
 // Code subagents with per-agent tools/model frontmatter have no Copilot counterpart.
+// Each agent is rendered independently: an invalid lane config fails qa-investigador
+// only, the other agents are still written, and init exits 1 at the end.
+const agentFailures = [];
 if (isSprintCycleEnabled(config)) {
   const templatesDir = path.resolve(__dirname, '..', 'templates');
   const claudeAgentsDest = path.join(cwd, '.claude', 'agents');
   fs.mkdirSync(claudeAgentsDest, { recursive: true });
-  for (const agentName of AGENT_NAMES) {
-    writeIfMissing(path.join(claudeAgentsDest, agentFileName(agentName)), buildAgentContent(agentName, templatesDir, config));
+  for (const agent of renderAllAgents(templatesDir, config)) {
+    if (agent.error) {
+      agentFailures.push(agent);
+      continue;
+    }
+    writeIfMissing(path.join(claudeAgentsDest, agent.fileName), agent.content);
   }
 }
 
@@ -414,7 +434,11 @@ console.log('    .github/instructions/  qa-framework.instructions.md');
 console.log('    .claude/commands/      qa-*.md (Claude Code slash commands)');
 console.log('    .claude/rules/         qa-framework.md (Claude Code always-loaded rules)');
 if (isSprintCycleEnabled(config)) {
-  console.log('    .claude/agents/        qa-analisis/qa-plan/qa-asesoria/qa-informe-resultados.md (ANALISIS/PLAN mode)');
+  const failedAgents = new Set(agentFailures.map((a) => a.agentName));
+  const generatedAgents = AGENT_NAMES.filter((name) => !failedAgents.has(name));
+  if (generatedAgents.length) {
+    console.log(`    .claude/agents/        ${generatedAgents.join('/')}.md (ANALISIS/PLAN mode)`);
+  }
 }
 console.log('');
 console.log('  Optional integrations:');
@@ -438,6 +462,23 @@ console.log('');
 console.log('  Next: edit qa/qa-framework.config.json, then read qa/AGENT-NEXT-STEPS.md');
 console.log('');
 
+if (agentFailures.length) {
+  if (skipIfExists) {
+    // Postinstall mode: a non-zero exit would make `npm install` of this package fail,
+    // which blocks the user from ever reaching the fix. Report loudly, exit 0.
+    for (const { agentName, fileName, error } of agentFailures) {
+      console.error(`[qa-framework/init] WARNING: agent ${agentName} (.claude/agents/${fileName}) was not generated. ${error.message}`);
+    }
+    console.error('[qa-framework/init] WARNING: fix qa-framework.config.json (run "npx qa-framework validate"), then run "npx qa-framework upgrade" to generate the missing agent.');
+  } else {
+    for (const { fileName, error } of agentFailures) {
+      console.error(`[qa-framework/init] ERROR: .claude/agents/${fileName} was not generated. ${error.message}`);
+    }
+    console.error('[qa-framework/init] Fix qa-framework.config.json (run "qa-framework validate") and run init or upgrade again.');
+    process.exitCode = 1;
+  }
+}
+
 // -----------------------------------------------------------------------
 // Helpers
 // -----------------------------------------------------------------------

package/scripts/lib/claude-agents.js

@@ -7,22 +7,71 @@
  * qa-framework.config.json. Claude Code only - subagents with per-agent tools/model
  * frontmatter have no GitHub Copilot equivalent, so no .github/ counterpart is generated.
  *
- * Placeholders are resolved from config.integrations.azureDevOps.sprintCycle, falling back
- * to neutral defaults when a field (or the whole config section) is absent.
+ * Placeholders are resolved from the project config, falling back to neutral defaults
+ * when a field (or the whole config section) is absent.
+ *
+ * Template syntax:
+ *   {{NAME}}                         placeholder, replaced in a single pass (values are
+ *                                    inserted verbatim and never re-expanded)
+ *   {{#if FLAG}}...{{/if}}           kept only when FLAG is true (not nestable)
+ *   {{#unless FLAG}}...{{/unless}}   kept only when FLAG is false (not nestable)
+ *
+ * Any {{...}} token left after rendering is a template bug and throws.
+ *
+ * buildAgentContent() throws per agent, so callers can generate the agents that are
+ * valid, report the one that is not, and exit non-zero.
  */
 
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_NAMES = ['qa-analisis', 'qa-plan', 'qa-asesoria', 'qa-informe-resultados'];
+const { laneTableFromConfig, DEFAULT_LANE_TABLE } = require('../../templates/automation-scaffold/scripts/lane-config');
+
+const AGENT_NAMES = [
+  'qa-analisis',
+  'qa-plan',
+  'qa-asesoria',
+  'qa-informe-resultados',
+  'qa-reporte-ejecucion',
+  'qa-investigador',
+];
 
 const DEFAULT_SPRINT_CYCLE = {
   sprintDurationDays: 8,
   manualTestingTimeboxDays: 2,
   dateFormat: 'dd-mm-aaaa',
   timezone: 'America/Santiago',
+  approvalThresholdPercent: 85,
 };
 
+const DEFAULT_TC_ID_PATTERN = 'TC-{MODULE}-{SUBMODULE}-{NUM}';
+const NOT_CONFIGURED = '(no configurado: ver qa/qa-framework.config.json)';
+
+const MCP_NAMESPACE_PATTERN = /^mcp__[A-Za-z0-9_-]+__$/;
+const DEFECT_ID_PREFIX_PATTERN = /^[A-Z0-9-]+$/;
+const DECIMAL_SEPARATORS = [',', '.'];
+
+// Playwright MCP tools granted to qa-investigador per lane namespace, in this order.
+const BROWSER_TOOLS = [
+  'browser_navigate',
+  'browser_snapshot',
+  'browser_click',
+  'browser_type',
+  'browser_fill_form',
+  'browser_select_option',
+  'browser_hover',
+  'browser_press_key',
+  'browser_wait_for',
+  'browser_evaluate',
+  'browser_network_requests',
+  'browser_console_messages',
+  'browser_take_screenshot',
+  'browser_find',
+  'browser_close',
+];
+
+const INVESTIGATOR_BASE_TOOLS = ['Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash'];
+
 const LOCALE_LANGUAGE_LABELS = {
   es: 'espanol',
   'es-cl': 'espanol de Chile',
@@ -31,6 +80,10 @@ const LOCALE_LANGUAGE_LABELS = {
   en: 'English',
 };
 
+// Tokens whose value depends on the lane table. They are resolved only for templates
+// that use them, so an invalid lane config fails qa-investigador and nothing else.
+const LANE_TOKENS = ['{{INVESTIGATOR_TOOLS}}', '{{LANE_MCP_TABLE}}', 'HAS_MCP_LANES'];
+
 function isSprintCycleEnabled(config) {
   return Boolean(config?.integrations?.azureDevOps?.sprintCycle?.enabled);
 }
@@ -40,9 +93,98 @@ function resolveLocaleLanguageLabel(locale) {
   return LOCALE_LANGUAGE_LABELS[locale.toLowerCase()] ?? locale;
 }
 
+function isValidApprovalThreshold(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 && value < 100;
+}
+
+function resolveApprovalThresholdPercent(sprintCycle) {
+  const value = sprintCycle.approvalThresholdPercent;
+  // Invalid values are reported by `qa-framework validate`; generation keeps the default.
+  return isValidApprovalThreshold(value) ? value : DEFAULT_SPRINT_CYCLE.approvalThresholdPercent;
+}
+
+function formatRatio(percent) {
+  // Rounded to strip binary float noise (e.g. 57 / 100), always with a dot.
+  return String(Number((percent / 100).toFixed(6)));
+}
+
+function resolveDecimalSeparator(config) {
+  const explicit = config?.conventions?.decimalSeparator;
+  if (DECIMAL_SEPARATORS.includes(explicit)) return explicit;
+  const locale = config?.conventions?.locale ?? config?.conventions?.language;
+  if (!locale) return ',';
+  return String(locale).toLowerCase().startsWith('es') ? ',' : '.';
+}
+
+function resolveDefectIdPrefix(config) {
+  const explicit = config?.conventions?.defectIdPrefix;
+  if (typeof explicit === 'string' && DEFECT_ID_PREFIX_PATTERN.test(explicit)) return explicit;
+  return config?.project?.name ? config.project.name.toUpperCase().replace(/[^A-Z0-9]/g, '-') : 'PROJ';
+}
+
+function resolveProjectField(value) {
+  if (typeof value !== 'string' || value.trim() === '' || value.includes('{{')) return NOT_CONFIGURED;
+  return value;
+}
+
+/**
+ * MCP-capable lanes in config order: [{ id, mcpNamespace }].
+ *
+ * Validation is delegated to laneTableFromConfig (the same reader the automation
+ * scaffold uses). Order comes from the config array, not from the table object,
+ * because numeric-like lane ids would otherwise be reordered by the JS engine.
+ * Throws on an invalid lane block or an mcpNamespace that is not a tool prefix.
+ */
+function resolveMcpLanes(config) {
+  const table = laneTableFromConfig(config);
+  if (table === DEFAULT_LANE_TABLE) return [];
+
+  const lanes = [];
+  for (const [index, entry] of config.parallelLanes.lanes.entries()) {
+    const lane = table[entry.id];
+    if (!lane || lane.mcpNamespace === null) continue;
+    if (!MCP_NAMESPACE_PATTERN.test(lane.mcpNamespace)) {
+      throw new Error(
+        `parallelLanes.lanes[${index}].mcpNamespace must match ${MCP_NAMESPACE_PATTERN} ` +
+          `(e.g. "mcp__playwright-qauser__"). Got: ${JSON.stringify(lane.mcpNamespace)}`
+      );
+    }
+    lanes.push({ id: entry.id, mcpNamespace: lane.mcpNamespace });
+  }
+  return lanes;
+}
+
+function buildLanePlaceholders(config) {
+  const mcpLanes = resolveMcpLanes(config);
+
+  const tools = [...INVESTIGATOR_BASE_TOOLS];
+  for (const { mcpNamespace } of mcpLanes) {
+    for (const tool of BROWSER_TOOLS) tools.push(`${mcpNamespace}${tool}`);
+  }
+
+  const tableLines = mcpLanes.length
+    ? [
+        '| Lane | Servidor MCP | Prefijo de herramientas |',
+        '| --- | --- | --- |',
+        ...mcpLanes.map(({ id, mcpNamespace }) =>
+          `| ${id} | ${mcpNamespace.replace(/^mcp__/, '').replace(/__$/, '')} | \`${mcpNamespace}\` |`
+        ),
+      ]
+    : [];
+
+  return {
+    placeholders: {
+      '{{INVESTIGATOR_TOOLS}}': tools.join(', '),
+      '{{LANE_MCP_TABLE}}': tableLines.join('\n'),
+    },
+    flags: { HAS_MCP_LANES: mcpLanes.length > 0 },
+  };
+}
+
 function buildPlaceholders(config) {
   const sprintCycle = { ...DEFAULT_SPRINT_CYCLE, ...(config?.integrations?.azureDevOps?.sprintCycle ?? {}) };
   const project = config?.project ?? {};
+  const approvalPercent = resolveApprovalThresholdPercent(sprintCycle);
 
   return {
     '{{PROJECT_NAME}}': project.name ?? '{{PROJECT_NAME}}',
@@ -52,18 +194,138 @@ function buildPlaceholders(config) {
     '{{DATE_FORMAT}}': sprintCycle.dateFormat,
     '{{TIMEZONE}}': sprintCycle.timezone,
     '{{LOCALE_LANGUAGE_LABEL}}': resolveLocaleLanguageLabel(config?.conventions?.locale ?? config?.conventions?.language),
-    '{{DEFECT_ID_PREFIX}}': config?.project?.name ? config.project.name.toUpperCase().replace(/[^A-Z0-9]/g, '-') : 'PROJ',
+    '{{DEFECT_ID_PREFIX}}': resolveDefectIdPrefix(config),
+    '{{APPROVAL_THRESHOLD_PERCENT}}': String(approvalPercent).replace('.', resolveDecimalSeparator(config)),
+    '{{APPROVAL_THRESHOLD_RATIO}}': formatRatio(approvalPercent),
+    '{{DECIMAL_SEPARATOR}}': resolveDecimalSeparator(config),
+    '{{TC_ID_PATTERN}}': config?.conventions?.testCaseIdPattern || DEFAULT_TC_ID_PATTERN,
+    '{{QA_BASE_URL}}': resolveProjectField(project.qaBaseUrl),
+    '{{LOGIN_PATH}}': resolveProjectField(project.loginPath),
+    '{{TECH_STACK}}': resolveProjectField(project.techStack),
   };
 }
 
+/**
+ * Renders conditional blocks, then placeholders, then guards against leftovers.
+ *
+ * A block whose opening and closing tags sit on their own lines is removed together
+ * with those lines, so dropping a block never leaves an extra blank line behind.
+ */
+function renderTemplate(template, placeholders, flags, agentName) {
+  let content = template;
+
+  for (const [keyword, keepWhen] of [['if', true], ['unless', false]]) {
+    const ownLine = new RegExp(
+      `^[ \\t]*\\{\\{#${keyword} ([A-Z0-9_]+)\\}\\}[ \\t]*\\r?\\n([\\s\\S]*?)^[ \\t]*\\{\\{\\/${keyword}\\}\\}[ \\t]*(?:\\r?\\n|$)`,
+      'gm'
+    );
+    const inline = new RegExp(`\\{\\{#${keyword} ([A-Z0-9_]+)\\}\\}([\\s\\S]*?)\\{\\{\\/${keyword}\\}\\}`, 'g');
+    const choose = (match, flag, body) => (Boolean(flags[flag]) === keepWhen ? body : '');
+    content = content.replace(ownLine, choose).replace(inline, choose);
+  }
+
+  const leftovers = new Set();
+  content = content.replace(/\{\{[#/]?[A-Za-z0-9_ ]+\}\}/g, (token) => {
+    if (Object.prototype.hasOwnProperty.call(placeholders, token)) return placeholders[token];
+    leftovers.add(token);
+    return token;
+  });
+
+  if (leftovers.size) {
+    throw new Error(
+      `Template for agent ${agentName} has unresolved tokens: ${[...leftovers].join(', ')}`
+    );
+  }
+  return content;
+}
+
 function buildAgentContent(agentName, templatesDir, config) {
   const templatePath = path.join(templatesDir, 'agents', `${agentName}.md`);
-  let content = fs.readFileSync(templatePath, 'utf8');
-  const placeholders = buildPlaceholders(config);
-  for (const [placeholder, value] of Object.entries(placeholders)) {
-    content = content.split(placeholder).join(value);
+  try {
+    const template = fs.readFileSync(templatePath, 'utf8');
+    const placeholders = buildPlaceholders(config);
+    let flags = {};
+    if (LANE_TOKENS.some((token) => template.includes(token))) {
+      const lane = buildLanePlaceholders(config);
+      Object.assign(placeholders, lane.placeholders);
+      flags = lane.flags;
+    }
+    return renderTemplate(template, placeholders, flags, agentName);
+  } catch (err) {
+    if (err.message.startsWith(`Cannot generate agent ${agentName}`)) throw err;
+    throw new Error(`Cannot generate agent ${agentName}: ${err.message.replace(/^\[lane-config\] /, '')}`);
   }
-  return content;
+}
+
+/**
+ * Renders every agent, never letting one failure stop the others.
+ * Returns [{ agentName, fileName, content }] or [{ agentName, fileName, error }].
+ */
+function renderAllAgents(templatesDir, config) {
+  return AGENT_NAMES.map((agentName) => {
+    const fileName = agentFileName(agentName);
+    try {
+      return { agentName, fileName, content: buildAgentContent(agentName, templatesDir, config) };
+    } catch (error) {
+      return { agentName, fileName, error };
+    }
+  });
+}
+
+/**
+ * Present-but-invalid values of the config keys the agents consume.
+ * Absent keys are never reported. Returns an array of messages.
+ */
+function validateAgentConfig(config) {
+  const errors = [];
+  const conventions = config?.conventions ?? {};
+  const sprintCycle = config?.integrations?.azureDevOps?.sprintCycle ?? {};
+
+  if ('approvalThresholdPercent' in sprintCycle && !isValidApprovalThreshold(sprintCycle.approvalThresholdPercent)) {
+    errors.push(
+      'integrations.azureDevOps.sprintCycle.approvalThresholdPercent must be a number greater than 0 and less than 100. ' +
+        `Got: ${JSON.stringify(sprintCycle.approvalThresholdPercent)}`
+    );
+  }
+  if ('decimalSeparator' in conventions && !DECIMAL_SEPARATORS.includes(conventions.decimalSeparator)) {
+    errors.push(`conventions.decimalSeparator must be "," or ".". Got: ${JSON.stringify(conventions.decimalSeparator)}`);
+  }
+  if (
+    'defectIdPrefix' in conventions &&
+    (typeof conventions.defectIdPrefix !== 'string' || !DEFECT_ID_PREFIX_PATTERN.test(conventions.defectIdPrefix))
+  ) {
+    errors.push(
+      `conventions.defectIdPrefix must match ${DEFECT_ID_PREFIX_PATTERN} (uppercase letters, digits, "-"). ` +
+        `Got: ${JSON.stringify(conventions.defectIdPrefix)}`
+    );
+  }
+
+  // Lanes are only checked when the generator actually consumes them: sprint agents on
+  // and a lane block that laneTableFromConfig does not short-circuit (enabled !== false).
+  // A disabled block, or a project without sprint agents, never fails validate here.
+  const block = config?.parallelLanes;
+  const lanesInUse =
+    isSprintCycleEnabled(config) && block !== undefined && block !== null && block.enabled !== false;
+  if (!lanesInUse) return errors;
+
+  const lanes = block.lanes;
+  if (Array.isArray(lanes)) {
+    lanes.forEach((lane, index) => {
+      const ns = lane && typeof lane === 'object' ? lane.mcpNamespace : undefined;
+      if (ns !== undefined && ns !== null && (typeof ns !== 'string' || !MCP_NAMESPACE_PATTERN.test(ns))) {
+        errors.push(
+          `parallelLanes.lanes[${index}].mcpNamespace must match ${MCP_NAMESPACE_PATTERN} or be null. Got: ${JSON.stringify(ns)}`
+        );
+      }
+    });
+  }
+  try {
+    laneTableFromConfig(config);
+  } catch (err) {
+    errors.push(`parallelLanes: ${err.message.replace(/^\[lane-config\] /, '')}`);
+  }
+
+  return errors;
 }
 
 function agentFileName(agentName) {
@@ -72,7 +334,14 @@ function agentFileName(agentName) {
 
 module.exports = {
   AGENT_NAMES,
+  BROWSER_TOOLS,
+  DEFAULT_SPRINT_CYCLE,
   isSprintCycleEnabled,
+  buildPlaceholders,
+  resolveMcpLanes,
+  renderTemplate,
   buildAgentContent,
+  renderAllAgents,
+  validateAgentConfig,
   agentFileName,
 };

package/scripts/lib/module-keys.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * scripts/lib/module-keys.js - the one place that knows how a module or submodule
+ * key maps to a folder name.
+ *
+ * Two layouts coexist on purpose, and they are NOT the same string:
+ *
+ *   specs       qa/01-specifications/module-{name}/submodule-{name}/
+ *   automation  qa/07-automation/e2e/tests/{name}/{name}.spec.ts
+ *
+ * The prefixed form is what every skill under skills/, docs/folder-structure-guide.md
+ * and the "specPath" field of qa-framework.config.json declare. The bare form is what
+ * "automationPath" declares and what the live consuming projects actually contain.
+ * init.js used to write the bare form in both places, so a freshly scaffolded project
+ * violated the spec-path convention its own agent instructions impose.
+ *
+ * Both helpers are idempotent: a config that already spells the key as
+ * "module-suppliers" must not become "module-module-suppliers", and a key written
+ * bare must not lose a leading segment that merely looks like a prefix.
+ */
+
+/** Prefix `key` with `prefix-` unless it already carries it. */
+function withPrefix(prefix, key) {
+  const marker = `${prefix}-`;
+  return key.startsWith(marker) ? key : marker + key;
+}
+
+/** Strip a leading `prefix-` from `key` if present. */
+function withoutPrefix(prefix, key) {
+  const marker = `${prefix}-`;
+  return key.startsWith(marker) ? key.slice(marker.length) : key;
+}
+
+/** Folder name for a module's spec tree: module-{name}. */
+const moduleSpecDirName = key => withPrefix('module', key);
+
+/** Folder name for a submodule's spec tree: submodule-{name}. */
+const submoduleSpecDirName = key => withPrefix('submodule', key);
+
+/** Bare module name used by automation paths and TC ids. */
+const moduleBareName = key => withoutPrefix('module', key);
+
+/** Bare submodule name used by automation paths and TC ids. */
+const submoduleBareName = key => withoutPrefix('submodule', key);
+
+module.exports = {
+  withPrefix,
+  withoutPrefix,
+  moduleSpecDirName,
+  submoduleSpecDirName,
+  moduleBareName,
+  submoduleBareName,
+};

package/scripts/sync-version.js

@@ -13,6 +13,15 @@ const targets = [
   path.join(rootDir, '.github', 'copilot-instructions.md'),
 ];
 
+// qa-framework.config.json is published and is the template init.js copies into every
+// consuming project, where its frameworkVersion is injected into {{VERSION}} of the
+// generated agent instructions. Left out of this sync it silently drifted to 1.10.0
+// while the package shipped 1.12.0, so every fresh install told its agent the wrong
+// version. It is patched by field, not by the loose vX.Y.Z pattern used for prose.
+const jsonTargets = [
+  { file: path.join(rootDir, 'qa-framework.config.json'), field: 'frameworkVersion' },
+];
+
 // templates/qa-framework.instructions.md and templates/qa-framework.rules.md contain a
 // literal {{VERSION}} placeholder substituted by init.js/upgrade.js in the consumer
 // project at install/upgrade time. That placeholder is NOT a hardcoded version string
@@ -20,6 +29,24 @@ const targets = [
 
 const versionPattern = /v\d+\.\d+\.\d+/;
 
+for (const { file: filePath, field } of jsonTargets) {
+  const original = fs.readFileSync(filePath, 'utf8');
+  const fieldPattern = new RegExp(
+    `("${field}"\\s*:\\s*")\\d+\\.\\d+\\.\\d+(")`
+  );
+
+  if (!fieldPattern.test(original)) {
+    throw new Error(`sync-version: no "${field}" version field in ${filePath}`);
+  }
+
+  const updated = original.replace(fieldPattern, `$1${version}$2`);
+
+  if (updated !== original) {
+    fs.writeFileSync(filePath, updated, 'utf8');
+    console.log(`sync-version: updated ${path.relative(rootDir, filePath)} ${field} -> ${version}`);
+  }
+}
+
 for (const filePath of targets) {
   const original = fs.readFileSync(filePath, 'utf8');
 

package/scripts/upgrade.js

@@ -77,7 +77,7 @@ const fs   = require('fs');
 const path = require('path');
 
 const { buildCommandContent, discoverSkillNames, commandFileName } = require('./lib/claude-commands');
-const { AGENT_NAMES, isSprintCycleEnabled, buildAgentContent, agentFileName } = require('./lib/claude-agents');
+const { isSprintCycleEnabled, renderAllAgents } = require('./lib/claude-agents');
 
 const args   = process.argv.slice(2);
 const dryRun = args.includes('--dry-run');
@@ -152,6 +152,7 @@ const SHIPPED_SCAFFOLD_HASHES = {
 const updated  = [];
 const skipped  = [];
 const warnings = [];
+const errors   = [];
 
 console.log(`\n[qa-framework/upgrade] ${dryRun ? '(dry-run) ' : ''}Upgrading framework-owned files`);
 console.log(`[qa-framework/upgrade] Project root: ${cwd}\n`);
@@ -197,8 +198,14 @@ forceWrite(claudeRulesPath, claudeRulesContent);
 if (isSprintCycleEnabled(config)) {
   const templatesDir = path.resolve(__dirname, '..', 'templates');
   const claudeAgentsDest = path.join(cwd, '.claude', 'agents');
-  for (const agentName of AGENT_NAMES) {
-    forceWrite(path.join(claudeAgentsDest, agentFileName(agentName)), buildAgentContent(agentName, templatesDir, config));
+  // Rendered per agent: one invalid agent (e.g. qa-investigador with a bad lane config)
+  // is reported and left untouched on disk, the others are still upgraded.
+  for (const agent of renderAllAgents(templatesDir, config)) {
+    if (agent.error) {
+      errors.push(`.claude/agents/${agent.fileName} was not generated. ${agent.error.message}`);
+      continue;
+    }
+    forceWrite(path.join(claudeAgentsDest, agent.fileName), agent.content);
   }
 }
 
@@ -704,6 +711,12 @@ if (warnings.length) {
   for (const w of warnings) console.log(`    ⚠️  ${w}`);
 }
 
+if (errors.length) {
+  for (const e of errors) console.error(`[qa-framework/upgrade] ERROR: ${e}`);
+  console.error('[qa-framework/upgrade] Fix qa-framework.config.json (run "qa-framework validate") and run upgrade again.');
+  process.exitCode = 1;
+}
+
 console.log('\n[qa-framework/upgrade] Done.\n');
 
 // -----------------------------------------------------------------------