@longph2102/v-flow 1.5.0

package/cli/commands/log.js

@@ -0,0 +1,199 @@
+const fs = require('fs');
+const chalk = require('chalk');
+const { withErrorHandler, ValidationError } = require('../lib/cli-error');
+const activityLog = require('../lib/activity-log');
+
+/**
+ * `v-flow log` — append a structured activity entry, or view recent ones.
+ *
+ * Used by the agentic workflow (see AGENTS.md "Activity Logging") to record
+ * phase boundaries and key decisions into the same .v-flow/logs/ files the CLI
+ * writes to, giving one unified audit trail of "using v-flow".
+ */
+module.exports = function (program) {
+  program
+    .command('log')
+    .description('Record a structured activity entry (agents) or view recent ones (--tail)')
+    .argument('[message...]', 'Free-form log message')
+    .option('--type <type>', 'Entry type (agent, note, ...)', 'agent')
+    .option('--phase <phase>', 'V-Flow phase, e.g. S.1, B.1')
+    .option('--feature <feature>', 'Feature name')
+    .option('--actor <actor>', 'Who/what produced this, e.g. ba-agent')
+    .option('--event <event>', 'Event kind: start | end | decision | error | info')
+    .option('--level <level>', 'Severity: info | warn | error', 'info')
+    .option('--data <json>', 'Extra structured fields as a JSON object')
+    .option('--tail [n]', 'Show the last N entries instead of writing (default 20)')
+    .option(
+      '--hook <provider>',
+      'Run as a lifecycle hook (claude|cursor|copilot|codex|antigravity): read the hook payload from stdin and log it'
+    )
+    .action(
+      withErrorHandler((message, options) => {
+        // ── Hook mode ── (invoked by an AI tool's lifecycle hook; reads stdin)
+        if (options.hook) {
+          runHookMode(options.hook, options);
+          return;
+        }
+
+        // ── Read mode ──
+        if (options.tail !== undefined) {
+          const n = options.tail === true ? 20 : parseInt(options.tail, 10) || 20;
+          printTail(n);
+          return;
+        }
+
+        // ── Write mode ──
+        let extra = {};
+        if (options.data) {
+          try {
+            extra = JSON.parse(options.data);
+          } catch (_) {
+            throw new ValidationError('--data must be a valid JSON object', 'Example: --data \'{"req":"REQ-1"}\'');
+          }
+        }
+
+        const msg = (message || []).join(' ').trim();
+        const entry = {
+          type: options.type,
+          level: options.level,
+          ...(options.event ? { event: options.event } : {}),
+          ...(options.phase ? { phase: options.phase } : {}),
+          ...(options.feature ? { feature: options.feature } : {}),
+          ...(options.actor ? { actor: options.actor } : {}),
+          ...(msg ? { message: msg } : {}),
+          ...extra,
+        };
+
+        if (!msg && !options.event && Object.keys(extra).length === 0) {
+          throw new ValidationError(
+            'Nothing to log',
+            'Provide a message, --event, or --data. Use --tail to view entries.'
+          );
+        }
+
+        activityLog.event(entry, humanSuffix(entry));
+
+        const dir = activityLog.resolveLogDir();
+        if (dir) {
+          console.log(chalk.dim(`📝 logged → ${dir}/activity.jsonl`));
+        } else {
+          console.log(chalk.yellow('⚠️  No .v-flow/ here — entry not persisted (run from a v-flow project or set VFLOW_LOG_DIR)'));
+        }
+      })
+    );
+};
+
+function humanSuffix(e) {
+  const scope = [e.phase, e.feature].filter(Boolean).join('/');
+  const actor = e.actor ? ` (${e.actor})` : '';
+  const head = `[${e.type}]${scope ? ` ${scope}` : ''}${e.event ? ` ${e.event}` : ''}${actor}`;
+  return e.message ? `${head}: ${e.message}` : head;
+}
+
+function printTail(n) {
+  const entries = activityLog.tail(n);
+  if (entries.length === 0) {
+    console.log(chalk.dim('No activity log entries yet.'));
+    return;
+  }
+  console.log(chalk.cyan.bold(`\n📜 Last ${entries.length} activity entries\n`));
+  for (const e of entries) {
+    if (e.raw) {
+      console.log(chalk.dim(e.raw));
+      continue;
+    }
+    const ts = chalk.dim(e.ts || '');
+    if (e.type === 'cli') {
+      const ok = e.exitCode === 0 ? chalk.green('✓') : chalk.red(`✗ ${e.exitCode}`);
+      console.log(`${ts}  ${ok} ${chalk.white(`v-flow ${(e.invocation || []).join(' ')}`)} ${chalk.dim(`(${e.durationMs}ms)`)}`);
+    } else if (e.type === 'hook') {
+      console.log(`${ts}  ${chalk.magenta(`[hook:${e.provider}]`)} ${chalk.white([e.event, e.tool].filter(Boolean).join(' '))}${e.command ? chalk.dim(` — ${e.command}`) : ''}`);
+    } else {
+      console.log(`${ts}  ${chalk.white(humanSuffix(e))}`);
+    }
+  }
+  console.log('');
+}
+
+// ── Hook mode helpers ──────────────────────────────────────────────────────
+
+/**
+ * Read the hook payload from stdin, normalize it across providers, and log it.
+ * MUST be defensive: never throw, always exit 0 — a logging hook must not block
+ * or alter the host agent's behavior.
+ */
+function runHookMode(provider, options) {
+  let raw = '';
+  try {
+    if (!process.stdin.isTTY) {
+      raw = fs.readFileSync(0, 'utf8');
+    }
+  } catch (_) {
+    /* no stdin available */
+  }
+
+  let payload = null;
+  try {
+    payload = raw ? JSON.parse(raw) : null;
+  } catch (_) {
+    payload = { _unparsed: raw.slice(0, 500) };
+  }
+
+  try {
+    const { fields, human } = normalizeHookPayload(provider, payload, options);
+    activityLog.event({ type: 'hook', provider, level: 'info', ...fields }, human);
+  } catch (_) {
+    /* logging must never break the host agent */
+  }
+
+  // Antigravity requires a top-level JSON allow response; others accept empty
+  // stdout + exit 0 as "continue".
+  if (provider === 'antigravity') {
+    process.stdout.write(JSON.stringify({ allow_tool: true }));
+  }
+}
+
+function pickField(obj, ...keys) {
+  for (const k of keys) {
+    if (obj && obj[k] !== undefined && obj[k] !== null) return obj[k];
+  }
+  return undefined;
+}
+
+function normalizeHookPayload(provider, payload, options) {
+  const p = payload || {};
+  const toolCallArgs = (p.toolCall && p.toolCall.args) || {};
+
+  const event = options.event || pickField(p, 'hook_event_name', 'hookEventName');
+  const tool = pickField(p, 'tool_name', 'toolName') || toolCallArgs.ToolName;
+  const sessionId = pickField(p, 'session_id', 'sessionId', 'conversation_id', 'generation_id');
+  const cwd = pickField(p, 'cwd');
+  const command = toolCallArgs.CommandLine || (p.tool_input && p.tool_input.command);
+  const status = pickField(p, 'status', 'stop_hook_active');
+
+  const fields = {
+    ...(event ? { event } : {}),
+    ...(tool ? { tool } : {}),
+    ...(sessionId ? { sessionId } : {}),
+    ...(cwd ? { cwd } : {}),
+    ...(command ? { command } : {}),
+    ...(status !== undefined ? { status } : {}),
+    ...(options.feature ? { feature: options.feature } : {}),
+    payload: capPayload(p),
+  };
+
+  const scope = [event, tool].filter(Boolean).join(' ');
+  const human = `[hook:${provider}] ${scope || 'event'}${command ? ` — ${command}` : ''}`;
+  return { fields, human };
+}
+
+/** Keep the log lean: drop huge tool outputs, keep a size marker instead. */
+function capPayload(p) {
+  try {
+    const s = JSON.stringify(p);
+    if (s.length > 4000) return { _truncated: true, _bytes: s.length };
+    return p;
+  } catch (_) {
+    return undefined;
+  }
+}

