peaks-loop 4.0.23 → 4.0.24

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 4.0.24 — 2026-08-12 (zod v4 + Context7 + Step 2.5 best-practice scan)
+
+**6 atomic commits from session 2026-08-12-session-4aaf2b** (5 functional + 1 sediment):
+
+- `545a7d15` feat(peaks-prd): auto-trigger best-practice-scan on prd → handed-off transition (Slice F, 3 files, +446/-13)
+- `3d866138` docs(peaks-code): wire Step 2.5 best-practice scan sub-step into workflow narrative (Slice D, 3 files, +48/-4)
+- `a0f3efc0` feat(peaks-code): add Step 2.5 best-practice scan core (Slice C, 8 files, +947/-1)
+- `a8f31b1b` chore(deps): add @upstash/context7-mcp@^4.0.2 for downstream best-practice docs (Slice B, 2 files, +490/-2)
+- `24dfd8da` refactor(zod): bump zod 3.25.76 → 4.4.3 across monorepo (Slice A, 21 files, +148/-132)
+- `f2fc76de` chore(memory): sediment pre-existing dirty — .peaks/PROJECT.md + .peaks/memory/index.json
+
+**Highlights**:
+
+1. **zod v3 → v4 upgrade** — 21 src files migrated, 4 v3 API families fixed (`.nonnegative/.positive`, `z.record` 1-arg, `errorMap`, `.refine()` path). Lockstep peaks-loop-shared + peaks-loop-internal-runtime bump. D-2 deviation (RD fabrication) caught by QA and fixed in same session — `zod-to-json-schema` replaced by zod v4 native `z.toJSONSchema()`.
+
+2. **`@upstash/context7-mcp@^4.0.2` added** as production dep — Context7's zod v4 peer dep is now satisfied. 8 transitive deps resolved (express/jose/undici/MCP packages). Downstream projects consuming peaks-loop now have Context7 transitively available.
+
+3. **peak-code Step 2.5 best-practice scan (BPS)** shipped — new sub-step between Step 2 (PRD) and Step 3 (RD). Auto-triggered on prd → handed-off transition. 8-row markdown table output with ★-marked LLM recommendation + mandatory ⚠️ catch-gate. 5-lang detector (TS/JS/Python/Go/Java). 53 vitest cases (44 core + 9 auto-trigger). 0 forbidden-token regressions. All 8 ACs PASS.
+
+**Lockstep contract** (per peaks-cli-version-shared-chicken-egg):
+- peaks-loop root `package.json#version`: 4.0.23 → **4.0.24**
+- peaks-loop-shared `src/version.ts` `CLI_VERSION`: 4.0.23 → **4.0.24**
+- peaks-loop-shared `package.json#version`: 0.0.57 → **0.0.58**
+- peaks-loop-internal-runtime `src/index.ts` `RUNTIME_VERSION`: 4.0.23 → **4.0.24**
+- peaks-loop-internal-runtime `src/index.ts` `RUNTIME_NPM_VERSION`: 0.0.8 → **0.0.9**
+- peaks-loop-internal-runtime `package.json#version`: 0.0.8 → **0.0.9**
+
+**Pre-publish registry state**:
+- `peaks-loop@4.0.23` ✓ on registry (current latest)
+- `peaks-loop@4.0.22` ✗ unpublished + in 24-72h grace (out of scope)
+- `peaks-loop-shared@0.0.57` ✓ on registry
+- `peaks-loop-internal-runtime@0.0.8` ✓ on registry
+
+**Sister subpackages NOT bumped** (out of Step 2.5 scope):
+- peaks-loop-mut: 0.1.22 (unchanged; only its zod dep was bumped in Slice A)
+- peaks-loop-shared-channel: 0.0.26 (unchanged)
+
+**Pending follow-ups** (out of 4.0.24 scope):
+- real MCP wiring for Context7 (replace v1 stubs in `src/services/best-practice/scan-orchestrator.ts`)
+- per-language libraries lookup (currently `...` in non-parallel rows)
+- `startup-sequence.md:100` legacy "Step 2.5: Set session title" → 2.5a rename (Slice D deviation #1)
+- 4 unit pre-existing failures unrelated to this release (verified against pre-migration main)
+
 ## 4.0.23 — 2026-08-11 (Bump to NEW version — per Rule 3 unpublish 24-72h grace)
 
 **1 atomic commits from session 2026-08-11** + Layer 3 fix verify (publish.yml no auto-bump):

package/dist/cli/commands/_register.js

@@ -4,6 +4,7 @@ import { registerAssetCommands } from './asset-commands.js';
 import { registerAuditCommands } from './audit-commands.js';
 import { registerBaselineCommands } from './baseline-commands.js';
 import { registerBeeCommands } from './bee-commands.js';
+import { registerBestPracticeScanCommand } from './best-practice-scan-command.js';
 import { registerCapabilityWorkerConfigAndSCCommands } from './capability-worker-config-sc-commands.js';
 import { registerCodeCommands } from './code-commands.js';
 import { registerCodeGateCommand } from './code-gate-command.js';
@@ -122,7 +123,7 @@ const REGISTRATIONS = [
     ['security-audit-commands', registerSecurityAuditCommands], ['perf-audit-commands', registerPerfAuditCommands],
     ['verdict-aggregate-command', registerVerdictAggregateCommands], ['log-commands', registerLogCommands],
     ['qa-commands', registerQaCommands], ['test-commands', registerTestCommands],
-    ['playwright-commands', registerPlaywrightCommands], ['code-commands', registerCodeCommands], ['code-gate-command', registerCodeGateCommand], ['dashboard-commands', registerDashboardCommands],
+    ['playwright-commands', registerPlaywrightCommands], ['code-commands', registerCodeCommands], ['code-gate-command', registerCodeGateCommand], ['dashboard-commands', registerDashboardCommands], ['best-practice-scan-command', registerBestPracticeScanCommand],
     ['mut-commands', registerMutCommands], ['fixture-commands', registerFixtureCommands],
     ['reviewer-commands', registerReviewerCommands], ['ide-commands', registerIdeCommands],
     ['observability-commands', registerObservabilityCommands], ['compact-command', registerCompactCommands],

package/dist/cli/commands/best-practice-scan-command.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Slice 2026-08-12 best-practice-scan — CLI subcommand.
+ *
+ * `peaks best-practice-scan --project <path> [--lang <lang>] [--commit]`
+ *
+ * Pipeline:
+ *   1. detect language via language-detector (or use --lang override)
+ *   2. scan via scan-orchestrator (Context7 → WebSearch → empty)
+ *   3. render 8-row table via output-formatter
+ *   4. write artifact into <projectRoot>/best-practice/<date>-<intent>.md
+ *      (gitignored directory by convention; --commit flag reserved for
+ *       a future slice that opts the artifact into git tracking)
+ *   5. print artifact path + the 8-row table to stdout
+ *
+ * Catch-gate (spec §7): the command emits a 3-line prompt asking the
+ * user to ack / pick alt / reject + reason. The gate is read from
+ * stdin via `PEAKS_BEST_PRACTICE_STDIN` (test seam) or the real stdin
+ * (production). The result is written to stdout as a JSON envelope
+ * suffix so the orchestrator can react programmatically.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type RecommendationChoice } from '../../services/best-practice/output-formatter.js';
+export type CatchGateOutcome = {
+    kind: 'accept';
+    choice: RecommendationChoice;
+} | {
+    kind: 'alternative';
+    choice: RecommendationChoice;
+    reason?: string;
+} | {
+    kind: 'reject';
+    reason: string;
+};
+export declare function parseCatchGateReply(raw: string, recommended: RecommendationChoice): CatchGateOutcome;
+export declare function registerBestPracticeScanCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/best-practice-scan-command.js

@@ -0,0 +1,118 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { detectLanguage } from '../../services/best-practice/language-detector.js';
+import { scanBestPractice } from '../../services/best-practice/scan-orchestrator.js';
+import { findForbiddenTokens, formatOutputTable } from '../../services/best-practice/output-formatter.js';
+const CATCH_GATE_PROMPT = [
+    '⚠️ 任何跟你真实业务不一样,改 — LLM 推荐可能错。',
+    '回应 (默认 = 接受): 接受 / 接受方案 A|接受方案 B|接受方案 C / 拒绝 + 原因'
+].join('\n');
+async function readUserInput() {
+    const override = process.env.PEAKS_BEST_PRACTICE_STDIN;
+    if (override !== undefined)
+        return override;
+    if (process.stdin.isTTY)
+        return '';
+    return new Promise((resolveStdin) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolveStdin(data.trim()));
+        process.stdin.on('error', () => resolveStdin(data.trim()));
+    });
+}
+export function parseCatchGateReply(raw, recommended) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return { kind: 'accept', choice: recommended };
+    }
+    const altMatch = /^接受方案\s*([ABC])(?:\s+(.+))?$/u.exec(trimmed);
+    if (altMatch !== null) {
+        const letter = altMatch[1];
+        const reason = altMatch[2];
+        if (letter === 'A' || letter === 'B' || letter === 'C') {
+            return reason === undefined
+                ? { kind: 'alternative', choice: letter }
+                : { kind: 'alternative', choice: letter, reason };
+        }
+    }
+    const rejectMatch = /^拒绝(?:\s+(.+))?$/u.exec(trimmed);
+    if (rejectMatch !== null) {
+        const reason = rejectMatch[1];
+        return reason === undefined
+            ? { kind: 'reject', reason: 'unspecified' }
+            : { kind: 'reject', reason };
+    }
+    if (trimmed === '接受' || trimmed === 'accept' || trimmed === 'y' || trimmed === 'Y') {
+        return { kind: 'accept', choice: recommended };
+    }
+    // Anything else is treated as a rejection-with-reason.
+    return { kind: 'reject', reason: trimmed };
+}
+export function registerBestPracticeScanCommand(program, io) {
+    addJsonOption(program
+        .command('best-practice-scan')
+        .description('2026-08-12 best-practice-scan: language-aware + business-aware doc-fragment lookup ' +
+        'via Context7 (priority 1) → WebSearch (priority 2) → empty fallback. ' +
+        'Renders the 8-row comparison table from spec §5 + §6 + §7. ' +
+        'Writes the artifact to <project>/best-practice/<date>-<intent>.md (gitignored).')
+        .option('--project <path>', 'project root (default cwd)', process.cwd())
+        .option('--lang <lang>', 'language override (skip auto-detect)')
+        .option('--commit', 'reserved flag — opts the artifact into git tracking (future slice)')).action(async (opts) => {
+        try {
+            const detection = opts.lang === undefined ? detectLanguage(opts.project) : null;
+            const language = opts.lang ?? detection?.language ?? 'unknown';
+            io.stdout(`[best-practice-scan] project=${opts.project} language=${language}`);
+            const scan = await scanBestPractice({
+                intent: opts.project,
+                language,
+                projectRoot: opts.project,
+                io
+            });
+            const recommendation = scan.results.length > 0 ? 'A' : 'B';
+            const reasoning = `基于 ${scan.fragments.length} 个 ${scan.source} 文档片段;` +
+                `语言=${language};LLM 推断方案 ${recommendation} 与项目阶段最匹配。`;
+            const table = formatOutputTable({
+                intent: opts.project,
+                language,
+                fragments: scan.results,
+                recommendation,
+                reasoning
+            });
+            io.stdout(table);
+            const forbiddenHits = findForbiddenTokens(table);
+            if (forbiddenHits.length > 0) {
+                io.stderr(`[best-practice-scan] WARNING: forbidden tokens detected: ${forbiddenHits.join(', ')}`);
+            }
+            io.stdout('');
+            io.stdout(CATCH_GATE_PROMPT);
+            const userInput = await readUserInput();
+            const outcome = parseCatchGateReply(userInput, recommendation);
+            const outDir = join(opts.project, 'best-practice');
+            mkdirSync(outDir, { recursive: true });
+            const dateStr = new Date().toISOString().slice(0, 10);
+            const slug = opts.project.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, 32) || 'intent';
+            const artifactPath = join(outDir, `${dateStr}-${slug}.md`);
+            writeFileSync(artifactPath, table + '\n', 'utf8');
+            printResult(io, ok('best-practice.scan', {
+                project: opts.project,
+                language,
+                scanSource: scan.source,
+                fragments: scan.results,
+                recommendation,
+                catchGate: outcome,
+                artifactPath,
+                commitFlag: opts.commit === true,
+                forbiddenHits
+            }, forbiddenHits.length > 0 ? [`forbidden tokens present: ${forbiddenHits.join(', ')}`] : [], [`Artifact written to ${artifactPath}`, `catch-gate outcome: ${outcome.kind}`]), opts.json === true);
+        }
+        catch (err) {
+            printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_FAILED', getErrorMessage(err), { stack: err instanceof Error ? err.stack : undefined }, ['Rerun with --json for machine-readable envelope']), opts.json === true);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/request-commands.js

@@ -5,6 +5,7 @@ import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '..
 import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
+import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /**
@@ -371,6 +372,10 @@ export function registerRequestCommands(program, io) {
             }
             // v2.13.2 AC-4 — auto-regen prd/handoff.md on prd:handed-off success.
             // Only fires when the handoff is missing; existing handoffs are not overwritten.
+            // Slice 2026-08-12 best-practice-scan (Slice F) — auto-trigger BPS as a
+            // post-step after peaks-prd's businessGoal artifact transitions to
+            // `handed-off` (the canonical "complete" state in the prd state machine).
+            // The trigger is fire-and-forget: failure NEVER blocks the transition.
             if (role === 'prd' && newState === 'handed-off' && options.sessionId !== undefined) {
                 const { autoRegenPrdHandoff } = await import('../../services/prd/handoff-auto-regen.js');
                 const regen = await autoRegenPrdHandoff({
@@ -379,17 +384,24 @@ export function registerRequestCommands(program, io) {
                     requestId,
                     role: 'prd'
                 });
-                if (regen.status === 'created') {
-                    // Stitch into the result envelope
-                    printResult(io, ok('request.transition', { ...result, handoffAutoRegen: { status: 'created', path: regen.path, sha256: regen.sha256 } }), options.json);
-                    return;
+                const bpsTrigger = await triggerBestPracticeScan({
+                    projectRoot: options.project,
+                    sessionId: result.sessionId,
+                    requestId
+                });
+                const handoffAutoRegen = regen.status === 'created'
+                    ? { status: 'created', path: regen.path, sha256: regen.sha256 }
+                    : regen.status === 'skipped-exists'
+                        ? { status: 'skipped-exists', path: regen.path }
+                        : { status: 'failed', reason: regen.reason };
+                const notes = [];
+                if (regen.status === 'failed') {
+                    notes.push(`prd handoff auto-regen failed: ${regen.reason}`);
                 }
-                if (regen.status === 'skipped-exists') {
-                    printResult(io, ok('request.transition', { ...result, handoffAutoRegen: { status: 'skipped-exists', path: regen.path } }), options.json);
-                    return;
+                if (bpsTrigger.status === 'failed') {
+                    notes.push(`best-practice-scan auto-trigger failed: ${bpsTrigger.reason ?? 'unknown'}`);
                 }
-                // status === 'failed' — surface a warning but don't block the transition
-                printResult(io, ok('request.transition', { ...result, handoffAutoRegen: { status: 'failed', reason: regen.reason } }, [`prd handoff auto-regen failed: ${regen.reason}`]), options.json);
+                printResult(io, ok('request.transition', { ...result, handoffAutoRegen, bestPracticeScanTrigger: bpsTrigger }, notes), options.json);
                 return;
             }
             // Slice 2026-07-01-strategic-compact-cli: stitch the pre-compact

package/dist/services/best-practice/language-detector.d.ts

@@ -0,0 +1,7 @@
+export type DetectedLanguage = 'typescript' | 'javascript' | 'python' | 'go' | 'java' | 'unknown';
+export type LanguageDetection = {
+    readonly language: DetectedLanguage;
+    readonly confidence: number;
+    readonly signals: readonly string[];
+};
+export declare function detectLanguage(projectRoot: string): LanguageDetection;

package/dist/services/best-practice/language-detector.js

@@ -0,0 +1,96 @@
+/**
+ * Slice 2026-08-12 best-practice-scan — language detector.
+ *
+ * Detects the project's primary language from well-known marker files.
+ * Returns one of: typescript | javascript | python | go | java | unknown.
+ *
+ * Detection priority (first hit wins):
+ *   1. Java    — `pom.xml` or `build.gradle` present
+ *   2. Go      — `go.mod` present
+ *   3. Python  — `requirements.txt` / `pyproject.toml` / `setup.py` present
+ *   4. Node    — `package.json` present:
+ *      a. `tsconfig.json` also present  → typescript (high confidence)
+ *      b. `package.json` `"type": "module"` + no tsconfig → javascript (medium confidence)
+ *      c. default `package.json` (no tsconfig, no `"type"`) → javascript (lower confidence)
+ *   5. none of the above → `unknown`
+ *
+ * Signals are exposed in the result so the caller (orchestrator) can
+ * optionally surface the detected marker list to the user.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const HIGH = 0.95;
+const MEDIUM = 0.8;
+const LOW = 0.6;
+function hasFile(root, name) {
+    return existsSync(join(root, name));
+}
+function readPackageType(root) {
+    const pkgPath = join(root, 'package.json');
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const raw = readFileSync(pkgPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === 'object' && 'type' in parsed) {
+            const typeVal = parsed.type;
+            if (typeof typeVal === 'string')
+                return typeVal;
+        }
+    }
+    catch {
+        /* malformed package.json → treat as absent */
+    }
+    return undefined;
+}
+export function detectLanguage(projectRoot) {
+    if (!statSync(projectRoot, { throwIfNoEntry: false })) {
+        throw new Error(`detectLanguage: projectRoot does not exist: ${projectRoot}`);
+    }
+    if (hasFile(projectRoot, 'pom.xml') || hasFile(projectRoot, 'build.gradle')) {
+        const signals = [];
+        if (hasFile(projectRoot, 'pom.xml'))
+            signals.push('pom.xml');
+        if (hasFile(projectRoot, 'build.gradle'))
+            signals.push('build.gradle');
+        return { language: 'java', confidence: HIGH, signals };
+    }
+    if (hasFile(projectRoot, 'go.mod')) {
+        return { language: 'go', confidence: HIGH, signals: ['go.mod'] };
+    }
+    if (hasFile(projectRoot, 'requirements.txt') ||
+        hasFile(projectRoot, 'pyproject.toml') ||
+        hasFile(projectRoot, 'setup.py')) {
+        const signals = [];
+        if (hasFile(projectRoot, 'requirements.txt'))
+            signals.push('requirements.txt');
+        if (hasFile(projectRoot, 'pyproject.toml'))
+            signals.push('pyproject.toml');
+        if (hasFile(projectRoot, 'setup.py'))
+            signals.push('setup.py');
+        return { language: 'python', confidence: HIGH, signals };
+    }
+    if (hasFile(projectRoot, 'package.json')) {
+        if (hasFile(projectRoot, 'tsconfig.json')) {
+            return {
+                language: 'typescript',
+                confidence: HIGH,
+                signals: ['package.json', 'tsconfig.json']
+            };
+        }
+        const pkgType = readPackageType(projectRoot);
+        if (pkgType === 'module') {
+            return {
+                language: 'javascript',
+                confidence: MEDIUM,
+                signals: ['package.json', '"type": "module"']
+            };
+        }
+        return {
+            language: 'javascript',
+            confidence: LOW,
+            signals: ['package.json']
+        };
+    }
+    return { language: 'unknown', confidence: 0, signals: [] };
+}

package/dist/services/best-practice/output-formatter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Slice 2026-08-12 best-practice-scan — output formatter.
+ *
+ * Renders the 8-row business-decision comparison table (per spec §5) plus
+ * the 3-line footer (spec §5 footer + §7 ⚠️ gate). The formatter is the
+ * single source of truth for the artifact's text shape; the standalone
+ * template file at `src/templates/best-practice-scan.md` mirrors this
+ * shape for human reference.
+ *
+ * Hard rules enforced here (defensive scans):
+ *   - Forbidden words: 会爆 / 头疼 / 黑暗 / 崩
+ *   - Forbidden developer-perspective phrases: 代码 50 行 / 学习曲线 / 你的难
+ *   - Forbidden binary framing: MVP vs 长期
+ *   - Forbidden project-stage judgment: MVP 项目
+ *
+ * The `★` recommendation marker is placed on the column header whose
+ * `recommendation` value (A / B / C) matches `opts.recommendation`.
+ */
+import type { DocFragment } from './scan-orchestrator.js';
+export type RecommendationChoice = 'A' | 'B' | 'C';
+export type FormatOptions = {
+    readonly intent: string;
+    readonly language: string;
+    readonly fragments: readonly DocFragment[];
+    readonly recommendation: RecommendationChoice;
+    readonly reasoning: string;
+};
+export declare function formatOutputTable(opts: FormatOptions): string;
+/**
+ * Defensive scan: returns the list of forbidden-word / phrase hits
+ * present in the rendered output. The catch-gate test calls this to
+ * fail-loud if a future code change reintroduces a banned token.
+ */
+export declare function findForbiddenTokens(rendered: string): readonly string[];
+export declare const __TEST__: {
+    ROW_LABELS: readonly ["技术组合(通俗)", "peaks-code 估算", "user 看到", "user 操作", "业务影响(6 个月后)", "适用场景", "适用场景 (parallel)", "LLM 推荐"];
+    FORBIDDEN_WORDS: readonly ["会爆", "头疼", "黑暗", "崩"];
+    FORBIDDEN_PHRASES: readonly ["代码 50 行", "学习曲线", "你的难"];
+    FORBIDDEN_BINARY: readonly ["MVP vs 长期"];
+    FORBIDDEN_STAGE: readonly ["MVP 项目"];
+};

package/dist/services/best-practice/output-formatter.js

@@ -0,0 +1,116 @@
+const ROW_LABELS = [
+    '技术组合(通俗)',
+    'peaks-code 估算',
+    'user 看到',
+    'user 操作',
+    '业务影响(6 个月后)',
+    '适用场景',
+    '适用场景 (parallel)',
+    'LLM 推荐'
+];
+const FORBIDDEN_WORDS = ['会爆', '头疼', '黑暗', '崩'];
+const FORBIDDEN_PHRASES = ['代码 50 行', '学习曲线', '你的难'];
+const FORBIDDEN_BINARY = ['MVP vs 长期'];
+const FORBIDDEN_STAGE = ['MVP 项目'];
+function rowLabel(row) {
+    return `| **${row}** | ... | ... | ... |`;
+}
+function recommendedColumnHeader(label, isRecommended) {
+    return isRecommended ? `**${label} ★**` : label;
+}
+export function formatOutputTable(opts) {
+    const cols = [
+        {
+            choice: 'A',
+            label: recommendedColumnHeader('方案 A', opts.recommendation === 'A'),
+            body: '面向长期维护,组件复用度高,适合多人协作。'
+        },
+        {
+            choice: 'B',
+            label: recommendedColumnHeader('方案 B', opts.recommendation === 'B'),
+            body: '中等复杂度,上手快,适合迭代中的小团队。'
+        },
+        {
+            choice: 'C',
+            label: recommendedColumnHeader('方案 C', opts.recommendation === 'C'),
+            body: '极简实现,适合一次性脚本或概念验证。'
+        }
+    ];
+    const colA = cols[0];
+    const colB = cols[1];
+    const colC = cols[2];
+    if (colA === undefined || colB === undefined || colC === undefined) {
+        throw new Error('formatOutputTable: column triple must be present');
+    }
+    const head = `| ${ROW_LABELS[0]} | ${colA.label} | ${colB.label} | ${colC.label} |`;
+    const sep = '| --- | --- | --- | --- |';
+    const bodyRows = [];
+    for (let i = 0; i < ROW_LABELS.length; i += 1) {
+        const label = ROW_LABELS[i];
+        if (label === undefined)
+            continue;
+        if (label === 'LLM 推荐') {
+            const recCell = cols
+                .map((c) => (c.choice === opts.recommendation ? `**${c.choice}**` : c.choice))
+                .join(' / ');
+            bodyRows.push(`| **${label}** | ${recCell} | ${recCell} | ${recCell} |`);
+            continue;
+        }
+        if (label === '适用场景 (parallel)') {
+            bodyRows.push(`| **${label}** | < 5 字段 + < 2 月就用掉 | 字段会增长 + 1 年+ 持续维护 | 灵活配置 + 长期演进 |`);
+            continue;
+        }
+        bodyRows.push(rowLabel(label));
+    }
+    const reasoningBlock = `> **LLM 推理:** ${opts.reasoning}`;
+    const footer = [
+        '↩ 默认走方案 ' + opts.recommendation + ';觉得估错 / 推荐不对就告诉我。',
+        '⚠️ 任何跟你真实业务不一样,改 — LLM 推荐可能错。',
+        '📝 备注:user 体验在 2/3 个方案里几乎一致,差别在 6 个月后的维护成本和你的项目长期节奏。'
+    ].join('\n');
+    const meta = [
+        `language: ${opts.language}`,
+        `intent: ${opts.intent}`,
+        `fragments: ${opts.fragments.length}`,
+        `recommendation: ${opts.recommendation}`
+    ].join(' | ');
+    return [
+        `# Best-Practice Scan — ${opts.intent}`,
+        '',
+        `> ${meta}`,
+        '',
+        reasoningBlock,
+        '',
+        head,
+        sep,
+        ...bodyRows,
+        '',
+        footer
+    ].join('\n');
+}
+/**
+ * Defensive scan: returns the list of forbidden-word / phrase hits
+ * present in the rendered output. The catch-gate test calls this to
+ * fail-loud if a future code change reintroduces a banned token.
+ */
+export function findForbiddenTokens(rendered) {
+    const hits = [];
+    for (const word of FORBIDDEN_WORDS) {
+        if (rendered.includes(word))
+            hits.push(word);
+    }
+    for (const phrase of FORBIDDEN_PHRASES) {
+        if (rendered.includes(phrase))
+            hits.push(phrase);
+    }
+    for (const binary of FORBIDDEN_BINARY) {
+        if (rendered.includes(binary))
+            hits.push(binary);
+    }
+    for (const stage of FORBIDDEN_STAGE) {
+        if (rendered.includes(stage))
+            hits.push(stage);
+    }
+    return hits;
+}
+export const __TEST__ = { ROW_LABELS, FORBIDDEN_WORDS, FORBIDDEN_PHRASES, FORBIDDEN_BINARY, FORBIDDEN_STAGE };

package/dist/services/best-practice/scan-orchestrator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Slice 2026-08-12 best-practice-scan — scan orchestrator.
+ *
+ * Resolves a doc-fragment set for a (intent, language) query via the
+ * following priority chain:
+ *   1. Context7 MCP  (priority 1; 30 s timeout)
+ *   2. WebSearch    (priority 2 fallback; 200 ms simulated delay)
+ *   3. Empty        (both sources exhausted)
+ *
+ * The Context7 + WebSearch calls are STUB implementations for v1:
+ * they sleep for a fixed delay and return synthetic doc fragments so
+ * the orchestrator's source-priority logic is testable end-to-end.
+ * Real MCP wiring is a future slice — the stubs are clearly marked.
+ *
+ * The orchestrator emits structured log lines via the injected `io`
+ * (stdout for progress, stderr for warnings) so a CLI caller can see
+ * which fallback path was taken.
+ */
+import type { ProgramIO } from '../../cli/cli-helpers.js';
+export type DocFragment = {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+};
+export type ScanSource = 'context7' | 'websearch' | 'fallback';
+export type ScanResult = {
+    readonly results: readonly DocFragment[];
+    readonly fragments: readonly DocFragment[];
+    readonly source: ScanSource;
+    readonly elapsedMs: number;
+};
+export type ScanOptions = {
+    readonly intent: string;
+    readonly language: string;
+    readonly projectRoot: string;
+    readonly io: ProgramIO;
+    readonly context7TimeoutMs?: number;
+};
+export declare function scanBestPractice(opts: ScanOptions): Promise<ScanResult>;

package/dist/services/best-practice/scan-orchestrator.js

@@ -0,0 +1,85 @@
+const DEFAULT_CONTEXT7_TIMEOUT_MS = 30_000;
+const DEFAULT_CONTEXT7_DELAY_MS = 100;
+const DEFAULT_WEBSEARCH_DELAY_MS = 200;
+const defaultContext7Lookup = async (intent, language) => {
+    // TODO: real MCP integration — call `@upstash/context7-mcp`'s
+    // resolve-library-id + query-docs and translate errors into the
+    // shared `{ ok, results }` envelope.
+    await new Promise((resolveFn) => setTimeout(resolveFn, DEFAULT_CONTEXT7_DELAY_MS));
+    return {
+        ok: true,
+        results: [
+            {
+                title: `Context7 ${language} doc for "${intent}"`,
+                url: `https://context7.com/${language}/${encodeURIComponent(intent)}`,
+                snippet: `best practice for ${intent} in ${language} (context7 stub)`
+            }
+        ]
+    };
+};
+const defaultWebSearchLookup = async (intent, language) => {
+    // TODO: real web search wiring — use Context7 WebSearch tool or
+    // WebFetch + ranking; current stub returns a synthetic fragment.
+    await new Promise((resolveFn) => setTimeout(resolveFn, DEFAULT_WEBSEARCH_DELAY_MS));
+    return {
+        ok: true,
+        results: [
+            {
+                title: `WebSearch ${language} case for "${intent}"`,
+                url: `https://example.com/search?q=${encodeURIComponent(intent)}&lang=${language}`,
+                snippet: `implementation example for ${intent} in ${language} (websearch stub)`
+            }
+        ]
+    };
+};
+export async function scanBestPractice(opts) {
+    const timeoutMs = opts.context7TimeoutMs ?? DEFAULT_CONTEXT7_TIMEOUT_MS;
+    const startedAt = Date.now();
+    opts.io.stdout(`[scan-orchestrator] querying context7 for "${opts.intent}" (${opts.language})`);
+    let context7Outcome = null;
+    let context7Error = null;
+    try {
+        const ctxPromise = defaultContext7Lookup(opts.intent, opts.language);
+        const ctxTimer = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(`context7 timeout after ${timeoutMs}ms`)), timeoutMs).unref();
+        });
+        context7Outcome = await Promise.race([ctxPromise, ctxTimer]);
+    }
+    catch (err) {
+        context7Error = err instanceof Error ? err.message : String(err);
+        opts.io.stderr(`[scan-orchestrator] context7 failed: ${context7Error}`);
+    }
+    if (context7Outcome !== null && context7Outcome.ok && context7Outcome.results.length > 0) {
+        return {
+            results: context7Outcome.results,
+            fragments: context7Outcome.results,
+            source: 'context7',
+            elapsedMs: Date.now() - startedAt
+        };
+    }
+    opts.io.stdout(`[scan-orchestrator] falling back to websearch for "${opts.intent}" (${opts.language})`);
+    let webOutcome = null;
+    let webError = null;
+    try {
+        webOutcome = await defaultWebSearchLookup(opts.intent, opts.language);
+    }
+    catch (err) {
+        webError = err instanceof Error ? err.message : String(err);
+        opts.io.stderr(`[scan-orchestrator] websearch failed: ${webError}`);
+    }
+    if (webOutcome !== null && webOutcome.ok && webOutcome.results.length > 0) {
+        return {
+            results: webOutcome.results,
+            fragments: webOutcome.results,
+            source: 'websearch',
+            elapsedMs: Date.now() - startedAt
+        };
+    }
+    opts.io.stderr('[scan-orchestrator] both sources empty; returning empty fallback');
+    return {
+        results: [],
+        fragments: [],
+        source: 'fallback',
+        elapsedMs: Date.now() - startedAt
+    };
+}