@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/projects.js

@@ -12,8 +12,12 @@ const dispatch = require('./dispatch');
 const queries = require('./queries');
 const projectDiscovery = require('./project-discovery');
 const scheduleBootstrap = require('./schedule-bootstrap');
+const apiValidation = require('./api-validation');
 const { MINIONS_DIR } = shared;
 
+const PROJECT_PATH_MAX_LENGTH = 4096;
+const PROJECT_CONFIRM_TOKEN_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
 function _httpError(status, message, extra) {
   const err = new Error(message);
   err.statusCode = status;
@@ -25,6 +29,169 @@ function _sameProjectName(a, b) {
   return String(a || '').toLowerCase() === String(b || '').toLowerCase();
 }
 
+function _validateProjectPathInput(value, field = 'path') {
+  const validated = apiValidation.validateString(value, {
+    field,
+    path: `body.${field}`,
+    trim: true,
+    allowEmpty: false,
+    maxLength: PROJECT_PATH_MAX_LENGTH,
+  });
+  if (validated.includes('\0')) {
+    throw new apiValidation.ApiInputError(`${field} must not contain a null byte`, {
+      code: 'invalid-project-path',
+      field,
+      path: `body.${field}`,
+      rejectedValue: validated,
+    });
+  }
+  return validated;
+}
+
+function _validateCheckoutModeInput(value, field) {
+  try { return shared.validateCheckoutMode(value); }
+  catch (e) {
+    throw new apiValidation.ApiInputError(e.message, {
+      code: 'invalid-checkout-mode',
+      field,
+      path: `body.${field}`,
+      rejectedValue: value,
+    });
+  }
+}
+
+function validateProjectAddInput(target, options = {}) {
+  apiValidation.validatePlainObject(options, { path: 'options' });
+  const inputPath = _validateProjectPathInput(
+    typeof target === 'string' ? target : target && target.path,
+  );
+
+  let name;
+  if (options.name !== undefined) {
+    name = apiValidation.validateString(options.name, {
+      field: 'name',
+      path: 'body.name',
+      trim: true,
+      allowEmpty: false,
+      maxLength: 64,
+    });
+    shared.validateProjectName(name);
+  }
+
+  const allowNonRepo = options.allowNonRepo === undefined
+    ? false
+    : apiValidation.validateBoolean(options.allowNonRepo, {
+      field: 'allowNonRepo',
+      path: 'body.allowNonRepo',
+    });
+  let confirmToken;
+  if (options.confirmToken !== undefined) {
+    confirmToken = apiValidation.validateIdentifier(options.confirmToken, {
+      field: 'confirmToken',
+      path: 'body.confirmToken',
+      trim: true,
+      maxLength: 36,
+      pattern: PROJECT_CONFIRM_TOKEN_RE,
+    });
+  }
+  if (allowNonRepo && !confirmToken) {
+    throw new apiValidation.ApiInputError(
+      'confirmToken is required when allowNonRepo is true',
+      {
+        code: 'confirmation-required',
+        field: 'confirmToken',
+        path: 'body.confirmToken',
+      },
+    );
+  }
+  if (!allowNonRepo && confirmToken) {
+    throw new apiValidation.ApiInputError(
+      'confirmToken is only valid when allowNonRepo is true',
+      {
+        code: 'conflicting-options',
+        field: 'confirmToken',
+        path: 'body.confirmToken',
+      },
+    );
+  }
+
+  const canonicalMode = _validateCheckoutModeInput(options.checkoutMode, 'checkoutMode');
+  const legacyMode = _validateCheckoutModeInput(options.worktreeMode, 'worktreeMode');
+  if (canonicalMode && legacyMode && canonicalMode !== legacyMode) {
+    throw new apiValidation.ApiInputError(
+      'checkoutMode and worktreeMode must resolve to the same value',
+      {
+        code: 'conflicting-options',
+        field: 'checkoutMode',
+        path: 'body.checkoutMode',
+      },
+    );
+  }
+
+  let observeAuthors;
+  if (options.observeAuthors !== undefined) {
+    observeAuthors = apiValidation.validateArray(options.observeAuthors, {
+      field: 'observeAuthors',
+      path: 'body.observeAuthors',
+      maxLength: 100,
+      itemValidator: (entry, context) => apiValidation.validateString(entry, {
+        field: 'observeAuthors',
+        path: context.path,
+        trim: true,
+        allowEmpty: false,
+        maxLength: 320,
+      }),
+    }).map(entry => entry.trim());
+  }
+
+  return {
+    inputPath,
+    allowNonRepo,
+    confirmToken,
+    name,
+    checkoutMode: canonicalMode || legacyMode,
+    observeAuthors,
+  };
+}
+
+function resolveProjectRemovalDataMode(options = {}) {
+  apiValidation.validatePlainObject(options, { path: 'options' });
+  const keepData = options.keepData === undefined
+    ? false
+    : apiValidation.validateBoolean(options.keepData, {
+      field: 'keepData',
+      path: 'options.keepData',
+    });
+  const purge = options.purge === undefined
+    ? false
+    : apiValidation.validateBoolean(options.purge, {
+      field: 'purge',
+      path: 'options.purge',
+    });
+  const dataMode = options.dataMode === undefined
+    ? undefined
+    : apiValidation.validateEnum(options.dataMode, {
+      field: 'dataMode',
+      path: 'options.dataMode',
+      values: ['archive', 'keep', 'purge'],
+    });
+  const selectedModes = new Set([
+    dataMode,
+    keepData ? 'keep' : null,
+    purge ? 'purge' : null,
+  ].filter(Boolean));
+  if (selectedModes.size > 1) {
+    throw new apiValidation.ApiInputError(
+      'keepData, purge, and dataMode contain conflicting removal modes',
+      {
+        code: 'conflicting-options',
+        path: 'options',
+      },
+    );
+  }
+  return selectedModes.values().next().value || 'archive';
+}
+
 // Windows EPERM/EBUSY can hit fs.renameSync transiently when antivirus,
 // indexer, or another scanner has the directory open. Retry with backoff
 // before giving up — same pattern used by shared.safeWrite for atomic
@@ -131,7 +298,6 @@ function _requeueProjectlessCentralWorkItems(itemIds) {
  *   purgedDataDir, pipelineRefs[], warnings[] } or { ok:false, error }
  */
 function removeProject(target, options = {}) {
-  const dataMode = options.dataMode || (options.purge ? 'purge' : (options.keepData ? 'keep' : 'archive'));
   const summary = {
     ok: false,
     project: null,
@@ -150,6 +316,28 @@ function removeProject(target, options = {}) {
     orphanedRefs: { pullRequests: 0, workItems: 0, dispatches: 0 },
     warnings: [],
   };
+  let normalizedTarget;
+  let dataMode;
+  try {
+    normalizedTarget = apiValidation.validateString(target, {
+      field: 'target',
+      path: 'target',
+      trim: true,
+      allowEmpty: false,
+      maxLength: PROJECT_PATH_MAX_LENGTH,
+    });
+    if (normalizedTarget.includes('\0')) {
+      throw new apiValidation.ApiInputError('target must not contain a null byte', {
+        code: 'invalid-project-selector',
+        field: 'target',
+        path: 'target',
+        rejectedValue: normalizedTarget,
+      });
+    }
+    dataMode = resolveProjectRemovalDataMode(options);
+  } catch (e) {
+    return { ...summary, error: e.message, ...(e.code ? { code: e.code } : {}) };
+  }
 
   const configPath = path.join(MINIONS_DIR, 'config.json');
   let config;
@@ -157,10 +345,10 @@ function removeProject(target, options = {}) {
   catch (e) { return { ...summary, error: 'Failed to read config: ' + e.message }; }
 
   const projects = shared.getProjects(config);
-  const project = shared.resolveConfiguredProject(target, projects).project;
+  const project = shared.resolveConfiguredProject(normalizedTarget, projects).project;
   if (!project) {
     const available = projects.map(p => p.name).join(', ') || '(none)';
-    return { ...summary, error: `No project linked matching: ${target}. Available: ${available}` };
+    return { ...summary, error: `No project linked matching: ${normalizedTarget}. Available: ${available}` };
   }
   summary.project = { name: project.name, localPath: project.localPath };
 
@@ -469,16 +657,14 @@ function assertProjectLinkOk(project) {
 }
 
 async function addProject(target, options = {}) {
-  const inputPath = typeof target === 'string' ? target : (target && target.path);
-  if (!inputPath || typeof inputPath !== 'string') {
-    throw _httpError(400, 'addProject: target path required');
-  }
+  const validated = validateProjectAddInput(target, options);
+  const { inputPath } = validated;
 
   // 1. Validate path (must exist + be a git repo OR caller opts in via
   //    allowNonRepo + confirmToken — same contract as the dashboard handler).
   const resolved = shared.validateProjectPath(inputPath, {
-    allowNonRepo: options.allowNonRepo === true,
-    confirmToken: options.confirmToken,
+    allowNonRepo: validated.allowNonRepo,
+    confirmToken: validated.confirmToken,
     isValidToken: options.isValidToken,
   });
 
@@ -501,7 +687,7 @@ async function addProject(target, options = {}) {
   if (!detected.name) detected.name = path.basename(resolved);
 
   // 4. Validate name (rejects shell metacharacters, path separators, …).
-  const rawName = options.name || detected.name;
+  const rawName = validated.name || detected.name;
   const name = shared.validateProjectName(rawName);
 
   // 5. Build entry.
@@ -516,8 +702,8 @@ async function addProject(target, options = {}) {
     repoName: detected.repoName || name,
     mainBranch: detected.mainBranch || 'main',
     prUrlBase: detected.prUrlBase,
-    checkoutMode: options.checkoutMode ?? options.worktreeMode,
-    observeAuthors: Array.isArray(options.observeAuthors) ? options.observeAuthors : undefined,
+    checkoutMode: validated.checkoutMode,
+    observeAuthors: validated.observeAuthors,
   });
 
   // 6. Fail-closed gate. AFTER buildProjectEntry — buildProjectEntry never

package/engine/promotion.js

@@ -0,0 +1,371 @@
+// engine/promotion.js — human-approved promotion of verified review lessons into
+// repository guidance (project skills or allowlisted instruction files) and the
+// shared project-bound skill work-item queueing logic reused by skill
+// extraction. Promotion NEVER edits an operator checkout: every path queues a
+// normal project-bound work item that follows the standard branch → PR → review
+// → merge lifecycle. Vanilla Copilot/Claude only see the guidance once that PR
+// merges through native instruction/skill discovery (P-192d3660).
+
+const crypto = require('crypto');
+const shared = require('./shared');
+const reviewLearning = require('./review-learning');
+
+const { WI_STATUS, WORK_TYPE } = shared;
+
+const PROMOTION_TARGET_KINDS = Object.freeze(['project-skill', 'repository-instruction']);
+// High-confidence + repeatedly-observed gate. A lesson owns one finding key, so
+// "≥ 2 distinct valid findings" means the rule recurred at least once (the
+// original finding plus one repeated-finding occurrence).
+const MIN_PROMOTION_CONFIDENCE = 0.8;
+const MIN_DISTINCT_FINDINGS = 2;
+const MAX_PROMOTION_PATH_BYTES = 200;
+
+function badRequest(message) {
+  const err = new Error(message);
+  err.statusCode = 400;
+  return err;
+}
+
+function normalizePromotionTargetKind(value) {
+  const kind = String(value || '').trim().toLowerCase();
+  if (!PROMOTION_TARGET_KINDS.includes(kind)) {
+    throw badRequest(`invalid promotion target kind: ${value}. Choose ${PROMOTION_TARGET_KINDS.join(' or ')}`);
+  }
+  return kind;
+}
+
+// Repository-instruction promotions may only ever land in the files vanilla
+// runtimes natively discover: CLAUDE.md / AGENTS.md at any depth, or the
+// GitHub Copilot instruction file. Skills use the separate project-skill kind.
+function isAllowedInstructionPath(relPath) {
+  const p = String(relPath || '').trim();
+  if (!p) return false;
+  const base = p.split('/').pop();
+  if (base === 'CLAUDE.md' || base === 'AGENTS.md') return true;
+  if (/(^|\/)\.github\/copilot-instructions\.md$/.test(p)) return true;
+  return false;
+}
+
+function normalizePromotionPath(kind, rawPath) {
+  const targetKind = normalizePromotionTargetKind(kind);
+  const raw = String(rawPath || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!raw) throw badRequest('promotion target path is required');
+  if (Buffer.byteLength(raw, 'utf8') > MAX_PROMOTION_PATH_BYTES) {
+    throw badRequest(`promotion target path exceeds ${MAX_PROMOTION_PATH_BYTES} bytes`);
+  }
+  if (raw.startsWith('/') || /^[a-z]:/i.test(raw)) {
+    throw badRequest('promotion target path must be repository-relative');
+  }
+  if (raw.split('/').some(seg => seg === '..' || seg === '.' || seg === '')) {
+    throw badRequest('promotion target path must not contain traversal or empty segments');
+  }
+  if (targetKind === 'project-skill') {
+    const slug = raw.replace(/\/SKILL\.md$/i, '');
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug)) {
+      throw badRequest('project-skill path must be a lowercase kebab-case slug (e.g. verify-branch-before-fix)');
+    }
+    const displayPath = `${slug}/SKILL.md`;
+    return { targetKind, targetPath: displayPath, displayPath, slug };
+  }
+  if (!isAllowedInstructionPath(raw)) {
+    throw badRequest(
+      `repository instruction path not allowlisted: ${raw}. Allowed: CLAUDE.md, AGENTS.md (any directory), .github/copilot-instructions.md`,
+    );
+  }
+  return { targetKind, targetPath: raw, displayPath: raw };
+}
+
+// Bounded generalized rules extracted from a lesson body ("Rules:\n- ...").
+function extractLessonRules(lesson) {
+  const body = String(lesson?.body || '');
+  const rules = body
+    .split(/\r?\n/)
+    .map(line => (line.match(/^\s*-\s+(.+)$/) || [])[1])
+    .map(rule => (rule == null ? '' : String(rule).trim()))
+    .filter(Boolean);
+  return rules
+    .map(rule => reviewLearning.redactBoundedText(
+      rule,
+      reviewLearning.REVIEW_LEARNING_BOUNDS.ruleBytes,
+      'promotion rule',
+    ))
+    .slice(0, reviewLearning.REVIEW_LEARNING_BOUNDS.rules);
+}
+
+function evaluateLessonPromotionEligibility(lesson, support = {}) {
+  const reasons = [];
+  const distinctFindings = Number(support.distinctFindings) || 0;
+  const confidence = Number(lesson && lesson.confidence);
+  if (!lesson || lesson.sourceType !== reviewLearning.REVIEW_LEARNING_SOURCE_TYPE) {
+    reasons.push('not-a-review-learning-record');
+  } else {
+    if (lesson.memoryType !== 'procedural' || (lesson.metadata && lesson.metadata.kind) !== 'review-learning-lesson') {
+      reasons.push('not-a-review-lesson');
+    }
+    if (lesson.status !== 'active') reasons.push('lesson-not-active');
+    if (!(confidence >= MIN_PROMOTION_CONFIDENCE)) reasons.push(`confidence-below-${MIN_PROMOTION_CONFIDENCE}`);
+    if (distinctFindings < MIN_DISTINCT_FINDINGS) reasons.push(`insufficient-distinct-findings-${distinctFindings}`);
+  }
+  return {
+    eligible: reasons.length === 0,
+    reasons,
+    distinctFindings,
+    confidence: Number.isFinite(confidence) ? confidence : null,
+    minConfidence: MIN_PROMOTION_CONFIDENCE,
+    minDistinctFindings: MIN_DISTINCT_FINDINGS,
+  };
+}
+
+// Convenience for dashboard search annotation: fetch finding support + evaluate.
+function getLessonPromotionEligibility(lesson, memoryStore = require('./memory-store')) {
+  if (!lesson || lesson.sourceType !== reviewLearning.REVIEW_LEARNING_SOURCE_TYPE) {
+    return evaluateLessonPromotionEligibility(lesson, { distinctFindings: 0 });
+  }
+  let support = { distinctFindings: 0, memoryIds: lesson.id ? [lesson.id] : [] };
+  try {
+    support = memoryStore.getReviewLearningFindingSupport(lesson.id);
+  } catch { /* best-effort — treat as unsupported */ }
+  return evaluateLessonPromotionEligibility(lesson, support);
+}
+
+function buildPromotionDedupeKey({ lessonId, targetKind, project, targetPath }) {
+  const parts = [
+    String(lessonId || ''),
+    String(targetKind || ''),
+    String(project || ''),
+    String(targetPath || ''),
+  ].map(value => value.trim().toLowerCase());
+  return 'promo-' + crypto.createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 40);
+}
+
+function buildPromotionWorkItemFields({ lesson, memoryIds, rules, targetKind, project, targetPath, displayPath, operator, dedupeKey }) {
+  const isSkill = targetKind === 'project-skill';
+  const type = isSkill ? WORK_TYPE.IMPLEMENT : WORK_TYPE.DOCS;
+  const approvedBy = String(operator || 'operator').trim() || 'operator';
+  const ids = Array.isArray(memoryIds) && memoryIds.length ? memoryIds : (lesson.id ? [lesson.id] : []);
+  let ruleList = Array.isArray(rules) ? rules.filter(Boolean) : [];
+  if (!ruleList.length) {
+    const fromTitle = String(lesson.title || '').replace(/^Review lesson:\s*/i, '').trim();
+    if (fromTitle) ruleList = [fromTitle];
+  }
+  const rulesBlock = ruleList.length ? ruleList.map(rule => `- ${rule}`).join('\n') : '- (see originating memory records)';
+  const title = isSkill
+    ? `Promote review lesson to project skill: ${displayPath}`
+    : `Promote review lesson into ${displayPath}`;
+  const description = [
+    `Human-approved promotion of a verified review lesson into **${project}** repository guidance.`,
+    '',
+    `**Target:** ${targetKind} → \`${displayPath}\``,
+    `**Originating memory IDs:** ${ids.join(', ') || '(none)'}`,
+    `**Approved by:** ${approvedBy}`,
+    '',
+    '## Proposed guidance (bounded)',
+    rulesBlock,
+    '',
+    '## Instructions',
+    isSkill
+      ? `Create or extend the project skill at \`${displayPath}\` capturing the rule(s) above. Follow the repository's existing skill format (a SKILL.md with \`name\` + \`description\` frontmatter and a concise body).`
+      : `Add the rule(s) above to \`${displayPath}\` as a concise instruction. Keep the edit minimal and consistent with the file's existing structure and voice.`,
+    '',
+    'Open a normal PR for review and merge. Do NOT edit any operator checkout directly — work only in your engine-assigned worktree. Vanilla Copilot/Claude receive this guidance only after the PR merges, via native instruction/skill discovery.',
+  ].join('\n');
+  return {
+    type,
+    title,
+    description,
+    priority: (shared.WORK_ITEM_PRIORITY && shared.WORK_ITEM_PRIORITY.MEDIUM) || 'medium',
+    meta: {
+      promotion: {
+        lessonId: lesson.id,
+        memoryIds: ids,
+        targetKind,
+        targetPath,
+        displayPath,
+        project,
+        dedupeKey,
+        rules: ruleList,
+        approvedBy,
+      },
+    },
+  };
+}
+
+// Shared project-bound skill work-item queueing extracted from
+// engine/lifecycle.js#extractSkillsFromOutput. Resolves a real (non-central)
+// project, deduplicates on the "Add skill: <name>" title, and queues an
+// implementation work item. Returns { created, workItemId, duplicateOf } or null
+// when the project cannot be resolved.
+function queueProjectSkillWorkItem({ config, projectName, skillName, description, agentName, source = 'central' }) {
+  const proj = shared.resolveProjectSource(projectName, shared.getProjects(config), { allowCentral: false }).project;
+  if (!proj) return null;
+  const dupTitle = `Add skill: ${skillName}`;
+  let result = null;
+  shared.mutateWorkItems(source, data => {
+    data = data || [];
+    const existing = data.find(item => item.title === dupTitle && item.status !== WI_STATUS.FAILED);
+    if (existing) {
+      result = { created: false, workItemId: existing.id || null, duplicateOf: existing.id || null };
+      return data;
+    }
+    const skillId = `SK${String(data.filter(item => item.id && item.id.startsWith('SK')).length + 1).padStart(3, '0')}`;
+    data.push({
+      id: skillId,
+      type: WORK_TYPE.IMPLEMENT,
+      title: dupTitle,
+      description,
+      priority: 'low',
+      status: WI_STATUS.QUEUED,
+      created: shared.ts(),
+      createdBy: `engine:skill-extraction:${agentName}`,
+    });
+    result = { created: true, workItemId: skillId };
+    return data;
+  });
+  return result;
+}
+
+// Validate eligibility + target, queue a project-bound promotion work item
+// (dedup-safe), and record a `promotion-requested` lifecycle event linking the
+// originating memory records, target, and created work item. Repeated calls with
+// identical inputs return the existing work-item id without queueing duplicates.
+function queuePromotion(params = {}) {
+  const {
+    config,
+    lessonId,
+    targetKind,
+    project,
+    path: rawPath,
+    operator,
+    source,
+  } = params;
+  const memoryStore = params.memoryStore || require('./memory-store');
+
+  const lesson = memoryStore.getMemoryRecord(String(lessonId || '').trim());
+  if (!lesson) {
+    const err = new Error('memory record not found');
+    err.statusCode = 404;
+    throw err;
+  }
+  const support = memoryStore.getReviewLearningFindingSupport(lesson.id);
+  const eligibility = evaluateLessonPromotionEligibility(lesson, support);
+  if (!eligibility.eligible) {
+    throw badRequest(`lesson not eligible for promotion: ${eligibility.reasons.join('; ')}`);
+  }
+
+  const kind = normalizePromotionTargetKind(targetKind);
+  const resolved = shared.resolveProjectSource(project, shared.getProjects(config), { allowCentral: false });
+  if (resolved.error || !resolved.project) {
+    throw badRequest(resolved.error || `unknown project: ${project}`);
+  }
+  const targetProject = resolved.project;
+  const lessonProjectKey = lesson.scopeKey;
+  if (reviewLearning.normalizeProjectKey(targetProject.name) !== lessonProjectKey) {
+    throw badRequest(
+      `promotion project "${targetProject.name}" does not match the lesson's project scope "${lessonProjectKey}"`,
+    );
+  }
+
+  const { targetPath, displayPath } = normalizePromotionPath(kind, rawPath);
+  const rules = extractLessonRules(lesson);
+  const memoryIds = Array.isArray(support.memoryIds) && support.memoryIds.length
+    ? support.memoryIds
+    : [lesson.id];
+  const dedupeKey = buildPromotionDedupeKey({
+    lessonId: lesson.id,
+    targetKind: kind,
+    project: lessonProjectKey,
+    targetPath,
+  });
+  const fields = buildPromotionWorkItemFields({
+    lesson,
+    memoryIds,
+    rules,
+    targetKind: kind,
+    project: targetProject.name,
+    targetPath,
+    displayPath,
+    operator,
+    dedupeKey,
+  });
+
+  let outcome = null;
+  shared.mutateWorkItems(targetProject.name, items => {
+    items = items || [];
+    const existing = items.find(item => item.meta
+      && item.meta.promotion
+      && item.meta.promotion.dedupeKey === dedupeKey
+      && item.status !== WI_STATUS.FAILED
+      && item.status !== WI_STATUS.CANCELLED);
+    if (existing) {
+      outcome = { created: false, workItemId: existing.id, duplicateOf: existing.id, item: existing };
+      return items;
+    }
+    const id = 'W-' + shared.uid();
+    const item = {
+      id,
+      ...fields,
+      project: targetProject.name,
+      status: WI_STATUS.PENDING,
+      created: new Date().toISOString(),
+      createdBy: `dashboard:promotion:${String(operator || 'operator').trim() || 'operator'}`,
+    };
+    try {
+      const branch = shared.deriveWorkItemBranchName(item, config);
+      if (branch) item.branch = branch;
+    } catch { /* engine derives on dispatch */ }
+    items.push(item);
+    outcome = { created: true, workItemId: id, item };
+    return items;
+  });
+
+  let event = null;
+  try {
+    event = memoryStore.recordMemoryLifecycleEvent({
+      eventType: 'promotion-requested',
+      memoryId: lesson.id,
+      findingKey: lesson.sourceRef,
+      project: lessonProjectKey,
+      agent: 'operator',
+      area: (lesson.metadata && lesson.metadata.area) || 'general',
+      disposition: (lesson.metadata && lesson.metadata.disposition) || null,
+      workItemId: outcome.workItemId,
+      identity: dedupeKey,
+      metadata: {
+        targetKind: kind,
+        targetPath,
+        memoryIds,
+        dedupeKey,
+        duplicate: !outcome.created,
+      },
+    });
+  } catch { /* audit event is best-effort; must never fail the promotion */ }
+
+  return {
+    ...outcome,
+    eligibility,
+    targetKind: kind,
+    targetPath,
+    displayPath,
+    project: targetProject.name,
+    memoryIds,
+    rules,
+    dedupeKey,
+    event,
+  };
+}
+
+module.exports = {
+  PROMOTION_TARGET_KINDS,
+  MIN_PROMOTION_CONFIDENCE,
+  MIN_DISTINCT_FINDINGS,
+  normalizePromotionTargetKind,
+  normalizePromotionPath,
+  isAllowedInstructionPath,
+  extractLessonRules,
+  evaluateLessonPromotionEligibility,
+  getLessonPromotionEligibility,
+  buildPromotionDedupeKey,
+  buildPromotionWorkItemFields,
+  queueProjectSkillWorkItem,
+  queuePromotion,
+};

package/engine/qa-from-prd.js

@@ -36,6 +36,7 @@ const { LIMITS, VALID_MODES, validateSpec } = qaSessions;
 // we draft a QA flow over it — drafting against an in-progress PRD would test
 // half-built behavior.
 const QA_READY_STATUSES = new Set(['completed', 'approved']);
+const QA_PRD_FILENAME_MAX = 255;
 
 // Mirrors engine/qa-sessions.js _KEBAB_RE — runner names are kebab-case.
 const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -76,6 +77,7 @@ function _isNonEmptyString(v) {
 // endpoint can't read an arbitrary file under MINIONS_DIR.
 function _isSafePrdFileName(name) {
   if (!_isNonEmptyString(name)) return false;
+  if (name.length > QA_PRD_FILENAME_MAX) return false;
   if (name.indexOf('\0') !== -1) return false;
   if (name.indexOf('/') !== -1 || name.indexOf('\\') !== -1) return false;
   if (name.indexOf('..') !== -1) return false;
@@ -421,6 +423,7 @@ module.exports = {
   QaFromPrdError,
   // Constants + internals exposed for tests.
   QA_READY_STATUSES,
+  QA_PRD_FILENAME_MAX,
   FLOW_SOURCE,
   _isSafePrdFileName,
   _findNewestLinkedPr,