package/cli/commands/plugin.js

@@ -0,0 +1,230 @@
+/**
+ * v-flow plugin — Plugin management commands
+ *
+ * Subcommands:
+ *   v-flow plugin list          — List discovered plugins
+ *   v-flow plugin create <name> — Scaffold a new plugin
+ *   v-flow plugin install       — Install all plugin assets to agent targets
+ *   v-flow plugin validate      — Validate plugin manifests
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+const { isInitialized, getVFlowDir } = require('../lib/templates');
+const { withErrorHandler, requireInit, printOk, printWarn, printError, printDim } = require('../lib/cli-error');
+const { createT } = require('../lib/i18n');
+const {
+  discoverPlugins,
+  validateManifest,
+  loadPlugin,
+  installPlugin,
+  scaffoldPlugin,
+  VALID_TYPES,
+} = require('../lib/plugins');
+
+module.exports = function (program) {
+  const pluginCmd = program
+    .command('plugin')
+    .description('🔌 Plugin management — create, list, install, validate');
+
+  // ════════════════════════════════════════════════════════════
+  // v-flow plugin list
+  // ════════════════════════════════════════════════════════════
+  pluginCmd
+    .command('list')
+    .description('List discovered plugins')
+    .action(withErrorHandler(async () => {
+      const t = createT();
+      const projectRoot = process.cwd();
+      requireInit(projectRoot, isInitialized);
+
+      console.log(chalk.cyan.bold(`\n${t('plugin.title')}\n`));
+
+      const plugins = await discoverPlugins(projectRoot);
+
+      if (plugins.length === 0) {
+        console.log(chalk.dim(`   ${t('plugin.no_plugins')}`));
+        console.log(chalk.dim(`   ${t('plugin.create_hint')}\n`));
+        return;
+      }
+
+      console.log(chalk.white.bold(`   Found ${plugins.length} plugin(s):\n`));
+
+      for (const plugin of plugins) {
+        const typeColor = {
+          agent: chalk.blue,
+          workflow: chalk.green,
+          skill: chalk.yellow,
+          composite: chalk.magenta,
+        }[plugin.type] || chalk.white;
+
+        console.log(`   📦 ${chalk.bold(plugin.name)} ${chalk.dim(`v${plugin.version}`)} ${typeColor(`[${plugin.type}]`)}`);
+        if (plugin.description) {
+          console.log(chalk.dim(`      ${plugin.description}`));
+        }
+      }
+      console.log('');
+    }));
+
+  // ════════════════════════════════════════════════════════════
+  // v-flow plugin create <name>
+  // ════════════════════════════════════════════════════════════
+  pluginCmd
+    .command('create')
+    .description('Scaffold a new plugin')
+    .argument('<name>', 'Plugin name (kebab-case)')
+    .option('--type <type>', `Plugin type: ${VALID_TYPES.join(', ')}`, 'composite')
+    .action(withErrorHandler(async (name, options) => {
+      const t = createT();
+      const projectRoot = process.cwd();
+      requireInit(projectRoot, isInitialized);
+
+      if (!VALID_TYPES.includes(options.type)) {
+        throw new (require('../lib/cli-error').ValidationError)(
+          `Invalid plugin type: ${options.type}`,
+          `Valid types: ${VALID_TYPES.join(', ')}`
+        );
+      }
+
+      console.log(chalk.cyan.bold(`\n${t('plugin.create_title')}\n`));
+
+      const pluginDir = await scaffoldPlugin(projectRoot, name, options.type);
+
+      printOk(`Plugin created: .v-flow/plugins/${name}/`);
+      printOk(`Type: ${options.type}`);
+      console.log('');
+      console.log(chalk.white.bold('   📁 Created files:'));
+      printDim(`plugin.json — manifest`);
+
+      if (options.type === 'agent' || options.type === 'composite') {
+        printDim(`agent.md — agent definition`);
+      }
+      if (options.type === 'workflow' || options.type === 'composite') {
+        printDim(`workflow.md — slash command`);
+      }
+      if (options.type === 'skill' || options.type === 'composite') {
+        printDim(`skill/SKILL.md — skill definition`);
+        printDim(`skill/config.json — skill config`);
+        printDim(`skill/gotchas.md — common gotchas`);
+      }
+
+      console.log('');
+      console.log(chalk.white.bold('   💡 Next steps:'));
+      printDim(`1. Edit files in .v-flow/plugins/${name}/`);
+      printDim(`2. Run: v-flow plugin install`);
+      console.log('');
+    }));
+
+  // ════════════════════════════════════════════════════════════
+  // v-flow plugin install
+  // ════════════════════════════════════════════════════════════
+  pluginCmd
+    .command('install')
+    .description('Install all plugin assets to agent targets')
+    .option('--dry-run', 'Preview without making changes')
+    .action(withErrorHandler(async (options) => {
+      const t = createT();
+      const projectRoot = process.cwd();
+      requireInit(projectRoot, isInitialized);
+
+      console.log(chalk.cyan.bold(`\n${t('plugin.install_title')}\n`));
+
+      const plugins = await discoverPlugins(projectRoot);
+
+      if (plugins.length === 0) {
+        console.log(chalk.dim('   No plugins to install.\n'));
+        return;
+      }
+
+      let totalInstalled = 0;
+      let totalSkipped = 0;
+
+      for (const plugin of plugins) {
+        console.log(chalk.white.bold(`   📦 ${plugin.name} v${plugin.version}:`));
+
+        const loaded = await loadPlugin(plugin);
+        const stats = await installPlugin(projectRoot, loaded, {
+          dryRun: options.dryRun,
+        });
+
+        if (loaded.agents.length > 0) {
+          printOk(`${loaded.agents.length} agent(s) → .agents/agents/ & .github/agents/`);
+        }
+        if (loaded.workflows.length > 0) {
+          printOk(`${loaded.workflows.length} workflow(s) → .agents/workflows/ & .github/prompts/`);
+        }
+        if (loaded.skills.length > 0) {
+          printOk(`${loaded.skills.length} skill(s) → .agents/skills/plugins/ & .github/skills/plugins/`);
+        }
+
+        totalInstalled += stats.installed;
+        totalSkipped += stats.skipped;
+        console.log('');
+      }
+
+      if (options.dryRun) {
+        console.log(chalk.yellow(`   🔍 Dry run — ${totalInstalled} asset(s) would be installed\n`));
+      } else {
+        console.log(chalk.green(`   ✅ Installed ${totalInstalled} asset(s) from ${plugins.length} plugin(s)\n`));
+      }
+    }));
+
+  // ════════════════════════════════════════════════════════════
+  // v-flow plugin validate
+  // ════════════════════════════════════════════════════════════
+  pluginCmd
+    .command('validate')
+    .description('Validate all plugin manifests')
+    .action(withErrorHandler(async () => {
+      const t = createT();
+      const projectRoot = process.cwd();
+      requireInit(projectRoot, isInitialized);
+
+      console.log(chalk.cyan.bold(`\n${t('plugin.validate_title')}\n`));
+
+      const fs = require('fs-extra');
+      const pluginsDir = path.join(projectRoot, '.v-flow', 'plugins');
+      if (!fs.existsSync(pluginsDir)) {
+        console.log(chalk.dim('   No plugins directory found.\n'));
+        return;
+      }
+
+      const entries = await fs.readdir(pluginsDir, { withFileTypes: true });
+      let valid = 0;
+      let invalid = 0;
+
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+
+        const manifestPath = path.join(pluginsDir, entry.name, 'plugin.json');
+        if (!fs.existsSync(manifestPath)) {
+          printError(`${entry.name}: missing plugin.json`);
+          invalid++;
+          continue;
+        }
+
+        try {
+          const manifest = await fs.readJson(manifestPath);
+          const result = validateManifest(manifest);
+
+          if (result.valid) {
+            printOk(`${manifest.name} v${manifest.version} [${manifest.type}]`);
+            valid++;
+          } else {
+            printError(`${entry.name}: ${result.errors.join(', ')}`);
+            invalid++;
+          }
+        } catch (err) {
+          printError(`${entry.name}: invalid JSON — ${err.message}`);
+          invalid++;
+        }
+      }
+
+      console.log('');
+      if (invalid === 0) {
+        console.log(chalk.green(`   ✅ All ${valid} plugin(s) valid\n`));
+      } else {
+        console.log(chalk.yellow(`   ${valid} valid, ${invalid} invalid\n`));
+      }
+    }));
+};

package/cli/commands/score-card.js

@@ -0,0 +1,203 @@
+/**
+ * v-flow score-card — Objective scoring for module cards (Decision 3).
+ *
+ * Emits a re-runnable scorecard: the objective half (6 pts) is computed from
+ * machine-checkable facts via a KnowledgeOracle, with an evidence trail. The
+ * subjective half (business/dev correctness, depth — 4 pts) needs human + AI
+ * graders and is intentionally NOT produced here.
+ *
+ * Usage:
+ *   v-flow score-card [module]            # one card, or all if omitted
+ *   v-flow score-card orders --json       # machine-readable scorecard.json
+ *   v-flow score-card --oracle none       # declared-only mode (no verification)
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const { isInitialized, getVFlowDir } = require('../lib/templates');
+const { withErrorHandler, requireInit, printWarn } = require('../lib/cli-error');
+const { getOracle } = require('../lib/knowledge-oracle');
+const { scoreModuleCard } = require('../lib/module-card-score');
+
+const DIM_LABEL = {
+  structural: 'Structural completeness',
+  grounded: 'Evidence-grounded',
+  freshness: 'Freshness / no-drift',
+  coverage: 'Coverage',
+};
+
+function evidenceLine(dim) {
+  const e = dim.evidence || {};
+  switch (dim.key) {
+    case 'structural':
+      return `${e.issues} issue · ${e.warnings} warning`;
+    case 'grounded':
+      return dim.verified
+        ? `${e.refs_resolved}/${e.refs_total} ref resolve${  e.broken && e.broken.length ? ` · gãy: ${e.broken.length}` : ''}`
+        : e.reason;
+    case 'freshness':
+      return dim.verified
+        ? `${e.files_checked} file kiểm · drift: ${e.drifted ? e.drifted.length : 0}${  e.last_verified ? ` (từ ${e.last_verified})` : ''}`
+        : e.reason;
+    case 'coverage':
+      return dim.verified ? `${e.symbols_mentioned}/${e.symbols_total} symbol` : e.reason;
+    default:
+      return '';
+  }
+}
+
+// Turn a scorecard into concrete remediation steps — the "what do I do now"
+// the bare numbers don't answer. Only emits for dimensions below their max;
+// each line names the dimension, its score, and the exact fix.
+function nextSteps(sc) {
+  const steps = [];
+  for (const dim of sc.dimensions) {
+    if (dim.verified && dim.score >= dim.max) continue; // chiều này đã trọn điểm
+    const e = dim.evidence || {};
+    const at = `(${dim.score}/${dim.max})`;
+    switch (dim.key) {
+      case 'structural':
+        if (e.issues > 0 || e.warnings > 0) {
+          steps.push(`Cấu trúc ${at}: chạy \`v-flow validate --module-cards ${sc.module}\` để xem ${e.issues} issue + ${e.warnings} warning cụ thể, rồi bổ sung file/heading còn thiếu.`);
+        }
+        break;
+      case 'grounded':
+        if (e.broken && e.broken.length) {
+          steps.push(`Bằng chứng ${at}: sửa ${e.broken.length} ref code gãy — vd: ${e.broken[0]}`);
+        } else if (!dim.verified && e.refs_total === 0) {
+          steps.push(`Bằng chứng ${at}: card chưa neo về code — thêm refs dạng  Source: \`đường-dẫn/file.ext:dòng\`, hàm \`tên\`  vào card.`);
+        } else if (!dim.verified) {
+          steps.push(`Bằng chứng ${at}: ${e.reason || 'oracle chưa kiểm được'}.`);
+        }
+        break;
+      case 'freshness':
+        if (e.drifted && e.drifted.length) {
+          steps.push(`Độ mới ${at}: ${e.drifted.length} file đã đổi sau ${e.last_verified} — review & cập nhật card rồi bump **Last verified** (vd: ${e.drifted[0]}).`);
+        } else if (!dim.verified && /Last verified/i.test(e.reason || '')) {
+          steps.push(`Độ mới ${at}: thêm \`**Last verified**: YYYY-MM-DD\` vào SKILL.md để bật kiểm drift.`);
+        } else if (!dim.verified) {
+          steps.push(`Độ mới ${at}: ${e.reason || 'chưa kiểm được'}.`);
+        }
+        break;
+      case 'coverage':
+        if (!dim.verified) {
+          const r = e.reason || '';
+          if (/cypher error/i.test(r)) {
+            steps.push(`Coverage ${at}: "cypher error" là do GitNexus index/CLI (KHÔNG phải lỗi card). Chạy \`npx gitnexus analyze\` cho repo rồi thử lại; nếu vẫn lỗi, tạm bỏ qua chiều này.`);
+          } else if (/full-graph/i.test(r)) {
+            steps.push(`Coverage ${at}: cần full-graph — chạy lại với \`--oracle gitnexus\` sau khi \`npx gitnexus analyze\`.`);
+          } else if (/no scope|code refs/i.test(r)) {
+            steps.push(`Coverage ${at}: card chưa có ref code nên không xác định được phạm vi — thêm \`Source:\` refs trước (xem mục Bằng chứng).`);
+          } else {
+            steps.push(`Coverage ${at}: ${r || 'chưa kiểm được'}.`);
+          }
+        } else if (dim.score < dim.max) {
+          steps.push(`Coverage ${at}: card mới nhắc ${e.symbols_mentioned}/${e.symbols_total} symbol — bổ sung các symbol quan trọng còn thiếu.`);
+        }
+        break;
+    }
+  }
+  return steps;
+}
+
+function printNextSteps(sc) {
+  const steps = nextSteps(sc);
+  if (steps.length === 0) {
+    console.log(chalk.green('      👉 Đã trọn điểm objective — chuyển sang chấm subjective (business/dev/depth) với human + AI.'));
+    return;
+  }
+  console.log(chalk.white.bold('      👉 Cần làm gì tiếp:'));
+  steps.forEach((s, i) => console.log(chalk.dim(`         ${i + 1}. `) + chalk.white(s)));
+}
+
+function printScorecard(sc) {
+  const stamp = sc.stamp ? chalk.yellow(sc.stamp) : '';
+  console.log(chalk.white.bold(`\n   📦 ${sc.module}`));
+  console.log(
+    chalk.cyan.bold(`   Objective: ${sc.objective_total}/${sc.objective_max}${stamp}`) +
+      chalk.dim(`  (oracle: ${sc.oracle}${sc.fully_verified ? '' : ' — có chiều chưa kiểm chứng'})`)
+  );
+  for (const dim of sc.dimensions) {
+    const icon = dim.verified ? '✅' : '⚠️ ';
+    const label = DIM_LABEL[dim.key] || dim.key;
+    const verifiedTag = dim.verified ? '' : chalk.yellow(' [unverified]');
+    console.log(
+      `      ${icon} ${chalk.white(label.padEnd(24))} ${chalk.bold(`${dim.score}/${dim.max}`)}${verifiedTag} ${ 
+        chalk.dim(`— ${evidenceLine(dim)}`)}`
+    );
+  }
+}
+
+module.exports = function (program) {
+  program
+    .command('score-card [module]')
+    .description('Chấm điểm objective cho module card (.v-flow/modules/) — provable, có evidence trail')
+    .option('--json', 'Xuất scorecard dạng JSON (machine-readable)')
+    .option('--oracle <mode>', 'Oracle: lightweight | gitnexus (full-graph) | none (declared-only)', 'lightweight')
+    .option('--repo <name>', 'Tên repo GitNexus (khi --oracle gitnexus, nếu cần chỉ định)')
+    .action(
+      withErrorHandler(async (moduleName, options) => {
+        const projectRoot = process.cwd();
+        requireInit(projectRoot, isInitialized);
+
+        if (!['lightweight', 'gitnexus', 'none'].includes(options.oracle)) {
+          printWarn(`--oracle "${options.oracle}" không hợp lệ → dùng "lightweight"`);
+          options.oracle = 'lightweight';
+        }
+
+        const modulesDir = path.join(getVFlowDir(projectRoot), 'modules');
+        const allCards = fs.existsSync(modulesDir)
+          ? (await fs.readdir(modulesDir, { withFileTypes: true }))
+              .filter((d) => d.isDirectory())
+              .map((d) => d.name)
+              .sort()
+          : [];
+
+        if (allCards.length === 0) {
+          if (options.json) {
+            console.log('[]');
+          } else {
+            console.log(chalk.dim('\n   Chưa có module card nào (.v-flow/modules/) — chạy /v.understand trước.\n'));
+          }
+          return;
+        }
+
+        const cards = moduleName
+          ? allCards.filter((c) => c === moduleName || c === `domain-${moduleName}`)
+          : allCards;
+
+        if (cards.length === 0) {
+          printWarn(`Không tìm thấy module card "${moduleName}". Có: ${allCards.join(', ')}`);
+          return;
+        }
+
+        const oracle = getOracle(options.oracle, projectRoot, { repo: options.repo });
+        const results = cards.map((card) => {
+          const cardPath = path.join(modulesDir, card);
+          const readFile = (f) => {
+            const p = path.join(cardPath, f);
+            return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+          };
+          return scoreModuleCard(card, readFile, oracle);
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify(results.length === 1 ? results[0] : results, null, 2));
+          return;
+        }
+
+        console.log(chalk.cyan.bold('\n🏅 V Flow — Module Card Scorecard (objective tier)'));
+        for (const sc of results) {
+          printScorecard(sc);
+          printNextSteps(sc);
+        }
+        console.log(
+          chalk.dim(
+            '\n   Chú thích: * = thiếu full-graph (coverage chưa kiểm) · † = declared-only (chưa máy nào kiểm).' +
+              '\n   Objective = chứng minh được; phần subjective (business/dev/depth, 4đ) do human + AI độc lập chấm.\n'
+          )
+        );
+      })
+    );
+};