forgeos 0.1.0-alpha.20 → 0.1.0-alpha.21

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.20 input=a0a760df40f02ebbcf3138bab4133a51f5a69548cba44b7ee4ec711ce57af5c6 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
+// @forge-generated generator=0.1.0-alpha.21 input=e2f2a360a9fd4118a2d21dd1353365628fe3927c40f9f9ce870f448f3e221f90 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # forgeos
 
+## 0.1.0-alpha.21
+
+### Patch Changes
+
+- Harden Codex hook queue privacy and brownfield import classification.
+
+  - Queue new Codex hook events as redacted payloads instead of storing raw prompts, tool inputs, tool responses, or transcripts in `.forge/agent/events.ndjson`.
+  - Compact consumed hook queue history into redacted `.history` lines so old raw queue entries are not copied forward during drain retention.
+  - Scope brownfield route classification to the detected route handler, so read-only GET handlers are not marked command-like because a sibling route in the same file writes state.
+  - Mark read-shaped `POST /search`, `/query`, `/filter`, `/lookup`, and `/graphql` routes as `command-candidate` with `ambiguous-post-query` risk instead of treating them as normal writes.
+  - Sync the public docs changelog/CLI reference and clarify the alpha/latest npm dist-tag policy.
+
 ## 0.1.0-alpha.20
 
 ### Patch Changes

package/README.md

@@ -413,7 +413,7 @@ Configure npm Trusted Publisher for package `forgeos`:
 | Environment | blank |
 | Allowed action | `npm publish` |
 
-Do not add `NPM_TOKEN` for normal releases. Alpha releases publish with the `alpha` dist-tag so prerelease builds do not become `latest` accidentally. Use `release:publish-local-alpha -- --dry-run` only to validate the staged tarball locally; real npm publishing should go through `release:publish-alpha`, which dispatches `publish.yml` and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses `id-token: write`, Node 24/npm 11+, and provenance for the actual publish. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
+Do not add `NPM_TOKEN` for normal alpha publishes. Alpha releases publish with the `alpha` dist-tag through npm OIDC Trusted Publisher so prerelease builds do not become `latest` accidentally. Configure `NPM_TOKEN` only when maintainers intentionally want the workflow to promote `latest` with `npm dist-tag add forgeos@<version> latest`; otherwise that step is skipped and `latest` may lag behind `alpha` during hardening. Use `release:publish-local-alpha -- --dry-run` only to validate the staged tarball locally; real npm publishing should go through `release:publish-alpha`, which dispatches `publish.yml` and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses `id-token: write`, Node 24/npm 11+, and provenance for the actual publish. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
 
 ## Milestone History
 

package/docs/changelog.md

