convoke-agents 3.1.0 → 3.2.1

package/scripts/lib/portfolio/portfolio-engine.js

@@ -27,6 +27,194 @@ const { formatMarkdown } = require('./formatters/markdown-formatter');
 /** Directories to exclude from portfolio scan */
 const EXCLUDE_DIRS = ['_archive', 'brainstorming', 'design-artifacts', 'journey-examples', 'project-documentation', 'test-artifacts', 'drafts'];
 
+// --- Story 6.3: Attribution helpers ---
+
+/**
+ * Scan a corpus for any taxonomy initiative ID or alias as a whole word.
+ * Mirrors `_scanCorpusForInitiative` in artifact-utils.js — kept local to avoid
+ * a cross-module dependency from portfolio into the migration suggester. The
+ * `[a-z0-9-]` boundary class keeps kebab-case identifiers atomic so `pre-gyre`
+ * does not match `gyre`.
+ *
+ * @param {string} corpus - Lowercased text to scan
+ * @param {import('../types').TaxonomyConfig} taxonomy
+ * @returns {string|null} Resolved canonical initiative ID, or null
+ */
+function _scanCorpus(corpus, taxonomy) {
+  if (!corpus || !taxonomy || !taxonomy.initiatives) return null;
+  const platform = Array.isArray(taxonomy.initiatives.platform) ? taxonomy.initiatives.platform : [];
+  const user = Array.isArray(taxonomy.initiatives.user) ? taxonomy.initiatives.user : [];
+  const allInitiatives = [...platform, ...user];
+  const aliasKeys = taxonomy.aliases ? Object.keys(taxonomy.aliases) : [];
+  const candidates = [...allInitiatives, ...aliasKeys].sort((a, b) => b.length - a.length);
+
+  for (const candidate of candidates) {
+    const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(?:^|[^a-z0-9-])${escaped}(?:$|[^a-z0-9-])`, 'i');
+    if (re.test(corpus)) {
+      if (allInitiatives.includes(candidate)) return candidate;
+      if (taxonomy.aliases && taxonomy.aliases[candidate]) return taxonomy.aliases[candidate];
+    }
+  }
+  return null;
+}
+
+/**
+ * Map of story-key filename prefixes (that are NOT taxonomy initiatives) to
+ * canonical initiative IDs. Story files (e.g. `tf-2-10-...`, `p3-1-1-...`) live
+ * in `implementation-artifacts/` and use compact prefixes that aren't real
+ * initiative IDs. Real-initiative prefixes (`gyre`, `forge`, `helm`, etc.) are
+ * resolved separately by checking taxonomy membership directly.
+ *
+ * Add new entries here when a new initiative starts producing stories under a
+ * non-initiative prefix.
+ */
+const STORY_PREFIX_MAP = Object.freeze({
+  ag: 'convoke',     // Artifact Governance — platform-level work
+  tf: 'loom',        // Team Factory → Loom
+  p2: 'convoke',     // Phase 2 — platform stabilization
+  p3: 'convoke',     // Phase 3 — Convoke rename
+  enh: 'enhance',    // Enhance module
+  sp: 'convoke',     // Skill Portability — platform-level
+});
+
+/**
+ * Folder defaults for the portfolio engine. Mirrors the migration suggester:
+ * `planning-artifacts` is for cross-cutting convoke platform artifacts.
+ * Other dirs (`vortex-artifacts`, `implementation-artifacts`) are heterogeneous
+ * — no safe default, so they fall through to subsequent inference layers.
+ */
+const PORTFOLIO_FOLDER_DEFAULT_MAP = Object.freeze({
+  'planning-artifacts': 'convoke'
+});
+
+/**
+ * Attribute a file to an initiative when filename inference fails.
+ * Six-step priority chain (highest first):
+ *   1. frontmatter.title keyword scan          → 'frontmatter-title'
+ *   2. first 5 lines of content keyword scan   → 'content-fallback'
+ *   3. filename first-segment matches a real taxonomy initiative (e.g. `gyre-1-1-...`)
+ *      → 'filename-prefix'
+ *   4. parent directory name (e.g. `gyre-artifacts/`) → 'parent-dir'
+ *   5. story-key prefix mapping (e.g. `tf-2-10-...` → loom) → 'story-prefix'
+ *   6. folder default (e.g. `planning-artifacts/` → convoke) → 'folder-default'
+ *
+ * @param {Object} fileInfo - File descriptor with filename and dir
+ * @param {string} content - Already-loaded file content
+ * @param {Object|null} frontmatter - Parsed frontmatter or null
+ * @param {import('../types').TaxonomyConfig} taxonomy
+ * @returns {{initiative: string|null, source: string|null}}
+ */
+function attributeFile(fileInfo, content, frontmatter, taxonomy) {
+  // Step 1: Frontmatter title scan (highest priority)
+  if (frontmatter && typeof frontmatter.title === 'string' && frontmatter.title.length > 0) {
+    const match = _scanCorpus(frontmatter.title.toLowerCase(), taxonomy);
+    if (match) return { initiative: match, source: 'frontmatter-title' };
+  }
+
+  // Step 2: First-5-lines content scan
+  // Strip frontmatter before scanning so non-title fields (e.g. `tags: [gyre]`)
+  // don't false-trigger content-fallback. The migration suggester does the same.
+  if (content && content.length > 0) {
+    let body = content;
+    try {
+      const parsed = parseFrontmatter(content);
+      if (parsed && typeof parsed.content === 'string') {
+        body = parsed.content;
+      }
+    } catch {
+      // Frontmatter parse failed — fall back to raw content
+    }
+    const corpus = body.split('\n').slice(0, 5).join(' ').toLowerCase();
+    const match = _scanCorpus(corpus, taxonomy);
+    if (match) return { initiative: match, source: 'content-fallback' };
+  }
+
+  // Step 3: Filename first-segment matches a real taxonomy initiative.
+  // Catches patterns like `gyre-1-1-...`, `forge-epic-1-...`, `helm-prd.md`,
+  // and also single-word filenames like `gyre.md` (extension stripped first).
+  if (fileInfo.filename && taxonomy && taxonomy.initiatives) {
+    const platform = Array.isArray(taxonomy.initiatives.platform) ? taxonomy.initiatives.platform : [];
+    const user = Array.isArray(taxonomy.initiatives.user) ? taxonomy.initiatives.user : [];
+    const allInitiatives = new Set([...platform, ...user]);
+    const stem = fileInfo.filename.replace(/\.(md|yaml|yml)$/i, '');
+    const firstSegment = stem.split('-')[0].toLowerCase();
+    if (allInitiatives.has(firstSegment)) {
+      return { initiative: firstSegment, source: 'filename-prefix' };
+    }
+  }
+
+  // Step 4: Parent directory scan
+  // The dir is something like `gyre-artifacts` — split on dashes and check each
+  // segment against the taxonomy. We can't reuse `_scanCorpus` here because it
+  // uses a kebab-aware boundary class (`[a-z0-9-]`) that intentionally treats
+  // `gyre-artifacts` as a single token, which is correct for content scanning
+  // but wrong for directory naming where `-` IS the segment separator.
+  if (fileInfo.dir && taxonomy && taxonomy.initiatives) {
+    const platform = Array.isArray(taxonomy.initiatives.platform) ? taxonomy.initiatives.platform : [];
+    const user = Array.isArray(taxonomy.initiatives.user) ? taxonomy.initiatives.user : [];
+    const allInitiatives = new Set([...platform, ...user]);
+    const aliases = taxonomy.aliases || {};
+    const dirSegments = fileInfo.dir.toLowerCase().split('-');
+    for (const seg of dirSegments) {
+      if (allInitiatives.has(seg)) {
+        return { initiative: seg, source: 'parent-dir' };
+      }
+      if (aliases[seg]) {
+        return { initiative: aliases[seg], source: 'parent-dir' };
+      }
+    }
+  }
+
+  // Step 5: Story-key prefix mapping
+  // Match patterns like `tf-2-10-...`, `p3-epic-2-retrospective`, `ag-1-1-...`
+  // Take the first dash-separated segment of the filename stem and look it up in STORY_PREFIX_MAP.
+  if (fileInfo.filename) {
+    const stem = fileInfo.filename.replace(/\.(md|yaml|yml)$/i, '');
+    const firstSegment = stem.split('-')[0].toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(STORY_PREFIX_MAP, firstSegment)) {
+      return { initiative: STORY_PREFIX_MAP[firstSegment], source: 'story-prefix' };
+    }
+  }
+
+  // Step 6: Folder default — last resort for cross-cutting platform artifacts
+  // (e.g. `planning-artifacts/architecture.md` → convoke)
+  if (fileInfo.dir && Object.prototype.hasOwnProperty.call(PORTFOLIO_FOLDER_DEFAULT_MAP, fileInfo.dir)) {
+    const defaultInit = PORTFOLIO_FOLDER_DEFAULT_MAP[fileInfo.dir];
+    if (defaultInit) {
+      return { initiative: defaultInit, source: 'folder-default' };
+    }
+  }
+
+  return { initiative: null, source: null };
+}
+
+/**
+ * Produce a one-line reason explaining why a file could not be attributed.
+ *
+ * @param {Object} fileInfo - File descriptor
+ * @param {string} content - File content (may be empty if unreadable)
+ * @param {Object|null} _frontmatter - Frontmatter (reserved for future heuristics)
+ * @returns {string} Reason
+ */
+function explainUnattributed(fileInfo, content, _frontmatter) {
+  if (!content || content.length === 0) {
+    return 'unreadable or empty';
+  }
+  // Check whether the filename has a recognizable type prefix BEFORE checking content length —
+  // matches the spec's order so a 3-line file with no prefix returns the more actionable
+  // 'no type prefix' message rather than 'insufficient content'.
+  const hasTypePrefix = /^[a-z]+\d*-/.test(fileInfo.filename);
+  if (!hasTypePrefix) {
+    return 'no type prefix in filename';
+  }
+  const lineCount = content.split('\n').length;
+  if (lineCount < 5) {
+    return 'insufficient content for inference';
+  }
+  return 'no initiative signal in filename, frontmatter title, content, or parent directory';
+}
+
 /**
  * Create an empty InitiativeState for a given initiative.
  * @param {string} initiative - Initiative ID
@@ -73,60 +261,103 @@ async function generatePortfolio(projectRoot, options = {}) {
   const registry = new Map();
   let governed = 0;
   let ungoverned = 0;
-  let unattributed = 0;
+  let attributableButUngoverned = 0; // Story 6.3: counts files attributed via fallback layers
+  const unattributedFiles = []; // Story 6.3: track per-file reasons (replaces bare counter)
 
   const mdFiles = allFiles.filter(f => f.filename.endsWith('.md'));
 
   for (const file of mdFiles) {
 
-    const typeResult = inferArtifactType(file.filename, taxonomy);
-    const initResult = typeResult.type
-      ? inferInitiative(typeResult.remainder, taxonomy)
-      : { initiative: null, confidence: 'low', source: 'no-type', candidates: [] };
-
-    // Files with no resolved initiative cannot be attributed — skip
-    if (!initResult.initiative) {
-      unattributed++;
-      continue;
-    }
-
-    // Read frontmatter to classify governed vs ungoverned
+    // Read frontmatter FIRST — governed files have authoritative metadata
     let frontmatter = null;
     let content = '';
+    let readFailed = false;
     try {
       content = fs.readFileSync(file.fullPath, 'utf8');
       frontmatter = parseFrontmatter(content).data;
     } catch {
-      // Unreadable — treat as no frontmatter
+      // Unreadable — treat as no frontmatter and skip fallback attribution
+      // (otherwise filename-prefix/story-prefix could silently attribute a file we never read)
+      readFailed = true;
     }
 
-    // Governed = has frontmatter with matching initiative field
-    const isGoverned = !!(frontmatter && frontmatter.initiative && frontmatter.initiative === initResult.initiative);
-    if (isGoverned) {
+    // Strategy: frontmatter initiative is authoritative if present
+    let initiative, artifactType, isGoverned, typeResult;
+    let attributionSource = null; // Story 6.3: tracks which fallback layer provided the attribution
+
+    if (frontmatter && frontmatter.initiative && frontmatter.artifact_type) {
+      // Governed file — use frontmatter as source of truth
+      initiative = frontmatter.initiative;
+      artifactType = frontmatter.artifact_type;
+      isGoverned = true;
       governed++;
+      typeResult = { type: artifactType, hcPrefix: null, remainder: '', date: null, typeConfidence: 'high', typeSource: 'frontmatter' };
     } else {
-      ungoverned++;
+      // Ungoverned file — fall back to filename inference
+      typeResult = inferArtifactType(file.filename, taxonomy);
+      const initResult = typeResult.type
+        ? inferInitiative(typeResult.remainder, taxonomy)
+        : { initiative: null, confidence: 'low', source: 'no-type', candidates: [] };
+
+      if (initResult.initiative) {
+        initiative = initResult.initiative;
+        artifactType = typeResult.type;
+        isGoverned = false;
+        ungoverned++;
+      } else if (readFailed) {
+        // Don't attempt fallback attribution on a file we couldn't read —
+        // otherwise filename/story-prefix layers would silently produce a phantom attribution.
+        unattributedFiles.push({
+          filename: file.filename,
+          dir: file.dir,
+          reason: 'unreadable or empty'
+        });
+        continue;
+      } else {
+        // Story 6.3: try content-fallback layers before giving up
+        const fallback = attributeFile(file, content, frontmatter, taxonomy);
+        if (fallback.initiative) {
+          initiative = fallback.initiative;
+          // Type may not be inferable — synthetic 'unknown' so registry can still index it
+          artifactType = typeResult.type || 'unknown';
+          isGoverned = false;
+          ungoverned++;
+          attributableButUngoverned++;
+          attributionSource = fallback.source;
+        } else {
+          // Truly unattributed — record reason for the diagnostic section
+          unattributedFiles.push({
+            filename: file.filename,
+            dir: file.dir,
+            reason: explainUnattributed(file, content, frontmatter)
+          });
+          continue;
+        }
+      }
     }
 
     const enriched = {
       filename: file.filename,
       dir: file.dir,
       fullPath: file.fullPath,
-      type: typeResult.type,
+      type: artifactType,
       hcPrefix: typeResult.hcPrefix,
       date: typeResult.date,
-      initiative: initResult.initiative,
+      initiative,
       frontmatter,
       content,
       isGoverned,
-      degradedMode: !isGoverned
+      degradedMode: !isGoverned,
+      // Story 6.3: 'frontmatter-title' | 'content-fallback' | 'filename-prefix' | 'parent-dir' | 'story-prefix' | 'folder-default' | null
+      attributionSource
     };
 
-    if (!registry.has(initResult.initiative)) {
-      registry.set(initResult.initiative, []);
+    if (!registry.has(initiative)) {
+      registry.set(initiative, []);
     }
-    registry.get(initResult.initiative).push(enriched);
+    registry.get(initiative).push(enriched);
   }
+  const unattributed = unattributedFiles.length;
 
   // FR39: warn if no governed artifacts
   if (governed === 0 && mdFiles.length > 0) {
@@ -180,11 +411,13 @@ async function generatePortfolio(projectRoot, options = {}) {
   return {
     initiatives: results,
     wipRadar,
+    unattributedFiles, // Story 6.3: full list with reasons (for --show-unattributed)
     summary: {
       total: mdFiles.length,
       governed,
       ungoverned,
       unattributed,
+      attributableButUngoverned, // Story 6.3: count of files attributed via fallback layers
       healthScore: { governed, total: attributable, percentage: healthPercentage }
     }
   };
@@ -199,17 +432,19 @@ Usage: convoke-portfolio [options]
 Generate a portfolio view of all initiatives from artifact analysis.
 
 Options:
-  --terminal        Terminal table output (default)
-  --markdown        Markdown table output
-  --sort <mode>     Sort: alpha (default), last-activity
-  --filter <prefix> Filter initiatives by prefix (e.g., --filter gyre)
-  --verbose         Show inference trace per initiative (source + confidence)
-  --help, -h        Show this help
+  --terminal           Terminal table output (default)
+  --markdown           Markdown table output
+  --sort <mode>        Sort: alpha (default), last-activity
+  --filter <prefix>    Filter initiatives by prefix (e.g., --filter gyre)
+  --verbose            Show inference trace per initiative (source + confidence)
+  --show-unattributed  List each unattributed file with its reason
+  --help, -h           Show this help
 
 Examples:
-  convoke-portfolio                      Default terminal view
-  convoke-portfolio --markdown           Markdown output for chat/docs
-  convoke-portfolio --sort last-activity Sort by most recent activity
+  convoke-portfolio                       Default terminal view
+  convoke-portfolio --markdown            Markdown output for chat/docs
+  convoke-portfolio --sort last-activity  Sort by most recent activity
+  convoke-portfolio --show-unattributed   See why each unattributed file was skipped
 `);
 }
 
