@getripple/cli 1.0.5 → 1.0.7

package/dist/index.js

@@ -36,6 +36,7 @@ function usage() {
         "  ripple init [--force] [--json]",
         "  ripple doctor [--strict] [--agent]",
         "  ripple scan [path]",
+        "  ripple workflow [--json]",
         "  ripple focus <file>",
         "  ripple blast <file>",
         "  ripple imports <file>",
@@ -82,6 +83,7 @@ function usage() {
         "Examples:",
         "  ripple init",
         "  ripple doctor",
+        "  ripple workflow",
         "  ripple doctor --agent",
         "  ripple agent",
         "  ripple agent --json",
@@ -420,12 +422,19 @@ function githubActionsWorkflow() {
         "",
     ].join("\n");
 }
+function rippleGitIgnoreBlock() {
+    return [
+        "# Ripple machine cache - regenerated automatically",
+        core_1.RIPPLE_CACHE_GITIGNORE_ENTRY,
+        "",
+    ].join("\n");
+}
 function defaultInitNextSteps(readiness) {
     return uniqueLines([
         ...(readiness?.nextSteps ?? []),
         "Run ripple plan --file <file> --task \"<task>\" --mode file --agent --save.",
         "Run ripple doctor --agent --strict after saving the first intent.",
-        "Commit .ripple/policy.json, .github/workflows/ripple.yml, and the saved intent when you want CI to enforce the gate.",
+        "Commit .ripple/policy.json, .ripple/intents/latest.json, approvals when needed, and .github/workflows/ripple.yml.",
     ]);
 }
 function uniqueLines(lines) {
@@ -682,6 +691,13 @@ function buildGithubAuditStepSummary(audit) {
     lines.push("");
     pushList(lines, "Fix now", gate.fixNow, 12);
     lines.push("");
+    lines.push("### Risk", "", `- Level: ${gate.risk.level}`, `- Score: ${gate.risk.score}/100`, `- Summary: ${gate.risk.summary}`, "");
+    pushList(lines, "Why this is risky", compactGateRiskReasons(gate), 8);
+    lines.push("");
+    pushList(lines, "Risk evidence", compactGateRiskEvidence(gate), 12);
+    lines.push("");
+    pushList(lines, "Risk required actions", compactGateRiskActions(gate), 12);
+    lines.push("");
     pushList(lines, "Ask human", gate.askHuman, 8);
     lines.push("");
     pushList(lines, "Gate commands", uniqueItems([
@@ -933,13 +949,51 @@ async function runWithQuietEngine(task) {
         console.log = originalLog;
     }
 }
+function createCliEngine(workspaceRoot, contextMode = "lean") {
+    const engine = new core_1.GraphEngine(workspaceRoot);
+    engine.setContextGenerationMode(contextMode);
+    return engine;
+}
+function createFastCheckEngine(workspaceRoot) {
+    const engine = createCliEngine(workspaceRoot, "lean");
+    return engine;
+}
+function fastCheckCandidateFiles(files, intent) {
+    const intentSymbolFiles = (intent?.allowedSymbols ?? [])
+        .map((symbolId) => symbolId.split("::")[0])
+        .filter(Boolean);
+    return uniqueItems([
+        ...files,
+        ...(intent
+            ? [
+                intent.targetFile,
+                ...intent.editableFiles,
+                ...intent.allowedFiles,
+                ...intent.expectedFiles,
+                ...intent.contextFiles,
+                ...intentSymbolFiles,
+            ]
+            : []),
+    ].filter((file) => Boolean(file)));
+}
 function printScanSummary(summary) {
     console.log("Ripple scan complete");
     console.log(`Workspace: ${summary.workspace}`);
     console.log(`Files: ${summary.files}`);
     console.log(`Symbols: ${summary.symbols}`);
     console.log(`Call edges: ${summary.callEdges}`);
-    console.log(`Context: .ripple/ ${summary.contextGenerated ? "generated" : "not generated"}`);
+    console.log(`Mode: ${summary.contextMode}`);
+    console.log(`Graph cache: ${summary.cacheGenerated ? summary.cachePath : "not generated"}`);
+    console.log(`Context bundle: ${summary.contextGenerated ? summary.contextPath : "not generated by lean scan"}`);
+}
+function printWorkflowSummary(summary) {
+    console.log("Ripple workflow generated");
+    console.log(`Workspace: ${summary.workspace}`);
+    console.log(`Path: ${summary.path}`);
+    console.log(`Context bundle: ${summary.contextGenerated ? "generated" : "missing"}`);
+    console.log(`Focus files: ${summary.focusFileCount}`);
+    console.log("");
+    printHumanList("Next:", summary.nextSteps);
 }
 function printDoctorSummary(summary) {
     console.log("Ripple doctor");
@@ -951,6 +1005,7 @@ function printDoctorSummary(summary) {
     console.log(`Agent trust: ${summary.adapterSupport.primaryAdapter.agentPolicy.canTrust.join(", ")}`);
     console.log(`Graph: ${summary.checks.graph.ok ? "ok" : "missing"} - ${summary.checks.graph.detail}`);
     console.log(`Git: ${summary.checks.git.ok ? "ok" : "missing"} - ${summary.checks.git.detail}`);
+    console.log(`Git ignore: ${summary.checks.gitIgnore.ok ? "ok" : "missing"} - ${summary.checks.gitIgnore.detail}`);
     console.log(`CI workflow: ${summary.checks.ciWorkflow.ok ? "ok" : "missing"} - ${summary.checks.ciWorkflow.detail}`);
     console.log(`Latest intent: ${summary.checks.latestIntent.ok ? "ok" : "missing"} - ${summary.checks.latestIntent.detail}`);
     console.log("");
@@ -993,7 +1048,10 @@ function printInitSummary(summary) {
 function printAgentDoctorSummary(summary) {
     console.log("RIPPLE_DOCTOR");
     console.log(`status: ${summary.status}`);
-    console.log(`readiness_decision: ${summary.status === "ready" ? "continue" : "setup-required"}`);
+    console.log(`decision: ${summary.decision}`);
+    console.log(`can_continue: ${summary.canContinue}`);
+    console.log(`must_stop: ${summary.mustStop}`);
+    console.log(`next_required_action: ${summary.nextRequiredAction}`);
     console.log(`workspace: ${summary.workspace}`);
     console.log(`adapter: ${summary.adapterSupport.primaryAdapter.id}`);
     console.log(`adapter_support: ${summary.adapterSupport.supportLevel}`);
@@ -1006,10 +1064,13 @@ function printAgentDoctorSummary(summary) {
     console.log(`policy_detail: ${summary.enforcement.explicitPolicy.detail}`);
     console.log(`graph: ${summary.checks.graph.ok ? "ok" : "missing"} - ${summary.checks.graph.detail}`);
     console.log(`git: ${summary.checks.git.ok ? "ok" : "missing"} - ${summary.checks.git.detail}`);
+    console.log(`git_ignore: ${summary.checks.gitIgnore.ok ? "ok" : "missing"} - ${summary.checks.gitIgnore.detail}`);
     console.log(`ci_workflow: ${summary.checks.ciWorkflow.ok ? "ok" : "missing"} - ${summary.checks.ciWorkflow.detail}`);
     console.log(`latest_intent: ${summary.checks.latestIntent.ok ? "ok" : "missing"} - ${summary.checks.latestIntent.detail}`);
     console.log("");
-    printAgentList("gaps", summary.enforcement.gaps);
+    printAgentList("why", summary.why);
+    console.log("");
+    printAgentList("fix_now", summary.fixNow);
     console.log("");
     printAgentList("next_steps", summary.nextSteps);
 }
@@ -1752,6 +1813,15 @@ function printAgentGateSummary(summary) {
     console.log(`control_mode: ${summary.intent.controlMode}`);
     console.log(`human_gate: ${summary.intent.humanGate}`);
     console.log(`boundary_risk: ${summary.intent.boundaryRisk}`);
+    console.log(`risk_level: ${summary.risk.level}`);
+    console.log(`risk_score: ${summary.risk.score}`);
+    console.log(`risk_summary: ${summary.risk.summary}`);
+    console.log("");
+    printAgentList("risk_reasons", compactGateRiskReasons(summary));
+    console.log("");
+    printAgentList("risk_evidence", compactGateRiskEvidence(summary));
+    console.log("");
+    printAgentList("risk_required_actions", compactGateRiskActions(summary));
     console.log("");
     printAgentList("why", summary.why);
     console.log("");
@@ -1776,43 +1846,100 @@ function printAgentGateSummary(summary) {
     printAgentList("commands_verify", summary.commands.verify);
 }
 function printGateSummary(summary) {
-    console.log("Ripple gate");
-    console.log(`Status: ${summary.status}`);
+    const statusLabel = summary.canContinue ? "CONTINUE" : "STOP";
+    console.log(`Ripple gate: ${statusLabel}`);
+    console.log(gateHeadline(summary));
+    console.log("");
     console.log(`Decision: ${summary.decision}`);
-    console.log(`Can continue: ${summary.canContinue}`);
-    console.log(`Must stop: ${summary.mustStop}`);
-    console.log(`Needs human: ${summary.needsHuman}`);
-    console.log(`Next required phase: ${summary.nextRequiredPhase}`);
-    console.log(`Next required action: ${summary.nextRequiredAction}`);
-    console.log(`Summary: ${summary.summary}`);
+    console.log(`Can continue: ${formatYesNo(summary.canContinue)}`);
+    console.log(`Must stop: ${formatYesNo(summary.mustStop)}`);
+    printGateRiskSummary(summary);
     console.log("");
     console.log("Intent:");
-    console.log(`  id: ${summary.intent.id}`);
-    console.log(`  task: ${summary.intent.task}`);
-    console.log(`  target: ${summary.intent.targetFile}`);
-    console.log(`  control mode: ${summary.intent.controlMode}`);
-    console.log(`  human gate: ${summary.intent.humanGate}`);
-    console.log(`  boundary risk: ${summary.intent.boundaryRisk}`);
+    console.log(`  Task: ${summary.intent.task}`);
+    console.log(`  Boundary: ${summary.intent.controlMode}`);
+    console.log(`  Target: ${summary.intent.targetFile}`);
+    console.log(`  Human gate: ${summary.intent.humanGate}`);
+    console.log(`  Approval: ${summary.approvalStatus}`);
+    console.log("");
+    printHumanList("Allowed:", gateAllowedItems(summary));
+    const outsideBoundary = gateChangedOutsideItems(summary);
+    printHumanList(outsideBoundary.length > 0 ? "Changed outside boundary:" : "Changed files:", outsideBoundary.length > 0 ? outsideBoundary : summary.changedFiles);
+    printHumanList("Why:", compactGateReasons(summary));
+    printHumanList("Fix now:", compactGateFixes(summary));
+    if (summary.canContinue) {
+        printHumanList("Verify:", summary.verificationTargets.slice(0, 8));
+    }
+    else {
+        printHumanList("Commands:", compactGateCommands(summary));
+    }
+}
+function printGateRiskSummary(summary) {
     console.log("");
-    console.log("Audit:");
-    console.log(`  status: ${summary.auditStatus}`);
-    console.log(`  decision: ${summary.auditDecision}`);
-    console.log(`  approval status: ${summary.approvalStatus}`);
-    console.log("");
-    printHumanList("Why:", summary.why);
-    printHumanList("Fix now:", summary.fixNow);
-    printHumanList("Ask human:", summary.askHuman);
-    printHumanList("Changed files:", summary.changedFiles);
-    printHumanList("Verify:", summary.verificationTargets);
-    const commands = [
-        ...summary.commands.doctor,
-        ...summary.commands.check,
-        ...summary.commands.audit,
+    console.log(`Risk: ${summary.risk.level.toUpperCase()} ${summary.risk.score}/100`);
+    console.log(`Risk summary: ${summary.risk.summary}`);
+    printHumanList("Why this is risky:", compactGateRiskReasons(summary));
+    printHumanList("Evidence:", compactGateRiskEvidence(summary));
+    printHumanList("Required:", compactGateRiskActions(summary));
+}
+function compactGateRiskReasons(summary) {
+    return summary.risk.reasons
+        .map((reason) => `${reason.severity.toUpperCase()} ${reason.kind}: ${reason.message}`)
+        .slice(0, 6);
+}
+function compactGateRiskEvidence(summary) {
+    return uniqueItems(summary.risk.reasons.flatMap((reason) => reason.evidence)).slice(0, 10);
+}
+function compactGateRiskActions(summary) {
+    return uniqueItems(summary.risk.requiredActions).slice(0, 8);
+}
+function gateHeadline(summary) {
+    if (summary.canContinue) {
+        return "Agent may continue after running the listed verification targets.";
+    }
+    if (summary.decision === "restore-readiness") {
+        return "Agent must stop because Ripple readiness is weaker than the saved intent.";
+    }
+    if (summary.needsHuman) {
+        return "Agent must stop and ask the human before continuing.";
+    }
+    return "Agent must stop and repair the staged change before continuing.";
+}
+function gateAllowedItems(summary) {
+    if (summary.intent.controlMode === "brainstorm") {
+        return ["no file edits"];
+    }
+    if (summary.allowedSymbols.length > 0) {
+        return summary.allowedSymbols;
+    }
+    if (summary.allowedFiles.length > 0) {
+        return summary.allowedFiles;
+    }
+    return [summary.intent.targetFile];
+}
+function gateChangedOutsideItems(summary) {
+    return [
+        ...summary.changedOutsideBoundaryFiles.map((file) => `file: ${file}`),
+        ...summary.changedOutsideBoundarySymbols.map((symbol) => `symbol: ${symbol}`),
+    ];
+}
+function compactGateReasons(summary) {
+    return uniqueItems(summary.why).slice(0, 6);
+}
+function compactGateFixes(summary) {
+    return uniqueItems(summary.fixNow).slice(0, 6);
+}
+function compactGateCommands(summary) {
+    return uniqueItems([
+        ...summary.commands.unstage,
         ...summary.commands.repair,
         ...summary.commands.approve,
-        ...summary.commands.unstage,
-    ];
-    printHumanList("Commands:", commands);
+        ...summary.commands.plan,
+        ...summary.commands.doctor,
+    ]).slice(0, 6);
+}
+function formatYesNo(value) {
+    return value ? "yes" : "no";
 }
 function printAuditSummary(summary) {
     const validation = summary.stagedCheck.intentValidation;
@@ -2232,7 +2359,7 @@ async function planCommand(options) {
         throw new Error("Missing target file. Usage: ripple plan --file <file> --task <task> [--budget N]");
     }
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = engine.planContext(options.task ?? "", options.file, options.budget);
@@ -2306,9 +2433,9 @@ function approvalStatusOutput(intent, status) {
     };
 }
 async function buildAuditForFiles(input) {
-    const engine = new core_1.GraphEngine(input.workspaceRoot);
+    const engine = createFastCheckEngine(input.workspaceRoot);
     try {
-        await runWithQuietEngine(() => engine.initialScan());
+        await runWithQuietEngine(() => engine.fastCheckScan(fastCheckCandidateFiles(input.files, input.intent)));
         const stagedCheck = (0, core_1.buildStagedCheckSummary)(engine, {
             workspaceRoot: input.workspaceRoot,
             stagedFiles: input.files,
@@ -2336,9 +2463,9 @@ async function buildAuditForFiles(input) {
     }
 }
 async function buildCheckSummaryForFiles(input) {
-    const engine = new core_1.GraphEngine(input.workspaceRoot);
+    const engine = createFastCheckEngine(input.workspaceRoot);
     try {
-        await runWithQuietEngine(() => engine.initialScan());
+        await runWithQuietEngine(() => engine.fastCheckScan(fastCheckCandidateFiles(input.files)));
         return (0, core_1.buildStagedCheckSummary)(engine, {
             workspaceRoot: input.workspaceRoot,
             stagedFiles: input.files,
@@ -2363,9 +2490,9 @@ async function checkCommand(options) {
     const checkFiles = options.changed
         ? (0, core_1.listGitChangedFiles)(workspaceRoot, baseRef)
         : (0, core_1.listGitStagedFiles)(workspaceRoot);
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createFastCheckEngine(workspaceRoot);
     try {
-        await runWithQuietEngine(() => engine.initialScan());
+        await runWithQuietEngine(() => engine.fastCheckScan(fastCheckCandidateFiles(checkFiles)));
         const stagedSummary = (0, core_1.buildStagedCheckSummary)(engine, {
             workspaceRoot,
             stagedFiles: checkFiles,
@@ -2614,7 +2741,7 @@ async function ciCommand(options) {
 }
 async function doctorCommand(options) {
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = (0, core_1.buildRippleReadinessSummary)(workspaceRoot, engine);
@@ -2638,6 +2765,7 @@ async function initCommand(options) {
     const policy = (0, core_1.defaultRipplePolicy)();
     const policyContents = (0, core_1.formatRipplePolicy)(policy);
     const workflow = githubActionsWorkflow();
+    const gitignoreBlock = rippleGitIgnoreBlock();
     const files = [
         {
             path: core_1.RIPPLE_POLICY_PATH.split(path.sep).join("/"),
@@ -2649,6 +2777,12 @@ async function initCommand(options) {
             absolutePath: path.join(workspaceRoot, GITHUB_ACTIONS_WORKFLOW_PATH),
             content: workflow,
         },
+        {
+            path: core_1.RIPPLE_GITIGNORE_PATH,
+            absolutePath: path.join(workspaceRoot, core_1.RIPPLE_GITIGNORE_PATH),
+            content: gitignoreBlock,
+            merge: true,
+        },
     ];
     if (options.print) {
         const summary = {
@@ -2668,18 +2802,15 @@ async function initCommand(options) {
             printJson(summary);
             return;
         }
-        process.stdout.write([
-            `# ${files[0].path}`,
-            files[0].content.trimEnd(),
-            "",
-            `# ${files[1].path}`,
-            files[1].content.trimEnd(),
-            "",
-        ].join("\n"));
+        process.stdout.write(files
+            .flatMap((file) => [`# ${file.path}`, file.content.trimEnd(), ""])
+            .join("\n"));
         return;
     }
-    const writtenFiles = files.map((file) => writeInitFile(file, options.force));
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const writtenFiles = files.map((file) => file.merge
+        ? writeRippleGitIgnoreFile(file.absolutePath)
+        : writeInitFile(file, options.force));
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const readiness = (0, core_1.buildRippleReadinessSummary)(workspaceRoot, engine);
@@ -2721,6 +2852,44 @@ function writeInitFile(file, force) {
         overwritten: existed,
     };
 }
+function writeRippleGitIgnoreFile(targetPath) {
+    const content = rippleGitIgnoreBlock();
+    const existed = fs.existsSync(targetPath);
+    if (!existed) {
+        fs.writeFileSync(targetPath, content, "utf8");
+        return {
+            path: core_1.RIPPLE_GITIGNORE_PATH,
+            status: "written",
+            written: true,
+            overwritten: false,
+        };
+    }
+    const existing = fs.readFileSync(targetPath, "utf8");
+    if (gitIgnoreContainsRippleCache(existing)) {
+        return {
+            path: core_1.RIPPLE_GITIGNORE_PATH,
+            status: "exists",
+            written: false,
+            overwritten: false,
+        };
+    }
+    const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+    fs.writeFileSync(targetPath, `${existing}${separator}${content}`, "utf8");
+    return {
+        path: core_1.RIPPLE_GITIGNORE_PATH,
+        status: "updated",
+        written: true,
+        overwritten: false,
+    };
+}
+function gitIgnoreContainsRippleCache(contents) {
+    return contents
+        .split(/\r?\n/)
+        .map((line) => line.trim().replace(/\\/g, "/").replace(/^\/+/, ""))
+        .some((line) => line === core_1.RIPPLE_CACHE_GITIGNORE_ENTRY ||
+        line === ".ripple/.cache" ||
+        line === ".ripple/.cache/**");
+}
 function initCiCommand(options) {
     const workflow = githubActionsWorkflow();
     const workspaceRoot = resolveWorkspaceRoot(".");
@@ -2867,15 +3036,15 @@ function printAgentPolicyExplanation(explanation) {
 async function repairCommand(options) {
     const workspaceRoot = resolveWorkspaceRoot(".");
     const stagedFiles = (0, core_1.listGitStagedFiles)(workspaceRoot);
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const intent = (0, core_1.loadChangeIntent)(workspaceRoot, options.intent ?? "latest");
+    const engine = createFastCheckEngine(workspaceRoot);
     try {
-        await runWithQuietEngine(() => engine.initialScan());
+        await runWithQuietEngine(() => engine.fastCheckScan(fastCheckCandidateFiles(stagedFiles, intent)));
         const stagedSummary = (0, core_1.buildStagedCheckSummary)(engine, {
             workspaceRoot,
             stagedFiles,
             tokenBudget: options.budget,
         });
-        const intent = (0, core_1.loadChangeIntent)(workspaceRoot, options.intent ?? "latest");
         const summary = (0, core_1.validateStagedCheckAgainstIntent)(stagedSummary, intent, {
             currentPolicyExplanation: currentPolicyExplanationForIntent(workspaceRoot, intent),
             currentReadinessSnapshot: currentReadinessSnapshotForEngine(workspaceRoot, engine),
@@ -2898,7 +3067,7 @@ async function repairCommand(options) {
 }
 async function historyCommand(options) {
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = engine.getRecentHistorySummary(options.last);
@@ -2921,7 +3090,7 @@ async function callersCommand(symbolId, options) {
         throw new Error("Symbol id must use <file>::<symbol>, for example src/auth.ts::validateToken");
     }
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = engine.getSymbolCallersSummary(symbolId);
@@ -2941,16 +3110,20 @@ async function callersCommand(symbolId, options) {
 }
 async function scanCommand(targetPath, options) {
     const workspaceRoot = resolveWorkspaceRoot(targetPath);
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
+        const cachePath = path.join(workspaceRoot, ".ripple", ".cache", "graph.cache.json");
         const workflowPath = path.join(workspaceRoot, ".ripple", "WORKFLOW.md");
         const summary = {
             workspace: workspaceRoot,
             files: engine.graph.files.size,
             symbols: engine.graph.symbols.size,
             callEdges: countCallEdges(engine),
-            contextGenerated: fs.existsSync(workflowPath),
+            contextMode: "lean",
+            cacheGenerated: fs.existsSync(cachePath),
+            cachePath,
+            contextGenerated: false,
             contextPath: workflowPath,
         };
         if (options.json) {
@@ -2964,12 +3137,66 @@ async function scanCommand(targetPath, options) {
         engine.dispose();
     }
 }
+async function workflowCommand(options) {
+    const workspaceRoot = resolveWorkspaceRoot(".");
+    const engine = createCliEngine(workspaceRoot, "full");
+    try {
+        await runWithQuietEngine(() => engine.initialScan());
+        const workflowPath = path.join(workspaceRoot, ".ripple", "WORKFLOW.md");
+        const contextDir = path.join(workspaceRoot, ".ripple", ".cache");
+        const contextFiles = [
+            ".ripple/.cache/context.json",
+            ".ripple/.cache/context.files.json",
+            ".ripple/.cache/context.symbols.json",
+        ];
+        const focusDir = path.join(contextDir, "focus");
+        const focusFileCount = countJsonFiles(focusDir);
+        const summary = {
+            protocol: "ripple-workflow",
+            version: 1,
+            workspace: workspaceRoot,
+            path: ".ripple/WORKFLOW.md",
+            written: fs.existsSync(workflowPath),
+            contextGenerated: contextFiles.every((filePath) => fs.existsSync(path.join(workspaceRoot, filePath))),
+            contextFiles,
+            focusFileCount,
+            nextSteps: [
+                "Copy .ripple/WORKFLOW.md into your agent instruction file if your agent does not use MCP.",
+                "For MCP-capable agents, prefer ripple_plan_context and ripple_gate over reading generated files.",
+                "Run ripple scan for a lean graph refresh when you do not need file-based agent instructions.",
+            ],
+        };
+        if (!summary.written) {
+            throw new Error("WORKFLOW.md was not generated. Check that the workspace has supported source files.");
+        }
+        if (options.json) {
+            printJson(summary);
+        }
+        else {
+            printWorkflowSummary(summary);
+        }
+    }
+    finally {
+        engine.dispose();
+    }
+}
+function countJsonFiles(directoryPath) {
+    try {
+        return fs
+            .readdirSync(directoryPath)
+            .filter((fileName) => fileName.endsWith(".json"))
+            .length;
+    }
+    catch {
+        return 0;
+    }
+}
 async function symbolsCommand(filePath, options) {
     if (!filePath) {
         throw new Error("Missing file path. Usage: ripple symbols <file>");
     }
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = engine.getFileSymbolsSummary(filePath);
@@ -2992,7 +3219,7 @@ async function blastCommand(filePath, options) {
         throw new Error("Missing file path. Usage: ripple blast <file>");
     }
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = engine.getBlastRadiusSummary(filePath);
@@ -3015,7 +3242,7 @@ async function dependencyCommand(filePath, direction, options) {
         throw new Error(`Missing file path. Usage: ripple ${direction} <file>`);
     }
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot);
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = engine.getFileDependencySummary(filePath);
@@ -3041,13 +3268,14 @@ async function focusCommand(filePath, options) {
         throw new Error("Missing file path. Usage: ripple focus <file>");
     }
     const workspaceRoot = resolveWorkspaceRoot(".");
-    const engine = new core_1.GraphEngine(workspaceRoot);
+    const engine = createCliEngine(workspaceRoot, "on-demand");
     try {
         await runWithQuietEngine(() => engine.initialScan());
         const summary = engine.getFileFocusSummary(filePath);
         if (!summary) {
             throw new Error(`File is not in the Ripple graph: ${filePath}`);
         }
+        engine.writeFileFocus(filePath);
         if (options.json) {
             printJson(summary);
         }
@@ -3087,6 +3315,10 @@ async function main() {
         await scanCommand(arg, options);
         return;
     }
+    if (command === "workflow") {
+        await workflowCommand(options);
+        return;
+    }
     if (command === "doctor") {
         await doctorCommand(options);
         return;