@@ -6,6 +6,36 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.21
+
+Alpha.21 hardens external-agent privacy and brownfield import polish:
+
+- Codex hook runner queue entries now store redacted payloads instead of raw
+  prompts, tool inputs, tool responses, or transcripts.
+- Consumed hook queue history is compacted as redacted `.history` entries, so
+  old raw queue lines are not copied forward during retention.
+- Brownfield import now scopes write/side-effect heuristics to the detected
+  route handler when possible, preventing sibling mutating routes from making a
+  read-only GET route look command-like.
+- Read-shaped `POST /search`, `/query`, `/filter`, `/lookup`, and `/graphql`
+  routes are emitted as `command-candidate` with `ambiguous-post-query` risk
+  until a human review decides whether they should become Forge queries or
+  commands.
+- CLI/reference docs now include the CAIR agent protocol and clarify the
+  `alpha`/`latest` npm dist-tag policy.
+
+## 0.1.0-alpha.20
+
+Generated-change and hook queue fixes:
+
+- Fixed generated-change diagnostics for `AGENTS.md` generated blocks and
+  `.forge/agent/context.json`.
+- Skipped probe, invalid, and out-of-workspace queued hook events during Agent
+  Memory drain, and bounded large hook queue inspection.
+- Preserved empty stdio command arguments, diagnosed malformed command strings,
+  and supported structured `service.commandArgs` in external manifests.
+- Included the basic example client demo in typecheck coverage.
+
 ## 0.1.0-alpha.19
 
 Alpha hardening:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.21",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "files": [

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.20","releaseId":"forgeos@0.1.0-alpha.20+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.21","releaseId":"forgeos@0.1.0-alpha.21+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.20 input=a0a760df40f02ebbcf3138bab4133a51f5a69548cba44b7ee4ec711ce57af5c6 content=3c1af03eecebf9f9b009d8a4a2e08079c9853fca2c742eed3ea3d5b8b68a57b7
+// @forge-generated generator=0.1.0-alpha.21 input=e2f2a360a9fd4118a2d21dd1353365628fe3927c40f9f9ce870f448f3e221f90 content=dcf914c56ed71bee812d0015d689e1dbf4e952b17ad03cd835f396f5fc8fee1a
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.20",
-  "releaseId": "forgeos@0.1.0-alpha.20+unknown",
+  "packageVersion": "0.1.0-alpha.21",
+  "releaseId": "forgeos@0.1.0-alpha.21+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/agent-memory/bridge.ts

@@ -4,6 +4,7 @@ import { createDiagnostic } from "../compiler/diagnostics/create.ts";
 import { createDeltaId } from "../delta/ids.ts";
 import { DeltaStore, DeltaStoreBusyError, describeDeltaStoreBusy, summarizeDeltaStoreBusy } from "../delta/store.ts";
 import { extractAgentEventBindings, normalizeAgentEvent, summarizeAgentEvent } from "./normalize.ts";
+import { redactAgentPayload } from "./redaction.ts";
 import { buildAgentMemoryContext } from "./context-pack.ts";
 import { claudeCodeInstallFiles, claudeCodeInstallResult } from "./sources/claude-code.ts";
 import { codexInstallFiles, codexInstallResult, privacyDefaults } from "./sources/codex.ts";
@@ -497,15 +498,62 @@ function compactAgentMemoryQueueFile(options: {
   }
   mkdirSync(dirname(historyFile), { recursive: true });
   const existingHistory = existsSync(historyFile) ? readFileSync(historyFile) : Buffer.alloc(0);
+  const redactedConsumedHistory = redactedQueueHistoryBuffer(originalConsumed);
   writeFileSync(
     historyFile,
-    trimBufferStart(Buffer.concat([existingHistory, originalConsumed]), options.historyMaxBytes),
+    trimBufferStart(Buffer.concat([existingHistory, redactedConsumedHistory]), options.historyMaxBytes),
   );
   writeFileSync(options.watchFile, currentBuffer.subarray(options.consumedOffset));
   writeQueueCheckpoint(options.watchFile, 0);
   return { compacted: true, historyFile };
 }
 