@@ -229,6 +464,7 @@ async function main() {
 
   const useMarkdown = args.includes('--markdown');
   const useVerbose = args.includes('--verbose');
+  const showUnattributed = args.includes('--show-unattributed');
   const sortMode = args.includes('--sort') && args[args.indexOf('--sort') + 1] === 'last-activity'
     ? 'last-activity'
     : 'alpha';
@@ -280,6 +516,29 @@ async function main() {
     const hs = result.summary.healthScore;
     console.log(`Governance: ${hs.governed}/${hs.total} artifacts governed (${hs.percentage}%)`);
 
+    // Story 6.3: Surface attributable-but-ungoverned guidance
+    if (result.summary.attributableButUngoverned > 0) {
+      console.log(
+        `${result.summary.attributableButUngoverned} files attributable to existing initiatives ` +
+        `but ungoverned — run convoke-migrate-artifacts to govern them`
+      );
+    }
+
+    // Story 6.3: Unattributed details
+    if (result.unattributedFiles && result.unattributedFiles.length > 0) {
+      if (showUnattributed) {
+        console.log(`\n--- Unattributed Files (${result.unattributedFiles.length}) ---`);
+        for (const u of result.unattributedFiles) {
+          console.log(`  ${u.dir}/${u.filename}: ${u.reason}`);
+        }
+      } else {
+        console.log(
+          `\n${result.unattributedFiles.length} unattributed files ` +
+          `(run with --show-unattributed to see details)`
+        );
+      }
+    }
+
     // Verbose: inference trace per initiative
     if (useVerbose) {
       console.log('\n--- Inference Trace ---');
@@ -302,4 +561,12 @@ if (require.main === module) {
   });
 }
 
-module.exports = { generatePortfolio, makeEmptyState, EXCLUDE_DIRS };
+module.exports = {
+  generatePortfolio,
+  makeEmptyState,
+  attributeFile,
+  explainUnattributed,
+  EXCLUDE_DIRS,
+  STORY_PREFIX_MAP,
+  PORTFOLIO_FOLDER_DEFAULT_MAP
+};

package/scripts/lib/portfolio/rules/artifact-chain-rule.js

@@ -90,11 +90,41 @@ function applyArtifactChainRule(state, artifacts, _options = {}) {
     return state;
   }
 
-  // No recognized pattern
-  state.phase = { value: 'unknown', source: 'artifact-chain', confidence: 'inferred' };
+  // No recognized pattern — collect evidence so the operator can see WHY it's unknown (Story 6.3)
+  const evidence = collectPhaseEvidence(artifacts, types, hcPrefixes);
+  state.phase = { value: 'unknown', source: 'artifact-chain', confidence: 'inferred', evidence };
   return state;
 }
 
