cclaw-cli 0.51.30 → 0.55.2

package/dist/content/hooks.js

@@ -26,7 +26,7 @@ function resolveCliRuntimeForGeneratedHook() {
     }
     return { entrypoint: null, argsPrefix: [] };
 }
-function internalHelperScript(helperName, internalSubcommand, usage) {
+function internalHelperScript(helperName, internalSubcommand, usage, options) {
     const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
@@ -40,6 +40,8 @@ const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 const HELPER_NAME = ${JSON.stringify(helperName)};
 const INTERNAL_SUBCOMMAND = ${JSON.stringify(internalSubcommand)};
 const USAGE = ${JSON.stringify(usage)};
+const POSITIONAL_ARG_NAME = ${JSON.stringify(options?.positionalArgName ?? null)};
+const POSITIONAL_ARG_REQUIRED = ${JSON.stringify(options?.positionalArgRequired === true)};
 
 async function detectRoot() {
   const candidates = [
@@ -69,11 +71,22 @@ function printUsage() {
 }
 
 async function main() {
-  const [, , ...flags] = process.argv;
-  if (flags.includes("--help") || flags.includes("-h")) {
+  const [, , ...argvTokens] = process.argv;
+  if (argvTokens.includes("--help") || argvTokens.includes("-h")) {
     printUsage();
     return;
   }
+  let positionalArg = "";
+  let flags = argvTokens;
+  if (POSITIONAL_ARG_NAME !== null) {
+    positionalArg = (argvTokens[0] ?? "").trim();
+    flags = argvTokens.slice(1);
+    if (POSITIONAL_ARG_REQUIRED && positionalArg.length === 0) {
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+  }
 
   const root = await detectRoot();
   const runtimePath = path.join(root, RUNTIME_ROOT);
@@ -112,7 +125,12 @@ async function main() {
     return;
   }
 
-  const child = spawn(process.execPath, [cliEntrypoint, ...cliArgsPrefix, "internal", INTERNAL_SUBCOMMAND, ...flags], {
+  const internalArgs =
+    POSITIONAL_ARG_NAME !== null
+      ? [INTERNAL_SUBCOMMAND, positionalArg, ...flags]
+      : [INTERNAL_SUBCOMMAND, ...flags];
+
+  const child = spawn(process.execPath, [cliEntrypoint, ...cliArgsPrefix, "internal", ...internalArgs], {
     cwd: root,
     env: process.env,
     stdio: "inherit"
@@ -124,7 +142,7 @@ async function main() {
     const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
     if (code === "ENOENT") {
       process.stderr.write(
-        "[cclaw] " + HELPER_NAME + ": node executable not found while invoking local runtime. Re-run npx cclaw-cli doctor.\\n"
+        "[cclaw] " + HELPER_NAME + ": node executable not found while invoking local runtime. Re-run npx cclaw-cli sync.\\n"
       );
     } else {
       process.stderr.write(
@@ -155,137 +173,14 @@ void main();
 export function startFlowScript() {
     return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]");
 }
-export function stageCompleteScript() {
-    const cliRuntime = resolveCliRuntimeForGeneratedHook();
-    return `#!/usr/bin/env node
-import fs from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { spawn } from "node:child_process";
-
-const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
-const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
-const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
-
-async function detectRoot() {
-  const candidates = [
-    process.env.CCLAW_PROJECT_ROOT,
-    process.env.CLAUDE_PROJECT_DIR,
-    process.env.CURSOR_PROJECT_DIR,
-    process.env.CURSOR_PROJECT_ROOT,
-    process.env.OPENCODE_PROJECT_DIR,
-    process.env.OPENCODE_PROJECT_ROOT,
-    process.cwd()
-  ].filter((value) => typeof value === "string" && value.length > 0);
-
-  for (const candidate of candidates) {
-    try {
-      const runtimePath = path.join(candidate, RUNTIME_ROOT);
-      const stat = await fs.stat(runtimePath);
-      if (stat.isDirectory()) return candidate;
-    } catch {
-      // continue
-    }
-  }
-  return candidates[0] || process.cwd();
+export function cancelRunScript() {
+    return internalHelperScript("cancel-run", "cancel-run", "Usage: node " + RUNTIME_ROOT + "/hooks/cancel-run.mjs --reason=<text> [--disposition=<cancelled|abandoned>] [--name=<slug>]");
 }
-
-function printUsage() {
-  process.stderr.write(
-    "Usage: node " +
-      RUNTIME_ROOT +
-      "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--json]\\n"
-  );
-}
-
-async function main() {
-  const [, , stage, ...flags] = process.argv;
-  if (!stage || stage.trim().length === 0) {
-    printUsage();
-    process.exitCode = 1;
-    return;
-  }
-
-  const root = await detectRoot();
-  const runtimePath = path.join(root, RUNTIME_ROOT);
-  try {
-    const stat = await fs.stat(runtimePath);
-    if (!stat.isDirectory()) throw new Error("not-dir");
-  } catch {
-    process.stderr.write("[cclaw] stage-complete: runtime root not found at " + runtimePath + "\\n");
-    process.exitCode = 1;
-    return;
-  }
-
-  const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
-  const cliArgsPrefix = process.env.CCLAW_CLI_JS ? [] : CCLAW_CLI_ARGS_PREFIX;
-  if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
-    process.stderr.write(
-      "[cclaw] stage-complete: local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  try {
-    const stat = await fs.stat(cliEntrypoint);
-    if (!stat.isFile()) throw new Error("not-file");
-    for (const argPath of cliArgsPrefix) {
-      if (typeof argPath !== "string" || argPath.startsWith("-")) continue;
-      const argStat = await fs.stat(argPath);
-      if (!argStat.isFile()) throw new Error("arg-not-file");
-    }
-  } catch {
-    process.stderr.write(
-      "[cclaw] stage-complete: local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  const child = spawn(
-    process.execPath,
-    [cliEntrypoint, ...cliArgsPrefix, "internal", "advance-stage", stage, ...flags],
-    {
-    cwd: root,
-    env: process.env,
-    stdio: "inherit"
-  }
-  );
-  let spawnErrored = false;
-
-  child.on("error", (error) => {
-    spawnErrored = true;
-    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
-    if (code === "ENOENT") {
-      process.stderr.write(
-        "[cclaw] stage-complete: node executable not found while invoking local runtime. Re-run npx cclaw-cli doctor.\\n"
-      );
-    } else {
-      process.stderr.write(
-        "[cclaw] stage-complete: failed to invoke local Node advance-stage runtime (" +
-          (error instanceof Error ? error.message : String(error)) +
-          ").\\n"
-      );
-    }
-    process.exitCode = 1;
-  });
-
-  child.on("close", (code, signal) => {
-    if (spawnErrored) {
-      process.exitCode = 1;
-      return;
-    }
-    if (signal) {
-      process.exitCode = 1;
-      return;
-    }
-    process.exitCode = typeof code === "number" && code >= 0 ? code : 1;
-  });
-}
-
-void main();
-`;
+export function stageCompleteScript() {
+    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=...] [--json]", {
+        positionalArgName: "stage",
+        positionalArgRequired: true
+    });
 }
 export function delegationRecordScript() {
     return `#!/usr/bin/env node
@@ -669,7 +564,7 @@ set "RUNTIME=%HOOK_DIR%run-hook.mjs"
 where node >nul 2>nul
 if %ERRORLEVEL% neq 0 (
   REM Best-effort: missing node should not block harness execution loops.
-  echo [cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli doctor. >&2
+  echo [cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli sync. >&2
   exit /b 0
 )
 node "%RUNTIME%" %*
@@ -681,7 +576,7 @@ if [ "$#" -lt 1 ]; then
   exit 1
 fi
 if ! command -v node >/dev/null 2>&1; then
-  echo "[cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli doctor." >&2
+  echo "[cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli sync." >&2
   exit 0
 fi
 exec node "\${SCRIPT_DIR}/run-hook.mjs" "$@"

package/dist/content/idea-command.d.ts

@@ -0,0 +1,8 @@
+import { type IdeaFrameId } from "./idea-frames.js";
+export interface IdeaCommandOptions {
+    frameIds?: readonly IdeaFrameId[];
+    mode?: "repo-grounded" | "elsewhere-software" | "elsewhere-non-software" | "narrow";
+}
+export declare function minimumDistinctIdeaFrames(frameCount: number, mode?: IdeaCommandOptions["mode"]): number;
+export declare function ideaCommandContract(options?: IdeaCommandOptions): string;
+export declare function ideaCommandSkillMarkdown(options?: IdeaCommandOptions): string;

package/dist/content/{ideate-command.js → idea-command.js}

@@ -1,43 +1,43 @@
 import { RUNTIME_ROOT } from "../constants.js";
-import { resolveIdeateFrames } from "./ideate-frames.js";
-import { ideateStructuredAskToolsWithFallback } from "./decision-protocol.js";
+import { resolveIdeaFrames } from "./idea-frames.js";
+import { ideaStructuredAskToolsWithFallback } from "./decision-protocol.js";
 import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
-const IDEATE_SKILL_FOLDER = "flow-ideate";
-const IDEATE_SKILL_NAME = "flow-ideate";
+const IDEA_SKILL_FOLDER = "flow-idea";
+const IDEA_SKILL_NAME = "flow-idea";
 /**
- * Directory + filename convention for ideate artifacts. These are separate
- * from stage artifacts (00-..08-*.md) because `/cc-ideate` runs outside the
+ * Directory + filename convention for idea artifacts. These are separate
+ * from stage artifacts (00-..08-*.md) because `/cc-idea` runs outside the
  * critical-path flow state machine and must not collide with stage numbering.
  */
-const IDEATE_ARTIFACT_GLOB = ".cclaw/artifacts/ideate-*.md";
-const IDEATE_ARTIFACT_PATTERN = ".cclaw/artifacts/ideate-<YYYY-MM-DD-slug>.md";
-const IDEATE_RESUME_WINDOW_DAYS = 30;
-const STRUCTURED_ASK_TOOLS = ideateStructuredAskToolsWithFallback();
-export function minimumDistinctIdeateFrames(frameCount, mode = "repo-grounded") {
+const IDEA_ARTIFACT_GLOB = ".cclaw/artifacts/idea-*.md";
+const IDEA_ARTIFACT_PATTERN = ".cclaw/artifacts/idea-<YYYY-MM-DD-slug>.md";
+const IDEA_RESUME_WINDOW_DAYS = 30;
+const STRUCTURED_ASK_TOOLS = ideaStructuredAskToolsWithFallback();
+export function minimumDistinctIdeaFrames(frameCount, mode = "repo-grounded") {
     if (frameCount <= 0)
         return 0;
     const cap = mode === "repo-grounded" ? 4 : 2;
     return Math.min(cap, frameCount);
 }
 function renderFrameBullets(frameIds) {
-    return resolveIdeateFrames(frameIds)
+    return resolveIdeaFrames(frameIds)
         .map((frame) => `   - ${frame.label} (\`${frame.id}\`)`)
         .join("\n");
 }
 function renderFrameNames(frameIds) {
-    return resolveIdeateFrames(frameIds)
+    return resolveIdeaFrames(frameIds)
         .map((frame) => frame.label)
         .join(", ");
 }
-export function ideateCommandContract(options = {}) {
-    const frames = resolveIdeateFrames(options.frameIds);
+export function ideaCommandContract(options = {}) {
+    const frames = resolveIdeaFrames(options.frameIds);
     const frameBullets = renderFrameBullets(options.frameIds);
-    const minimumDistinctFrames = minimumDistinctIdeateFrames(frames.length, options.mode);
-    return `# /cc-ideate
+    const minimumDistinctFrames = minimumDistinctIdeaFrames(frames.length, options.mode);
+    return `# /cc-idea
 
 ## Purpose
 
-Repository-improvement ideate mode. Generate a ranked backlog of
+Repository-improvement idea mode. Generate a ranked backlog of
 high-value improvements, persist it as an artifact on disk, and end with
 an explicit handoff — either launch \`/cc\` on a chosen candidate in the
 same session, or save/discard the backlog.
@@ -45,18 +45,20 @@ same session, or save/discard the backlog.
 ## HARD-GATE
 
 ${conversationLanguagePolicyMarkdown()}
-- Ideate mode only. Never mutate \`.cclaw/state/flow-state.json\`.
+- Idea mode only. Never mutate \`.cclaw/state/flow-state.json\`.
 - Every recommendation cites evidence from the current repository
   (file path, command output, or knowledge-store entry id).
-- Always write a persisted artifact to
-  \`${IDEATE_ARTIFACT_PATTERN}\`. Chat-only output is not acceptable —
-  the next session must be able to resume.
-- Always end with a structured handoff prompt, not an open question.
+- Whenever you produce ideation output, persist it to
+  \`${IDEA_ARTIFACT_PATTERN}\`. Chat-only output is not acceptable.
+  The only exception is an explicit user-cancel from the resume prompt —
+  in that case, write nothing and exit silently.
+- Always end with a structured handoff prompt, not an open question
+  (skipped on explicit cancel).
 
 ## Algorithm
 
-1. **Resume check.** Glob \`${IDEATE_ARTIFACT_GLOB}\`. If any artifact
-   has been modified within the last ${IDEATE_RESUME_WINDOW_DAYS} days,
+1. **Resume check.** Glob \`${IDEA_ARTIFACT_GLOB}\`. If any artifact
+   has been modified within the last ${IDEA_RESUME_WINDOW_DAYS} days,
    offer the user: continue that backlog, start fresh, or cancel.
 2. **Mode classification.** Explicitly classify subject:
    \`repo-grounded\` / \`elsewhere-software\` / \`elsewhere-non-software\` / \`narrow\`.
@@ -83,7 +85,7 @@ ${frameBullets}
    \`(impact points / effort cost) * confidence multiplier\` and recommend
    the top survivor.
 8. **Write the artifact** at
-   \`${IDEATE_ARTIFACT_PATTERN}\` using the schema in the skill.
+   \`${IDEA_ARTIFACT_PATTERN}\` using the schema in the skill.
 8.5 **Seed shelf (optional).** For critiqued-out or deferred ideas that still
    show upside, write seed notes to
    \`${RUNTIME_ROOT}/seeds/SEED-<YYYY-MM-DD>-<slug>.md\` with
@@ -91,61 +93,66 @@ ${frameBullets}
 9. **Present the handoff prompt** with four concrete options — not A/B/C
    letters. Default = "Start /cc on the top recommendation".
 
-## Headless mode
+## Headless mode (CI/automation only)
 
+Headless envelopes are a machine-mode exception for CI/automation orchestration.
+In normal interactive ideation, respond with natural language plus the artifact path.
 For skill-to-skill invocation, emit exactly one JSON envelope:
 
 \`\`\`json
-{"version":"1","kind":"stage-output","stage":"non-flow","payload":{"command":"/cc-ideate","artifact":".cclaw/artifacts/ideate-<date>-<slug>.md","recommendation":"I-1"},"emittedAt":"<ISO-8601>"}
+{"version":"1","kind":"stage-output","stage":"non-flow","payload":{"command":"/cc-idea","artifact":".cclaw/artifacts/idea-<date>-<slug>.md","recommendation":"I-1"},"emittedAt":"<ISO-8601>"}
 \`\`\`
 
 Validate envelopes with:
-\`cclaw internal envelope-validate --stdin\`
+\`npx cclaw-cli internal envelope-validate --stdin\`
 
 ## Primary skill
 
-   **${RUNTIME_ROOT}/skills/${IDEATE_SKILL_FOLDER}/SKILL.md**
+   **${RUNTIME_ROOT}/skills/${IDEA_SKILL_FOLDER}/SKILL.md**
 `;
 }
-export function ideateCommandSkillMarkdown(options = {}) {
-    const frames = resolveIdeateFrames(options.frameIds);
+export function ideaCommandSkillMarkdown(options = {}) {
+    const frames = resolveIdeaFrames(options.frameIds);
     const frameBullets = renderFrameBullets(options.frameIds);
-    const minimumDistinctFrames = minimumDistinctIdeateFrames(frames.length, options.mode);
+    const minimumDistinctFrames = minimumDistinctIdeaFrames(frames.length, options.mode);
     const frameNames = renderFrameNames(options.frameIds);
     return `---
-name: ${IDEATE_SKILL_NAME}
-description: "Repository ideate mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
+name: ${IDEA_SKILL_NAME}
+description: "Repository idea mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
 ---
 
-# /cc-ideate
+# /cc-idea
 
 ## Announce at start
 
-"Using flow-ideate to identify highest-leverage improvements in this
+"Using flow-idea to identify highest-leverage improvements in this
 repository. Will persist a ranked backlog to
-\`${IDEATE_ARTIFACT_PATTERN}\` and end with an explicit handoff."
+\`${IDEA_ARTIFACT_PATTERN}\` and end with an explicit handoff."
 
 ## HARD-GATE
 
 ${conversationLanguagePolicyMarkdown()}
-- Do not start coding in ideate mode.
-- Do not mutate \`.cclaw/state/flow-state.json\` — ideate mode sits outside
+- Do not start coding in idea mode.
+- Do not mutate \`.cclaw/state/flow-state.json\` — idea mode sits outside
   the critical-path flow.
-- Always produce the artifact file on disk before presenting the handoff.
+- Whenever ideation output is produced, persist the artifact file on disk
+  before presenting the handoff. The only exception is an explicit user-cancel
+  from the resume prompt — in that case, write nothing and exit silently.
 - Always end with a structured handoff that names the concrete follow-up
-  command for each option. No A/B/C letters without command context.
+  command for each option (skipped on explicit cancel). No A/B/C letters
+  without command context.
 
 ## Protocol
 
 ### Phase 0 — Resume and classify
 
 1. Use the harness's file-glob tool (\`Glob\` pattern
-   \`${IDEATE_ARTIFACT_GLOB}\` or equivalent \`ls\`/\`find\`).
-2. Filter to files modified within the last ${IDEATE_RESUME_WINDOW_DAYS} days.
+   \`${IDEA_ARTIFACT_GLOB}\` or equivalent \`ls\`/\`find\`).
+2. Filter to files modified within the last ${IDEA_RESUME_WINDOW_DAYS} days.
 3. If one or more match, present **one** structured ask using the
    harness's native tool (${STRUCTURED_ASK_TOOLS}) with options:
    - **Continue the existing backlog** — read the most-recent
-     ideate-*.md and work from its candidate list; skip re-scanning.
+     idea-*.md and work from its candidate list; skip re-scanning.
    - **Start a fresh scan** — proceed to Phase 1; the old artifact stays
      on disk for history.
    - **Cancel** — stop; do not scan or write anything.
@@ -218,10 +225,10 @@ Only survivors advance to ranking.
    and break ties with rationale strength.
 4. Compute the artifact filename:
    - \`slug\` = first 3–5 words of the top recommendation, lowercase,
-     non-alphanumeric collapsed to \`-\`, trimmed. When ideate mode is
+     non-alphanumeric collapsed to \`-\`, trimmed. When idea mode is
      focus-hinted (user passed an argument), use the focus hint instead.
    - \`date\` = today in \`YYYY-MM-DD\` (local time).
-   - Path = \`.cclaw/artifacts/ideate-<date>-<slug>.md\`.
+   - Path = \`.cclaw/artifacts/idea-<date>-<slug>.md\`.
 5. Use the harness's write-file tool (\`Write\`, \`apply_patch\`, or shell
    \`cat <<EOF > path\`) to create the artifact with this schema:
 
@@ -269,7 +276,7 @@ Only survivors advance to ranking.
 6. Optional: for promising non-selected ideas, write
    \`${RUNTIME_ROOT}/seeds/SEED-<YYYY-MM-DD>-<slug>.md\` entries with:
    \`title\`, \`trigger_when\`, \`hypothesis\`, \`action\`, and
-   \`source_artifact\` = ideate artifact path.
+   \`source_artifact\` = idea artifact path.
 7. Confirm in chat: "Wrote <path>."
 
 ### Phase 5 — Handoff prompt
@@ -286,7 +293,7 @@ Required options, in this order:
 2. **Pick a different candidate** — the agent asks which ID (I-2, I-3, …)
    and then invokes \`/cc <that candidate's handoff phrase>\`.
 3. **Save and close** — leave the artifact on disk, do nothing else.
-   Next session: \`/cc-ideate\` will offer to resume it.
+   Next session: \`/cc-idea\` will offer to resume it.
 4. **Discard** — delete the just-written artifact. Use only when the
    scan produced nothing actionable.
 
@@ -298,7 +305,7 @@ lettered list with the same four labels. Do not invent extra options.
 - **Start /cc on I-1** or **different candidate:** announce
   "Handing off to /cc <phrase>" and load the \`using-cclaw\` router
   skill. From there, the normal \`/cc\` classification and stage flow
-  takes over. Do not produce a second artifact; the ideate file is
+  takes over. Do not produce a second artifact; the idea file is
   preserved as the origin document for this run.
 - **Save and close:** reply with the artifact path and stop.
 - **Discard:** delete the artifact file, confirm deletion, stop.

package/dist/content/idea-frames.d.ts

@@ -0,0 +1,31 @@
+export type IdeaFrameId = "pain-friction" | "inversion" | "assumption-break" | "leverage" | "cross-domain-analogy" | "constraint-flip";
+export interface IdeaFrame {
+    id: IdeaFrameId;
+    label: string;
+    prompt: string;
+    examplePatterns: string[];
+}
+export interface IdeaFrameDispatchInput {
+    focus: string;
+    mode: "repo-grounded" | "elsewhere-software" | "elsewhere-non-software";
+    signalSummary: string[];
+}
+export interface IdeaFrameDispatchPlanEntry {
+    frameId: IdeaFrameId;
+    label: string;
+    prompt: string;
+}
+export interface IdeaCandidateDraft {
+    title: string;
+    evidencePath: string;
+    summary: string;
+    frameId: IdeaFrameId;
+}
+export interface IdeaCandidateMerged extends Omit<IdeaCandidateDraft, "frameId"> {
+    frameIds: IdeaFrameId[];
+}
+export declare const DEFAULT_IDEA_FRAME_IDS: readonly IdeaFrameId[];
+export declare const IDEA_FRAMES: readonly IdeaFrame[];
+export declare function resolveIdeaFrames(frameIds?: readonly IdeaFrameId[]): IdeaFrame[];
+export declare function buildIdeaFrameDispatchPlan(input: IdeaFrameDispatchInput, frameIds?: readonly IdeaFrameId[]): IdeaFrameDispatchPlanEntry[];
+export declare function dedupeIdeaCandidates(drafts: readonly IdeaCandidateDraft[]): IdeaCandidateMerged[];

package/dist/content/{ideate-frames.js → idea-frames.js}

@@ -60,7 +60,7 @@ const FRAME_REGISTRY = {
         ]
     }
 };
-export const DEFAULT_IDEATE_FRAME_IDS = Object.freeze([
+export const DEFAULT_IDEA_FRAME_IDS = Object.freeze([
     "pain-friction",
     "inversion",
     "assumption-break",
@@ -68,16 +68,16 @@ export const DEFAULT_IDEATE_FRAME_IDS = Object.freeze([
     "cross-domain-analogy",
     "constraint-flip"
 ]);
-export const IDEATE_FRAMES = Object.freeze(DEFAULT_IDEATE_FRAME_IDS.map((id) => FRAME_REGISTRY[id]));
-export function resolveIdeateFrames(frameIds) {
+export const IDEA_FRAMES = Object.freeze(DEFAULT_IDEA_FRAME_IDS.map((id) => FRAME_REGISTRY[id]));
+export function resolveIdeaFrames(frameIds) {
     if (!frameIds || frameIds.length === 0) {
-        return [...IDEATE_FRAMES];
+        return [...IDEA_FRAMES];
     }
     const seen = new Set();
     const resolved = [];
     for (const rawId of frameIds) {
-        if (!DEFAULT_IDEATE_FRAME_IDS.includes(rawId)) {
-            throw new Error(`Unknown ideate frame id: ${rawId}`);
+        if (!DEFAULT_IDEA_FRAME_IDS.includes(rawId)) {
+            throw new Error(`Unknown idea frame id: ${rawId}`);
         }
         if (seen.has(rawId))
             continue;
@@ -86,11 +86,11 @@ export function resolveIdeateFrames(frameIds) {
     }
     return resolved;
 }
-export function buildIdeateFrameDispatchPlan(input, frameIds) {
+export function buildIdeaFrameDispatchPlan(input, frameIds) {
     const signalBlock = input.signalSummary.length > 0
         ? input.signalSummary.map((line) => `- ${line}`).join("\n")
         : "- no pre-scan signals captured yet";
-    return resolveIdeateFrames(frameIds).map((frame) => ({
+    return resolveIdeaFrames(frameIds).map((frame) => ({
         frameId: frame.id,
         label: frame.label,
         prompt: [
@@ -115,7 +115,7 @@ function normalizeCandidateKey(title, evidencePath) {
         .replace(/\\/gu, "/");
     return `${normalizedTitle}::${normalizedEvidence}`;
 }
-export function dedupeIdeateCandidates(drafts) {
+export function dedupeIdeaCandidates(drafts) {
     const merged = new Map();
     for (const draft of drafts) {
         const key = normalizeCandidateKey(draft.title, draft.evidencePath);

package/dist/content/idea-ranking.d.ts

@@ -0,0 +1,25 @@
+export type IdeaImpact = "high" | "medium" | "low";
+export type IdeaEffort = "s" | "m" | "l";
+export type IdeaConfidence = "high" | "medium" | "low";
+export interface IdeaCandidateEvaluationInput {
+    id: string;
+    title: string;
+    impact: IdeaImpact;
+    effort: IdeaEffort;
+    confidence: IdeaConfidence;
+    rationaleStrength: number;
+    counterArgumentStrength: number;
+}
+export interface IdeaCandidateEvaluation extends IdeaCandidateEvaluationInput {
+    disposition: "survivor" | "critiqued-out";
+    rankingScore: number;
+}
+export interface IdeaRankingResult {
+    survivors: IdeaCandidateEvaluation[];
+    critiquedOut: IdeaCandidateEvaluation[];
+    recommendationId: string | null;
+}
+export declare function isCritiquedOut(rationaleStrength: number, counterArgumentStrength: number): boolean;
+export declare function scoreIdeaCandidate(impact: IdeaImpact, effort: IdeaEffort, confidence: IdeaConfidence): number;
+export declare function evaluateIdeaCandidate(input: IdeaCandidateEvaluationInput): IdeaCandidateEvaluation;
+export declare function rankIdeaCandidates(inputs: readonly IdeaCandidateEvaluationInput[], maxSurvivors?: number): IdeaRankingResult;

package/dist/content/{ideate-ranking.js → idea-ranking.js}

@@ -25,22 +25,22 @@ function clampStrength(value) {
 export function isCritiquedOut(rationaleStrength, counterArgumentStrength) {
     return clampStrength(counterArgumentStrength) > clampStrength(rationaleStrength);
 }
-export function scoreIdeateCandidate(impact, effort, confidence) {
+export function scoreIdeaCandidate(impact, effort, confidence) {
     const raw = (IMPACT_POINTS[impact] / EFFORT_COST[effort]) * CONFIDENCE_MULTIPLIER[confidence];
     return Number(raw.toFixed(3));
 }
-export function evaluateIdeateCandidate(input) {
+export function evaluateIdeaCandidate(input) {
     const disposition = isCritiquedOut(input.rationaleStrength, input.counterArgumentStrength)
         ? "critiqued-out"
         : "survivor";
     return {
         ...input,
         disposition,
-        rankingScore: scoreIdeateCandidate(input.impact, input.effort, input.confidence)
+        rankingScore: scoreIdeaCandidate(input.impact, input.effort, input.confidence)
     };
 }
-export function rankIdeateCandidates(inputs, maxSurvivors = 10) {
-    const evaluated = inputs.map(evaluateIdeateCandidate);
+export function rankIdeaCandidates(inputs, maxSurvivors = 10) {
+    const evaluated = inputs.map(evaluateIdeaCandidate);
     const survivors = evaluated
         .filter((candidate) => candidate.disposition === "survivor")
         .sort((left, right) => {

package/dist/content/iron-laws.d.ts

@@ -138,5 +138,4 @@ export declare function ironLawRuntimeDocument(options?: {
     strictLaws?: string[];
     nowIso?: string;
 }): IronLawRuntimeDocument;
-export declare function ironLawsAgentsMdBlock(): string;
 export declare function ironLawsSkillMarkdown(): string;