@ozzylabs/feedradar 0.1.6 → 0.1.8

package/dist/cli/research.js

@@ -17,11 +17,14 @@ const matterOptions = {
         },
     },
 };
+import { renderResearchPayloadBlock } from "../agents/_boundary.js";
 import { getAgentAdapter } from "../agents/index.js";
 import { getDefaultAgent, loadRadarConfig, RadarConfigError } from "../core/config.js";
 import { loadItems, saveItems } from "../core/items.js";
 import { loadTemplate } from "../core/templates.js";
-import { AgentIdSchema, ItemStatusSchema, ResearchFrontmatterSchema } from "../schemas/index.js";
+import { isValidTransition } from "../core/transitions.js";
+import { AgentIdSchema, ResearchFrontmatterSchema } from "../schemas/index.js";
+import { resolveCommitPathInside } from "./_commit-path.js";
 import { buildAgentProgressCallback, buildReporter, ProgressFlagError, parseProgressFlags, pollOutputFileSize, } from "./_progress.js";
 /**
  * Default hard-cap for `radar research --batch`.
@@ -33,6 +36,27 @@ import { buildAgentProgressCallback, buildReporter, ProgressFlagError, parseProg
  * cap also applies when the YAML is hand-edited.
  */
 export const RESEARCH_BATCH_DEFAULT_MAX_ITEMS = 10;