+/**
+ * Collect a one-line description of what the phase inference looked at when it
+ * couldn't determine a phase. Used to populate the Next Action with context
+ * instead of the generic "Create PRD or brief" message.
+ *
+ * @param {Array<Object>} artifacts - All artifacts for this initiative
+ * @param {Set<string>} types - Distinct artifact types present
+ * @param {Set<string>} hcPrefixes - HC prefixes present (e.g. 'hc1', 'hc2')
+ * @returns {string[]} Evidence list, e.g. ["3 artifacts found", "no PRD/brief", "no HC chain", ...]
+ */
+function collectPhaseEvidence(artifacts, types, hcPrefixes) {
+  const evidence = [];
+  const count = artifacts.length;
+  evidence.push(count === 1 ? '1 artifact found' : `${count} artifacts found`);
+
+  // Special-case: only HC1 present (incomplete discovery, doesn't trigger discovery branch)
+  if (hcPrefixes.size === 1 && hcPrefixes.has('hc1')) {
+    evidence.push('incomplete HC chain (needs HC2-HC6)');
+    return evidence;
+  }
+
+  if (!types.has('prd') && !types.has('brief')) evidence.push('no PRD/brief');
+  if (!types.has('arch')) evidence.push('no architecture');
+  if (hcPrefixes.size === 0) evidence.push('no HC chain');
+  if (!types.has('epic')) evidence.push('no epic');
+
+  return evidence;
+}
+
 /**
  * Check if epic content indicates completion via flexible markers.
  * @param {string} content - Epic file content
@@ -123,4 +153,4 @@ function detectHCChain(state, hcPrefixes) {
   }
 }
 
-module.exports = { applyArtifactChainRule, isEpicDone, detectHCChain, DONE_PATTERNS };
+module.exports = { applyArtifactChainRule, isEpicDone, detectHCChain, collectPhaseEvidence, DONE_PATTERNS };

package/scripts/lib/portfolio/rules/conflict-resolver.js

@@ -32,6 +32,28 @@ function applyConflictResolver(state, artifacts, _options = {}) {
     state.lastArtifact = { file: last.filename, date: last.date || 'unknown' };
   }
 
+  // Story 6.3: If phase is unknown AND a recognized-type artifact exists AND we have evidence,
+  // surface a context-aware next action instead of the generic "Create PRD or brief".
+  // - Initiatives with zero artifacts still get the generic message (legitimate use case).
+  // - Initiatives whose ONLY artifacts are fallback-attributed (synthetic 'unknown' type)
+  //   also get the generic message — those don't reflect a real phase signal worth elaborating on.
+  // This guards against the design-intent inversion caught in code review:
+  // a single fallback-attributed note shouldn't override "Create PRD or brief".
+  const hasRecognizedArtifact = artifacts.some(a => a && a.type && a.type !== 'unknown');
+  if (
+    state.phase.value === 'unknown' &&
+    Array.isArray(state.phase.evidence) &&
+    state.phase.evidence.length > 0 &&
+    hasRecognizedArtifact
+  ) {
+    const summary = state.phase.evidence.slice(0, 2).join(', ');
+    state.nextAction = {
+      value: `Unknown phase: ${summary}`,
+      source: 'conflict-resolver'
+    };
+    return state;
+  }
+
   // Derive nextAction from phase if not already set by chain-gap analysis
   if (!state.nextAction.value) {
     state.nextAction = deriveNextAction(state);

package/scripts/migrate-artifacts.js

@@ -23,6 +23,7 @@ const {
   verifyHistoryChain,
   executeInjections,
   resolveAmbiguous,
+  loadResolutionMap,
   detectMigrationState,
   generateGovernanceADR,
   supersedePreviousADR
@@ -39,7 +40,7 @@ const VALID_DIR_PATTERN = /^[a-zA-Z0-9_-]+$/;
  * Parse CLI arguments from argv array.
  *
  * @param {string[]} argv - Arguments (typically process.argv.slice(2))
- * @returns {{help: boolean, includeDirs: string[], apply: boolean, force: boolean, verbose: boolean}}
+ * @returns {{help: boolean, includeDirs: string[], apply: boolean, force: boolean, verbose: boolean, resolutionFile: string|null, resolutionFileError: string|null}}
  */
 function parseArgs(argv) {
   const help = argv.includes('--help') || argv.includes('-h');
@@ -66,7 +67,37 @@ function parseArgs(argv) {
     }
   }
 
