feature-factory 0.7.2 → 0.7.4

package/README.md

@@ -71,6 +71,32 @@ selects the run and reaches `story-reader` without extraction, wrapping, reseria
 normalization. The value matches `^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$`; digit-only values are positive
 decimal without leading zeroes.
 
+A resolver does not have to look anything up. When the caller already holds the work item — a controller
+dispatching an item it rendered itself, or a tracker whose content is already in the launch environment —
+the resolver is a transport rather than a lookup, and the whole of it is one `printf`:
+
+```sh
+[ -n "$MY_WORK_ITEM_JSON" ] && { printf %s "$MY_WORK_ITEM_JSON"; exit 0; }
+# otherwise fall through to whatever lookup this repository declares
+```
+
+Use `printf %s` and not `echo`, which appends a newline and in some shells interprets backslash escapes,
+corrupting a `body` that contains them. Gating the branch on a variable lets one config serve both callers:
+the caller that supplies the item sets it, and a caller that supplies only a reference takes the declared
+lookup unchanged, so adding the branch changes no existing behavior. Because the resolver chooses `run_id`,
+a caller supplying its own item also chooses the sandbox name, feature-branch suffix, and manifest candidate
+— so giving it a namespace of its own, such as `chainlink-1327`, makes collision with the tracker's own
+numbering unrepresentable rather than something a lookup has to detect.
+
+A resolver that recognizes a reference it cannot serve must exit non-zero rather than exit zero with empty
+stdout. Exit status is observable, so those two results are distinguishable — which is precisely why the
+choice matters. The ambiguity arises only when an in-scope but unserviceable reference is *reported* as exit
+zero with empty stdout, because that is already the contract's signal for *this is not my reference*: the run
+then continues to ticket, design, and free-text derivation from the request, and for a bare id that names no
+workflow, outcome, or acceptance criteria, so it reaches Gate 1 with nothing to approve and parks there. A
+non-zero exit instead refuses immediately, names the reference, and creates no session or run. Only the
+resolver author knows which of the two cases it is in, so the contract cannot make the choice for it.
+
 Malformed config, malformed payload, a non-zero exit, or unavailable exit status refuses before any
 run effect and never falls back:
 

package/bin/factory.js

@@ -27,7 +27,7 @@ import {
 } from "../state/session-lock.js";
 
 export const COMMANDS = Object.freeze({
-  init: Object.freeze(["--repo", "--branch", "--worktree", "--pr-base", "--issue", "--mode", "--max-parallel-slices", "--max-retries", "--now", "--json"]),
+  init: Object.freeze(["--repo", "--branch", "--worktree", "--pr-base", "--issue", "--issue-key", "--mode", "--max-parallel-slices", "--max-retries", "--now", "--json"]),
   status: Object.freeze(["--repo", "--json"]),
   "amend-paths": Object.freeze(["--repo", "--add", "--reason", "--session", "--now", "--json"]),
   resume: Object.freeze(["--repo", "--session", "--now", "--json"]),
@@ -1039,12 +1039,19 @@ const HANDLERS = {
     const at = stamp(flags);
     const next = await transition(runDir, {
       participants: [{ familyId: "envelope", mode: "terminalize" }],
-      apply: (state) => ({
-        ...state,
-        updated_at: at,
-        status,
-        terminal_result: { status, reason: flags.reason },
-      }),
+      apply: (state) => {
+        // Enforcement, not instruction: `completed` is the only terminal status that asserts the run earned a
+        // result, and the ordering that gave it meaning -- publish, then terminalize with reason
+        // `draft-pr-recorded` -- lived in WORKFLOW.md alone, so a driver that skipped the work could still
+        // record success. mimir 1483 did exactly that: ~70 seconds, no commits, no pushed branch, no PR, and
+        // a status a consumer binding on `status == "completed"` read as a shipped epic. `blocked` and
+        // `partial` stay unguarded because they claim less, and cleanup re-terminalizes an already-published
+        // run whose `pr_url` is set, so it still passes.
+        if (status === "completed" && !state.pr_url) {
+          throw new CliError("factory terminal completed requires a recorded pr_url; use blocked or partial");
+        }
+        return { ...state, updated_at: at, status, terminal_result: { status, reason: flags.reason } };
+      },
     });
     return emit(flags, { run_id: runId, status: next.status, reason: next.terminal_result.reason });
   },
@@ -1360,13 +1367,18 @@ function preflightInit(positional, flags) {
   const refusal = (message, cause) => new CliError(`${message}; no sandbox path was derived or created`, cause ? { cause } : undefined);
   if (positional.length !== 1) throw refusal("factory init requires exactly one <run-id>");
   if (flags.repo !== undefined && (typeof flags.repo !== "string" || !flags.repo.trim())) throw refusal("--repo must be a non-empty string");
+  // Accepted alias, not a guard: `issue_key` is the field name every reader sees, so `--issue-key` is the
+  // spelling reached for first -- mimir 1606's driver did, got `unknown option`, and recovered by dropping
+  // the flag, so a run that had read its real issue recorded none. Disagreement refuses, because the key is
+  // appended as `Closes #<key>` and preferring one silently would close a stranger's issue.
+  if (flags.issue !== undefined && flags.issueKey !== undefined && flags.issue !== flags.issueKey) throw refusal("--issue and --issue-key disagree; pass one");
   const runId = positional[0];
   try {
     const at = stamp(flags);
     return validateRun({
       version: SCHEMA_VERSION,
       run_id: runId,
-      issue_key: flags.issue ?? null,
+      issue_key: flags.issue ?? flags.issueKey ?? null,
       branch: flags.branch ?? `feature/${runId}`,
       worktree: flags.worktree ?? ".",
       pr_base: flags.prBase ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-factory",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",