+function redactedQueueHistoryBuffer(consumedBuffer: Buffer): Buffer {
+  const { complete } = splitCompleteJsonLines(consumedBuffer);
+  const lines: string[] = [];
+  for (const line of complete) {
+    if (!line.raw.trim()) {
+      continue;
+    }
+    const parsed = normalizeRawInput(line.raw);
+    if (!parsed) {
+      lines.push(JSON.stringify({
+        forgeHookQueueV1: true,
+        historyRedacted: true,
+        rawStored: false,
+        payloadRedacted: true,
+        payload: { _parseError: true },
+      }));
+      continue;
+    }
+    lines.push(JSON.stringify(redactedQueueHistoryEntry(parsed)));
+  }
+  return Buffer.from(lines.length > 0 ? `${lines.join("\n")}\n` : "", "utf8");
+}
+
+function redactedQueueHistoryEntry(parsed: Record<string, unknown>): Record<string, unknown> {
+  if (parsed.forgeHookQueueV1 !== true) {
+    return {
+      historyRedacted: true,
+      rawStored: false,
+      payloadRedacted: true,
+      payload: redactAgentPayload(parsed).value,
+    };
+  }
+  const queuedPayload = objectField(parsed, "payload") ?? objectField(parsed, "raw") ?? {};
+  return {
+    forgeHookQueueV1: true,
+    source: typeof parsed.source === "string" ? parsed.source : "codex",
+    eventName: typeof parsed.eventName === "string" ? parsed.eventName : undefined,
+    workspaceRoot: typeof parsed.workspaceRoot === "string" ? parsed.workspaceRoot : undefined,
+    enqueuedAt: typeof parsed.enqueuedAt === "string" ? parsed.enqueuedAt : undefined,
+    historyRedacted: true,
+    rawStored: false,
+    payloadRedacted: true,
+    payload: parsed.payloadRedacted === true ? queuedPayload : redactAgentPayload(queuedPayload).value,
+  };
+}
+
 function splitCompleteJsonLines(buffer: Buffer): {
   complete: Array<{ raw: string; endOffset: number }>;
   completeBytes: number;
@@ -1104,6 +1152,11 @@ function normalizeRawInput(input: unknown): Record<string, unknown> | null {
   return null;
 }
 
+function objectField(value: Record<string, unknown>, key: string): Record<string, unknown> | undefined {
+  const child = value[key];
+  return child && typeof child === "object" && !Array.isArray(child) ? child as Record<string, unknown> : undefined;
+}
+
 export async function readStdinJson(options?: { timeoutMs?: number }): Promise<unknown> {
   if (process.stdin.isTTY) {
     return undefined;
@@ -1150,15 +1203,15 @@ function parseQueuedHookLine(raw: Record<string, unknown>): {
   if (raw.forgeHookQueueV1 !== true) {
     return null;
   }
-  const payload = raw.raw;
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+  const payload = objectField(raw, "payload") ?? objectField(raw, "raw");
+  if (!payload) {
     return null;
   }
   return {
     source: typeof raw.source === "string" ? raw.source : "codex",
     eventName: typeof raw.eventName === "string" ? raw.eventName : undefined,
     workspaceRoot: typeof raw.workspaceRoot === "string" ? raw.workspaceRoot : undefined,
-    payload: payload as Record<string, unknown>,
+    payload,
   };
 }
 

package/src/forge/agent-memory/sources/codex-hook-runner.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 /**
  * Lightweight Codex hook runner — no Forge CLI, no DeltaDB.
- * Reads stdin with a short timeout, enqueues to .forge/agent/events.ndjson, exits.
+ * Reads stdin with a short timeout, enqueues a redacted event to .forge/agent/events.ndjson, exits.
  */
+import { createHash } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
@@ -17,6 +18,24 @@ if (!eventName) {
 const workspaceRoot = resolve(process.cwd());
 const eventsFile = join(workspaceRoot, ".forge", "agent", "events.ndjson");
 
+const RAW_TEXT_KEYS = new Set([
+  "prompt",
+  "userPrompt",
+  "last_assistant_message",
+  "lastAssistantMessage",
+  "completion",
+  "message",
+  "transcript",
+  "transcript_path",
+  "transcriptPath",
+  "output",
+  "stdout",
+  "stderr",
+  "result",
+]);
+
+const RAW_ARGS_KEYS = new Set(["args", "arguments", "tool_input", "toolInput", "tool_response", "toolResponse", "input"]);
+
 function readStdin(timeoutMs) {
   return new Promise((resolveRead) => {
     if (process.stdin.isTTY) {
@@ -72,13 +91,183 @@ async function main() {
     eventName,
     workspaceRoot,
     enqueuedAt: new Date().toISOString(),
-    raw,
+    rawStored: false,
+    payloadRedacted: true,
+    payload: sanitizePayload(raw, eventName),
   };
 
   mkdirSync(dirname(eventsFile), { recursive: true });
   appendFileSync(eventsFile, `${JSON.stringify(entry)}\n`, "utf8");
 }
 
+function sanitizePayload(raw, hookEventName) {
+  const payload = stripRawPayload(raw);
+  if (!payload.hook_event_name) {
+    payload.hook_event_name = hookEventName;
+  }
+  if (!payload.cwd) {
+    payload.cwd = workspaceRoot;
+  }
+
+  const toolInput = objectField(raw, "tool_input") ?? objectField(raw, "toolInput");
+  const toolResponse = objectField(raw, "tool_response") ?? objectField(raw, "toolResponse");
+  const command = stringField(toolInput, "command") ?? stringField(raw, "command");
+  if (command) {
+    payload.commandHash = hashStable(command);
+    payload.commandStored = false;
+    payload.commandSummary = summarizeCommand(command);
+    payload.commandKind = classifyCommand(stringField(raw, "tool_name") ?? stringField(raw, "toolName"), command);
+  }
+
+  const description = stringField(toolInput, "description");
+  if (description) {
+    payload.approvalDescriptionSummary = safeSummary(description, 180);
+  }
+
+  const exitCode = numberField(toolResponse, "exitCode") ?? numberField(toolResponse, "exit_code") ??
+    numberField(raw, "exitCode") ?? numberField(raw, "exit_code");
+  if (exitCode !== undefined) {
+    payload.exitCode = exitCode;
+    payload.resultStatus = exitCode === 0 ? "success" : "failed";
+  } else {
+    const status = stringField(toolResponse, "status") ?? stringField(raw, "status");
+    if (status) {
+      payload.resultStatus = status;
+    }
+  }
+
+  const responseSummary = summarizeToolResponse(toolResponse);
+  if (responseSummary) {
+    payload.responseSummary = responseSummary;
+  }
+  if (toolResponse) {
+    payload.responseHash = hashStable(JSON.stringify(toolResponse));
+    payload.responseStored = false;
+  }
+
+  return payload;
+}
+
+function stripRawPayload(value) {
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map((item) => stripRawPayload(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (RAW_TEXT_KEYS.has(key)) {
+      output[`${key}Hash`] = hashStable(typeof child === "string" ? child : JSON.stringify(child ?? null));
+      output[`${key}Stored`] = false;
+      if (typeof child === "string" && !isPromptLikeKey(key)) {
+        const summary = safeSummary(child, 160);
+        if (summary) {
+          output[`${key}Summary`] = summary;
+        }
+      }
+      continue;
+    }
+    if (RAW_ARGS_KEYS.has(key)) {
+      output[`${key}Hash`] = hashStable(JSON.stringify(child ?? null));
+      output[`${key}Stored`] = false;
+      output[`${key}Shape`] = describeShape(child);
+      continue;
+    }
+    output[key] = stripRawPayload(child);
+  }
+  return output;
+}
+
+function objectField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const child = value[key];
+  return child && typeof child === "object" && !Array.isArray(child) ? child : undefined;
+}
+
+function stringField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const child = value[key];
+  return typeof child === "string" && child.length > 0 ? child : undefined;
+}
+
+function numberField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const child = value[key];
+  return typeof child === "number" && Number.isFinite(child) ? child : undefined;
+}
+
+function describeShape(value) {
+  if (Array.isArray(value)) {
+    return { kind: "array", length: value.length };
+  }
+  if (value && typeof value === "object") {
+    return {
+      kind: "object",
+      keys: Object.keys(value).slice(0, 20).sort(),
+    };
+  }
+  return { kind: typeof value };
+}
+
+function summarizeCommand(command) {
+  return safeSummary(
+    command
+      .replace(/--(token|api-key|apikey|password|secret)\s+[^\s]+/giu, "--$1 [REDACTED]")
+      .replace(/(["']?)(token|apiKey|api_key|password|secret)(["']?)\s*:\s*(["'])(.*?)\4/giu, "$1$2$3: \"[REDACTED]\""),
+    220,
+  ) ?? "[command redacted]";
+}
+
+function summarizeToolResponse(response) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    return undefined;
+  }
+  const text = stringField(response, "stdout") ?? stringField(response, "stderr") ??
+    stringField(response, "output") ?? stringField(response, "result");
+  return text ? safeSummary(text, 180) : undefined;
+}
+
+function safeSummary(value, maxLength) {
+  const normalized = scrubSecretTokens(value).replace(/\s+/gu, " ").trim();
+  if (!normalized) {
+    return undefined;
+  }
+  return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 3)}...` : normalized;
+}
+
+function classifyCommand(toolName, command) {
+  if (toolName === "apply_patch" || command.includes("*** Begin Patch")) {
+    return "patch";
+  }
+  if (/^\s*(?:node|npm|bun|pnpm|yarn|forge|git)\b/u.test(command)) {
+    return "shell";
+  }
+  return "unknown";
+}
+
+function isPromptLikeKey(key) {
+  return key.toLowerCase().includes("prompt") || key.toLowerCase().includes("completion") || key.toLowerCase().includes("message");
+}
+
+function scrubSecretTokens(value) {
+  return value
+    .replace(/\bsk[-_][A-Za-z0-9_\-.]{8,}\b/gu, "[REDACTED]")
+    .replace(/\bnpm_[A-Za-z0-9]{16,}\b/gu, "[REDACTED]")
+    .replace(/\bgh[pousr]_[A-Za-z0-9_]{16,}\b/gu, "[REDACTED]")
+    .replace(/\b(?:xox[baprs]-)[A-Za-z0-9-]{16,}\b/gu, "[REDACTED]");
+}
+
+function hashStable(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
 main()
   .then(() => process.exit(0))
   .catch(() => process.exit(1));

package/src/forge/brownfield-import/index.ts

@@ -8,6 +8,7 @@ import type {
   ImportedDependencyInventory,
   ImportedFrontendCall,
   ImportedInventory,
+  ImportedEntryKind,
   ImportedRiskFinding,
   ImportedRiskReport,
   ImportedRoute,
@@ -365,7 +366,53 @@ function collectEnv(workspaceRoot: string, files: SourceFile[]): ImportedInvento
 }
 
 function sourceTextForRoute(route: ImportedRoute, files: SourceFile[]): string {
-  return files.find((file) => file.relativePath === route.file)?.text ?? "";
+  const text = files.find((file) => file.relativePath === route.file)?.text ?? "";
+  if (!text) {
+    return "";
+  }
+  return scopedSourceTextForRoute(route, text) ?? text;
+}
+
+function scopedSourceTextForRoute(route: ImportedRoute, text: string): string | null {
+  if (route.source === "next-app-router" && route.handler) {
+    return sliceUntilNextMatch(
+      text,
+      new RegExp(`export\\s+(?:async\\s+)?function\\s+${escapeRegExp(route.handler)}\\b`, "u"),
+      /export\s+(?:async\s+)?function\s+(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/gu,
+    );
+  }
+  if (route.source === "express") {
+    const method = route.method.toLowerCase();
+    const matcher = new RegExp(`\\b(?:app|router)\\s*\\.\\s*${escapeRegExp(method)}\\s*\\(\\s*["'\`]${escapeRegExp(route.path)}["'\`]`, "u");
+    return sliceUntilNextMatch(
+      text,
+      matcher,
+      /\b(?:app|router)\s*\.\s*(?:get|post|put|patch|delete|all)\s*\(\s*["'`][^"'`]+["'`]/giu,
+    );
+  }
+  if (route.source === "nest") {
+    const method = route.method.charAt(0).toUpperCase() + route.method.slice(1).toLowerCase();
+    return sliceUntilNextMatch(
+      text,
+      new RegExp(`@${escapeRegExp(method)}\\s*\\(`, "u"),
+      /@(Get|Post|Put|Patch|Delete|All)\s*\(/gu,
+    );
+  }
+  return null;
+}
+
+function sliceUntilNextMatch(text: string, startPattern: RegExp, nextPattern: RegExp): string | null {
+  const start = text.search(startPattern);
+  if (start < 0) {
+    return null;
+  }
+  nextPattern.lastIndex = start + 1;
+  const next = nextPattern.exec(text);
+  return text.slice(start, next?.index ?? text.length);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 
 function classifyCandidate(route: ImportedRoute, text: string): Pick<ImportedCandidateEntry, "kind" | "confidence" | "risks" | "evidence" | "needsApproval"> {
@@ -381,9 +428,17 @@ function classifyCandidate(route: ImportedRoute, text: string): Pick<ImportedCan
   const auth = /(auth|session|currentuser|getserversession|clerk|nextauth|requireuser|requireauth)/u.test(lowerText);
   const tenant = /(tenantid|tenant_id|organizationid|orgid|accountid)/u.test(lowerText);
   const methodUnknown = method === "ANY" || method === "ALL";
-  if (!isQuery || writes) {
+  const ambiguousPostQuery = method === "POST" &&
+    /(?:^|\/)(search|query|filter|lookup|graphql)(?:$|\/)/u.test(lowerPath) &&
+    !writes &&
+    !isDestructive &&
+    !external;
+  if ((!isQuery && !ambiguousPostQuery) || writes) {
     risks.add("writes-state");
   }
+  if (ambiguousPostQuery) {
+    risks.add("ambiguous-post-query");
+  }
   if (isDestructive) {
     risks.add("destructive");
   }
@@ -403,6 +458,15 @@ function classifyCandidate(route: ImportedRoute, text: string): Pick<ImportedCan
     risks.add("method-unknown");
   }
   const commandLike = !isQuery || writes || isDestructive || external;
+  if (ambiguousPostQuery) {
+    return {
+      kind: "command-candidate",
+      confidence: 0.55,
+      risks: Array.from(risks).sort(),
+      evidence,
+      needsApproval: true,
+    };
+  }
   return {
     kind: commandLike ? "command" : "query",
     confidence: commandLike ? (isDestructive ? 0.9 : 0.78) : 0.86,
@@ -412,7 +476,7 @@ function classifyCandidate(route: ImportedRoute, text: string): Pick<ImportedCan
   };
 }
 
-function nameForCandidate(route: ImportedRoute, kind: "command" | "query" | "unknown"): string {
+function nameForCandidate(route: ImportedRoute, kind: ImportedEntryKind): string {
   const nouns = route.path
     .replace(/^\/api\//u, "")
     .replace(/:\w+\*?/gu, "byId")
@@ -424,6 +488,7 @@ function nameForCandidate(route: ImportedRoute, kind: "command" | "query" | "unk
   const method = route.method.toUpperCase();
   const action =
     kind === "query" ? "read" :
+    kind === "command-candidate" ? "candidate" :
     method === "POST" ? "create" :
     method === "PUT" || method === "PATCH" ? "update" :
     method === "DELETE" ? "delete" :

package/src/forge/brownfield-import/types.ts

@@ -11,7 +11,7 @@ export interface BrownfieldImportCommandOptions {
 
 export type ImportedAssurance = "static-scan";
 export type ImportedReviewStatus = "needs-review" | "approved" | "rejected";
-export type ImportedEntryKind = "command" | "query" | "unknown";
+export type ImportedEntryKind = "command" | "command-candidate" | "query" | "unknown";
 export type ImportedRouteSource = "next-app-router" | "next-pages-api" | "express" | "nest" | "unknown";
 
 export interface ImportedDependencyInventory {

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.20";
+export const FORGEOS_VERSION = "0.1.0-alpha.21";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;