-  return { help, includeDirs, apply, force, verbose };
+  // Story 6.4: --resolution-file <path> — operator decisions for AMBIGUOUS entries.
+  // Loaded and validated in main() after the manifest is generated.
+  // Also accept the GNU --resolution-file=path form. Reject missing/empty/flag-like
+  // values loudly via parse error so operators don't accidentally run a destructive
+  // --apply --force without their overrides being honored.
+  let resolutionFile = null;
+  let resolutionFileError = null;
+
+  // Check the equals form first: --resolution-file=path
+  const eqArg = argv.find(a => a.startsWith('--resolution-file='));
+  if (eqArg) {
+    const value = eqArg.slice('--resolution-file='.length);
+    if (!value || value.startsWith('-')) {
+      resolutionFileError = `--resolution-file requires a non-empty path (got: '${value}')`;
+    } else {
+      resolutionFile = value;
+    }
+  } else {
+    const resolutionIdx = argv.indexOf('--resolution-file');
+    if (resolutionIdx !== -1) {
+      const nextArg = argv[resolutionIdx + 1];
+      // Reject: missing arg, empty arg, anything starting with `-` (covers --flags AND -singledash)
+      if (!nextArg || nextArg.startsWith('-')) {
+        resolutionFileError = `--resolution-file requires a path argument (got: '${nextArg || '<missing>'}')`;
+      } else {
+        resolutionFile = nextArg;
+      }
+    }
+  }
+
+  return { help, includeDirs, apply, force, verbose, resolutionFile, resolutionFileError };
 }
 
 // --- Help ---