+/**
+ * Whitelist of `Item.status` values accepted by `radar research --batch
+ * --status <status>`.
+ *
+ * Constrained to the two "ready-to-research" statuses defined by the
+ * ADR-0008 / ADR-0018 state machine:
+ *
+ *   - `detected`         — legacy pre-triage path (`radar research` directly)
+ *   - `triaged_research` — triage adapter promoted the item for research
+ *                          (ADR-0018 §W-B); workflow YAML generated by
+ *                          `radar workflow generate combined-with-triage`
+ *                          drives this branch (PR #249).
+ *
+ * Other statuses (`researched`, `reviewed`, `dismissed`, `triaged_digest`,
+ * `triaged_unsure`) are rejected with an explicit error rather than silently
+ * matching zero items, so a typo in scheduled YAML fails loud instead of
+ * decaying into a silent no-op (issue #250). `triaged_digest` requires
+ * `--digest` aggregation per group and is intentionally not a `--batch`
+ * single-item input; the workflow YAML walks groups explicitly.
+ */
+export const RESEARCH_BATCH_ALLOWED_STATUSES = ["detected", "triaged_research"];
 function parseArgs(args) {
     const out = { itemIds: [] };
     for (let i = 0; i < args.length; i++) {
@@ -69,6 +93,18 @@ function parseArgs(args) {
             out.filterTags = args[++i];
             continue;
         }
+        if (a === "--triage-group") {
+            out.triageGroup = args[++i];
+            continue;
+        }
+        if (a === "--emit-payload") {
+            out.emitPayload = true;
+            continue;
+        }
+        if (a === "--commit") {
+            out.commit = args[++i];
+            continue;
+        }
         if (a?.startsWith("--")) {
             throw new Error(`unknown option: ${a}`);
         }
@@ -81,8 +117,10 @@ function parseArgs(args) {
 function printHelp(log) {
     log("Usage:");
     log("  radar research <item-id> [--agent <agent-id>] [--template <template-id>]");
-    log("  radar research --digest <item-id> <item-id> ... [--agent <agent-id>] [--template <id>]");
+    log("  radar research --digest <item-id> <item-id> ... [--triage-group <group>] [--agent <agent-id>] [--template <id>]");
     log(`  radar research --batch [--status <status>] [--max-items N] [--filter-tags <list>] [--agent <id>]`);
+    log("  radar research <item-id> --emit-payload [--digest <ids...>] [--template <id>]");
+    log("  radar research --commit <path>");
     log("");
     log("Arguments:");
     log("  <item-id>             Item id (matches items/<sourceId>/<item-id>.yaml)");
@@ -93,15 +131,30 @@ function printHelp(log) {
     log("  --agent <agent-id>    claude-code | codex-cli | gemini-cli | copilot (default: claude-code)");
     log("  --template <id>       Template id under templates/ (default: default; digest: digest)");
     log("  --digest              Bundle multiple items into a single digest report (ADR-0011)");
+    log("  --triage-group <group> Digest-mode slug source (ADR-0018 §W-H): name the digest");
+    log("                        file after this triage.group instead of the matchedKeywords");
+    log("                        frequency. Required to keep per-group digests unique on the");
+    log("                        same day when a single-keyword source emits multiple groups");
+    log("                        (#255). Falls back to the matchedKeywords slug when omitted.");
     log("  --batch               Research every item matching --status (and --filter-tags)");
     log("                        respecting the --max-items hard-cap (ADR-0014 D3a).");
-    log("  --status <status>     Batch-mode filter: detected | researched | reviewed | dismissed");
-    log("                        (default: detected).");
+    log("  --status <status>     Batch-mode filter: detected | triaged_research");
+    log("                        (default: detected). `triaged_research` consumes items");
+    log("                        the triage adapter promoted (ADR-0018 §W-B) and");
+    log("                        transitions them to `researched` on success.");
     log(`  --max-items N         Batch-mode hard-cap on processed items (default: ${RESEARCH_BATCH_DEFAULT_MAX_ITEMS}).`);
     log("                        Excess items are dropped and announced via warn() so a runaway");
     log("                        detection cannot blow the cap from inside a workflow.");
     log("  --filter-tags <list>  Batch-mode comma-separated allow-list matched against");
     log("                        each item's matchedKeywords (case-insensitive). Default: all.");
+    log("  --emit-payload        Host-agent mode (ADR-0019): print the research payload to");
+    log("                        stdout and DO NOT spawn an agent. The interactive host");
+    log("                        session runs the SKILL procedure itself, then finalizes");
+    log("                        with `radar research --commit <path>`. Interactive/opt-in");
+    log("                        only — CI/headless must use the default spawn path.");
+    log("  --commit <path>       Host-agent mode (ADR-0019): validate an externally-written");
+    log("                        report (under <cwd>/research/) against ResearchFrontmatter-");
+    log("                        Schema and apply the detected → researched transition.");
     log("  --verbose             Stream the agent CLI's stdout/stderr in addition to phase markers.");
     log("  --quiet               Suppress phase markers and spinner; print only the completion line.");
     log("                        Equivalent to setting RADAR_NO_PROGRESS=1 (ADR-0015 D2).");
@@ -154,7 +207,26 @@ function clampSlug(s, max = 60) {
     const lastHyphen = cut.lastIndexOf("-");
     return lastHyphen > 0 ? cut.slice(0, lastHyphen) : cut;
 }
-function deriveDigestSlug(items) {
+/**
+ * Derive the `<slug>` segment of a digest filename
+ * (`<date>_digest_<slug>_v1.md`, ADR-0011 §2).
+ *
+ * Resolution order (#255):
+ *
+ *   1. `triageGroup` override (explicit `--triage-group`, or — when omitted —
+ *      a single `triage.group` shared by every item). The triage workflow
+ *      digests one group per `radar research --digest` call, so this is the
+ *      semantically correct discriminator. Crucially it keeps two same-day
+ *      groups distinct even when a single-keyword source gives every item the
+ *      same `matchedKeywords` (which the frequency slug below cannot).
+ *   2. `matchedKeywords` frequency (top-2). Back-compat path for callers that
+ *      do not carry triage groups (e.g. ad-hoc `radar research --digest a b`).
+ *   3. Literal `"digest"` when neither yields anything.
+ */
+function deriveDigestSlug(items, triageGroup) {
+    const groupSlug = resolveTriageGroupSlug(items, triageGroup);
+    if (groupSlug !== undefined)
+        return clampSlug(groupSlug);
     const freq = new Map();
     for (const item of items) {
         for (const kw of item.matchedKeywords) {
@@ -172,6 +244,32 @@ function deriveDigestSlug(items) {
         return "digest";
     return clampSlug(top.map(kebabCase).join("-"));
 }
+/**
+ * Pick the triage-group slug for {@link deriveDigestSlug}, or `undefined` when
+ * no group applies (so the matchedKeywords fallback runs).
+ *
+ * An explicit `triageGroup` always wins. Otherwise we only use a group when
+ * every item agrees on a single non-empty `triage.group`: a mixed set has no
+ * unambiguous group to name the file after, so we defer to the keyword slug.
+ */
+function resolveTriageGroupSlug(items, triageGroup) {
+    const explicit = triageGroup?.trim();
+    if (explicit !== undefined && explicit !== "") {
+        const slug = kebabCase(explicit);
+        return slug === "" ? undefined : slug;
+    }
+    const groups = new Set();
+    for (const item of items) {
+        const g = item.triage?.group?.trim();
+        if (g === undefined || g === "")
+            return undefined;
+        groups.add(g);
+    }
+    if (groups.size !== 1)
+        return undefined;
+    const slug = kebabCase([...groups][0]);
+    return slug === "" ? undefined : slug;
+}
 async function findItem(cwd, itemId) {
     const itemsDir = join(cwd, "items");
     if (!(await pathExists(itemsDir)))
@@ -223,8 +321,18 @@ async function resolveAgent(cwd, rawAgent, error) {
         throw e;
     }
 }
-async function processResearchInvocation(params) {
-    const { cwd, items, digest, agent, templateId, template, now, log, warn, error, progress } = params;
+/**
+ * PRE block (shared by the spawn path and `--emit-payload`): emit injection
+ * warnings, derive the deterministic `outputPath`, and guard against
+ * overwriting an existing report. Returns the resolved path or an `exitCode`
+ * for the caller to propagate.
+ *
+ * Extracted from `processResearchInvocation` so the host-agent emit path
+ * (#254 / ADR-0019) computes the exact same `outputPath` and reuses the same
+ * collision backstop as the spawn path, without the model-call step.
+ */
+async function prepareResearch(params) {
+    const { cwd, items, digest, templateId, now, triageGroup, warn, error, progress } = params;
     for (const item of items) {
         if (item.injectionFlags.length > 0) {
             warn(`research: item '${item.id}' has ${item.injectionFlags.length} injection flag(s): ${item.injectionFlags.join(", ")} (audit-only; use \`radar dismiss\` to skip)`);
@@ -233,7 +341,7 @@ async function processResearchInvocation(params) {
     let filename;
     if (digest) {
         const datePrefix = buildDigestDatePrefix(now);
-        const slug = deriveDigestSlug(items);
+        const slug = deriveDigestSlug(items, triageGroup);
         filename = `${datePrefix}_digest_${slug}_v1.md`;
     }
     else {
@@ -245,11 +353,8 @@ async function processResearchInvocation(params) {
     const outputPath = join(cwd, "research", filename);
     if (await pathExists(outputPath)) {
         error(`research: ${outputPath} already exists (use \`radar update\` to re-research)`);
-        return 1;
+        return { exitCode: 1 };
     }
-    const itemDescription = digest
-        ? `${items.length} items (${items.map((i) => i.id).join(", ")})`
-        : `item '${items[0].id}'`;
     // Phase marker: items resolved (ADR-0015 D4 "Loaded <noun>"). One marker
     // per invocation regardless of digest cardinality so the progress stream
     // stays uniform between single / digest / batch modes.
@@ -257,42 +362,28 @@ async function processResearchInvocation(params) {
     // Phase marker: template resolved. Echoes the actual template id so a
     // user running `--template deep-dive` sees the value flow through.
     progress.phase(`Loaded template: ${templateId}.md`);
-    log(`research: invoking ${agent} adapter for ${itemDescription} -> ${filename}`);
-    const adapter = getAgentAdapter(agent);
-    // Phase marker + spinner: agent spawn. We pair `phase("Spawning …")` with
-    // `start("Agent running…")` so the marker is printed once for scrollback
-    // and the spinner row carries the live `[mm:ss]` heartbeat + metrics.
-    progress.phase(`Spawning ${agent}`, `cwd: ${cwd}`);
-    progress.start("Agent running");
-    const adapterStartedAt = Date.now();
-    const polling = pollOutputFileSize({ path: outputPath, reporter: progress });
-    let adapterExitCode = 0;
-    try {
-        await adapter.research({
-            agent,
-            templateId,
-            templateBody: template.body,
-            items,
-            outputPath,
-            cwd,
-            onProgress: buildAgentProgressCallback(progress),
-        });
-    }
-    catch (e) {
-        adapterExitCode = 1;
-        polling.stop();
-        progress.fail("Agent failed", e instanceof Error ? e.message : String(e));
-        error(`research: adapter failed: ${e instanceof Error ? e.message : String(e)}`);
-        return 1;
-    }
-    finally {
-        polling.stop();
-    }
-    if (adapterExitCode === 0) {
-        progress.succeed(`Agent completed (exit ${adapterExitCode})`, Date.now() - adapterStartedAt);
-    }
+    return { outputPath, filename };
+}
+/**
+ * POST block (shared by the spawn path and `--commit`): validate the written
+ * report against `ResearchFrontmatterSchema`, reset Phase-1-contract drift,
+ * and apply the `detected → researched` status transition.
+ *
+ * This is the single source of truth for "finalize" so the spawn and
+ * host-agent paths (#254 / ADR-0019) cannot diverge on schema validation or
+ * the state-machine transition — the acceptance-condition that the CLI keeps
+ * owning both is satisfied structurally, not by a second copy of the logic.
+ *
+ * `items` is the transition target set. The spawn path passes the items it
+ * already resolved; `--commit` passes `undefined` and lets finalize derive the
+ * set from the report's `itemIds` frontmatter (reverse-lookup against
+ * `items/`), so a host-written digest with multiple `itemIds` transitions all
+ * of them.
+ */
+async function finalizeResearch(params) {
+    const { cwd, outputPath, log, warn, error, progress } = params;
     if (!(await pathExists(outputPath))) {
-        error(`research: adapter completed but did not write ${outputPath} (agent ignored the output path?)`);
+        error(`research: report was not written to ${outputPath} (did not write the output path?)`);
         return 1;
     }
     let body;
@@ -341,7 +432,49 @@ async function processResearchInvocation(params) {
         }, matterOptions);
         await writeFile(outputPath, rewritten, "utf8");
     }
-    const updated = items.map((item) => item.status === "detected" ? { ...item, status: "researched" } : item);
+    // Resolve the transition target set. Spawn passes the items it already
+    // loaded; `--commit` derives them from the report's `itemIds` frontmatter so
+    // the host-written file is self-describing (digest reports transition every
+    // linked item).
+    let targetItems;
+    if (params.items !== undefined) {
+        targetItems = params.items;
+    }
+    else {
+        const all = await loadItems(join(cwd, "items"));
+        const byId = new Map(all.map((i) => [i.id, i]));
+        const resolved = [];
+        for (const id of fmResult.data.itemIds) {
+            const match = byId.get(id);
+            if (!match) {
+                error(`research: --commit report references unknown item id '${id}' (no items/*/${id}.yaml under ${cwd})`);
+                return 1;
+            }
+            resolved.push(match);
+        }
+        targetItems = resolved;
+    }
+    // Defer the "which prior statuses can transition into `researched`"
+    // decision to `isValidTransition()` (src/core/transitions.ts). That
+    // module enumerates the ADR-0008 / ADR-0018 state machine edges in one
+    // place; re-deriving the rule here would risk drift the next time the
+    // matrix changes (e.g. a future `triaged_*` status).
+    //
+    // Today this resolves to {detected, triaged_research, triaged_digest} →
+    // researched. Items in any other status (already researched, dismissed,
+    // terminal reviewed, etc.) are passed through unchanged: the batch
+    // filter upstream enforces input selection, and this guard is defense
+    // in depth for the single-item path where a user invokes
+    // `radar research <item-id>` against an item already past the
+    // pre-research stage.
+    const transitions = new Map();
+    const updated = targetItems.map((item) => {
+        if (isValidTransition(item.status, "researched")) {
+            transitions.set(item.id, item.status);
+            return { ...item, status: "researched" };
+        }
+        return item;
+    });
     try {
         await saveItems(join(cwd, "items"), updated);
     }
@@ -352,16 +485,131 @@ async function processResearchInvocation(params) {
     }
     log(`research: wrote ${outputPath}`);
     for (const item of updated) {
-        if (item.status === "researched") {
+        const from = transitions.get(item.id);
+        if (from !== undefined && item.status === "researched") {
             // Phase marker: status transition. We emit one phase per item rather
             // than collapsing them so the digest case stays explicit about what
             // moved. The arrow uses U+2192 (→) per ADR-0015 D4 examples.
-            progress.phase(`Status: detected → researched`, `items/${item.sourceId}/${item.id}.yaml`);
+            progress.phase(`Status: ${from} → researched`, `items/${item.sourceId}/${item.id}.yaml`);
             log(`research: items/${item.sourceId}/${item.id}.yaml status -> researched`);
         }
     }
     return 0;
 }
+async function processResearchInvocation(params) {
+    const { cwd, items, digest, agent, templateId, template, now, triageGroup, log, warn, error, progress, } = params;
+    const prepared = await prepareResearch({
+        cwd,
+        items,
+        digest,
+        templateId,
+        now,
+        triageGroup,
+        warn,
+        error,
+        progress,
+    });
+    if ("exitCode" in prepared)
+        return prepared.exitCode;
+    const { outputPath, filename } = prepared;
+    const itemDescription = digest
+        ? `${items.length} items (${items.map((i) => i.id).join(", ")})`
+        : `item '${items[0].id}'`;
+    log(`research: invoking ${agent} adapter for ${itemDescription} -> ${filename}`);
+    const adapter = getAgentAdapter(agent);
+    // Phase marker + spinner: agent spawn. We pair `phase("Spawning …")` with
+    // `start("Agent running…")` so the marker is printed once for scrollback
+    // and the spinner row carries the live `[mm:ss]` heartbeat + metrics.
+    progress.phase(`Spawning ${agent}`, `cwd: ${cwd}`);
+    progress.start("Agent running");
+    const adapterStartedAt = Date.now();
+    const polling = pollOutputFileSize({ path: outputPath, reporter: progress });
+    let adapterExitCode = 0;
+    try {
+        await adapter.research({
+            agent,
+            templateId,
+            templateBody: template.body,
+            items,
+            outputPath,
+            cwd,
+            onProgress: buildAgentProgressCallback(progress),
+        });
+    }
+    catch (e) {
+        adapterExitCode = 1;
+        polling.stop();
+        progress.fail("Agent failed", e instanceof Error ? e.message : String(e));
+        error(`research: adapter failed: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+    finally {
+        polling.stop();
+    }
+    if (adapterExitCode === 0) {
+        progress.succeed(`Agent completed (exit ${adapterExitCode})`, Date.now() - adapterStartedAt);
+    }
+    return finalizeResearch({ cwd, outputPath, items, log, warn, error, progress });
+}
+/**
+ * Host-agent emit path (#254 / ADR-0019): run the same PRE block as the spawn
+ * path (`prepareResearch`) to derive `outputPath` + collision guard, then print
+ * the agent-neutral payload to stdout instead of spawning. The host session
+ * reads the payload, executes the SKILL procedure itself, and finalizes via
+ * `radar research --commit`.
+ */
+async function runResearchEmitPayload(params) {
+    const { cwd, items, digest, agent, templateId, template, now, triageGroup, log, warn, error, progress, } = params;
+    const prepared = await prepareResearch({
+        cwd,
+        items,
+        digest,
+        templateId,
+        now,
+        triageGroup,
+        warn,
+        error,
+        progress,
+    });
+    if ("exitCode" in prepared)
+        return prepared.exitCode;
+    log(renderResearchPayloadBlock({
+        agent,
+        templateId,
+        templateBody: template.body,
+        items,
+        outputPath: prepared.outputPath,
+    }));
+    return 0;
+}
+/**
+ * Host-agent commit path (#254 / ADR-0019): finalize a report the host session
+ * wrote out-of-band. Independent of agent / template / item resolution — the
+ * report is self-describing via its `itemIds` frontmatter, which
+ * `finalizeResearch` reverse-looks-up.
+ *
+ * Before finalize, the path is constrained to `<cwd>/research/` so a host that
+ * was misled by injected content into committing an arbitrary path (e.g.
+ * `../../etc/...`) is rejected at the CLI boundary (ADR-0009 M3b enforced in
+ * code, not just SKILL guidance).
+ */
+async function runResearchCommit(params) {
+    const { cwd, commitPath, log, warn, error, progress } = params;
+    const guard = await resolveCommitPathInside(cwd, "research", commitPath);
+    if ("error" in guard) {
+        error(`research: ${guard.error}`);
+        return 2;
+    }
+    return finalizeResearch({
+        cwd,
+        outputPath: guard.resolved,
+        items: undefined,
+        log,
+        warn,
+        error,
+        progress,
+    });
+}
 function parseMaxItems(raw, error) {
     if (raw === undefined)
         return RESEARCH_BATCH_DEFAULT_MAX_ITEMS;
@@ -395,13 +643,16 @@ async function runResearchBatch(parsed, cwd, log, warn, error, progress) {
         error("research: --batch is incompatible with --digest");
         return 2;
     }
+    if (parsed.triageGroup !== undefined) {
+        error("research: --batch is incompatible with --triage-group");
+        return 2;
+    }
     const rawStatus = parsed.status ?? "detected";
-    const statusResult = ItemStatusSchema.safeParse(rawStatus);
-    if (!statusResult.success) {
-        error(`research: invalid --status '${rawStatus}' (expected: detected | dismissed | researched | reviewed)`);
+    if (!RESEARCH_BATCH_ALLOWED_STATUSES.includes(rawStatus)) {
+        error(`research: invalid --status '${rawStatus}' (expected: ${RESEARCH_BATCH_ALLOWED_STATUSES.join(" | ")})`);
         return 2;
     }
-    const status = statusResult.data;
+    const status = rawStatus;
     const maxItems = parseMaxItems(parsed.maxItems, error);
     if (maxItems === null)
         return 2;
@@ -508,6 +759,37 @@ export async function runResearch(args, options = {}) {
         printHelp(log);
         return 0;
     }
+    // Host-agent commit (#254 / ADR-0019). Independent of agent / template /
+    // item resolution: the report is self-describing via its `itemIds`
+    // frontmatter. Handled before the other modes since it takes a path, not
+    // <item-id> arguments.
+    if (parsed.commit !== undefined) {
+        if (parsed.batch) {
+            error("research: --commit is incompatible with --batch");
+            return 2;
+        }
+        if (parsed.digest) {
+            error("research: --commit is incompatible with --digest");
+            return 2;
+        }
+        if (parsed.emitPayload) {
+            error("research: --commit is incompatible with --emit-payload");
+            return 2;
+        }
+        if (parsed.triageGroup !== undefined) {
+            error("research: --commit is incompatible with --triage-group");
+            return 2;
+        }
+        if (parsed.itemIds.length > 0) {
+            error(`research: --commit takes a <path>, not <item-id> arguments (got ${parsed.itemIds.length}: ${parsed.itemIds.join(", ")})`);
+            return 2;
+        }
+        return runResearchCommit({ cwd, commitPath: parsed.commit, log, warn, error, progress });
+    }
+    if (parsed.emitPayload && parsed.batch) {
+        error("research: --emit-payload is incompatible with --batch");
+        return 2;
+    }
     if (parsed.batch) {
         return runResearchBatch(parsed, cwd, log, warn, error, progress);
     }
@@ -523,6 +805,10 @@ export async function runResearch(args, options = {}) {
         error("research: --filter-tags requires --batch");
         return 2;
     }
+    if (parsed.triageGroup !== undefined && !parsed.digest) {
+        error("research: --triage-group requires --digest");
+        return 2;
+    }
     if (parsed.itemIds.length === 0) {
         error("research: missing <item-id>");
         printHelp(error);
@@ -572,6 +858,25 @@ export async function runResearch(args, options = {}) {
         error(`research: ${e instanceof Error ? e.message : String(e)}`);
         return 1;
     }
+    // Host-agent emit (#254 / ADR-0019): same item / template resolution as the
+    // spawn path, but print the payload instead of spawning. `--digest` is
+    // allowed (emits a digest payload).
+    if (parsed.emitPayload) {
+        return runResearchEmitPayload({
+            cwd,
+            items,
+            digest: parsed.digest ?? false,
+            agent,
+            templateId,
+            template,
+            now: new Date(),
+            triageGroup: parsed.triageGroup,
+            log,
+            warn,
+            error,
+            progress,
+        });
+    }
     return processResearchInvocation({
         cwd,
         items,
@@ -580,6 +885,7 @@ export async function runResearch(args, options = {}) {
         templateId,
         template,
         now: new Date(),
+        triageGroup: parsed.triageGroup,
         log,
         warn,
         error,