@@ -79,17 +110,21 @@ Analyze artifact files and show what the governance migration would do.
 Dry-run by default — no files are modified.
 
 Options:
-  --include <dirs>  Comma-separated directory names to scan (relative to _bmad-output/)
-                    Default: planning-artifacts,vortex-artifacts,gyre-artifacts
-  --verbose         Show cross-references for ambiguous files
-  --apply           Execute the rename migration (commit 1: git mv)
-  --force           Bypass confirmation prompt (use with --apply for automation)
-  --help, -h        Show this help
+  --include <dirs>           Comma-separated directory names to scan (relative to _bmad-output/)
+                             Default: planning-artifacts,vortex-artifacts,gyre-artifacts
+  --verbose                  Show cross-references for ambiguous files
+  --apply                    Execute the rename migration (commit 1: git mv)
+  --force                    Bypass confirmation prompt (use with --apply for automation)
+  --resolution-file <path>   JSON file with operator decisions for ambiguous entries.
+                             Combined with --force gives a fully non-interactive run.
+                             Schema: { "schemaVersion": 1, "resolutions": { "dir/file.md": { "action": "rename", "initiative": "convoke" } } }
+  --help, -h                 Show this help
 
 Examples:
   convoke-migrate-artifacts                          Dry-run with default scope
   convoke-migrate-artifacts --verbose                Dry-run with cross-references
   convoke-migrate-artifacts --include planning-artifacts   Dry-run for one directory
+  convoke-migrate-artifacts --apply --force --resolution-file resolutions.json   Non-interactive apply with operator decisions
 `);
 }
 
@@ -172,6 +207,13 @@ async function main() {
     return;
   }
 
+  // Story 6.4: fail fast on a malformed --resolution-file flag so a typo can't
+  // silently turn into a destructive --apply --force run with no overrides applied.
+  if (args.resolutionFileError) {
+    console.error(`Error: ${args.resolutionFileError}`);
+    process.exit(1);
+  }
+
   if (args.force && !args.apply) {
     console.log('Warning: --force has no effect without --apply. Running dry-run instead.');
   }
@@ -247,8 +289,25 @@ async function main() {
   // Load taxonomy for ambiguous resolution
   const taxonomy = readTaxonomy(projectRoot);
 
-  // Resolve ambiguous files interactively (or auto-skip in --force mode)
-  const resolution = await resolveAmbiguous(manifest, taxonomy, projectRoot, { force: args.force });
+  // Story 6.4: optional pre-loaded operator resolutions via --resolution-file.
+  // Loaded once here so any validation error fails fast before we touch the manifest.
+  let resolutionMap = null;
+  if (args.resolutionFile) {
+    try {
+      resolutionMap = loadResolutionMap(args.resolutionFile, taxonomy);
+      const count = Object.keys(resolutionMap).length;
+      console.log(`Loaded ${count} operator resolution(s) from ${args.resolutionFile}.`);
+    } catch (err) {
+      console.error(`Error loading resolution file: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Resolve ambiguous files: resolution map (if any) → no-candidates skip → force skip → interactive prompt
+  const resolution = await resolveAmbiguous(manifest, taxonomy, projectRoot, {
+    force: args.force,
+    resolutionMap
+  });
   if (resolution.resolved > 0 || resolution.skipped > 0) {
     console.log(`\nAmbiguous resolution: ${resolution.resolved} resolved, ${resolution.skipped} skipped.`);
   }