feature-factory 0.7.1 → 0.7.3

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/WORKFLOW.md

@@ -1,8 +1,17 @@
 # Feature Factory — host-neutral workflow
 
 This document is the authoritative, host-neutral feature-factory workflow. It is not a discoverable
-skill by itself. A host integration must ship its own `SKILL.md`, place an exact copy of this file next
-to that skill as `WORKFLOW.md`, and require the run driver to read it completely before any effect.
+skill by itself. A host integration must ship its own `SKILL.md` and place an exact copy of this file next
+to that skill as `WORKFLOW.md`.
+
+**Where the driver reads this file from, and when.** `factory init` stages an exact copy into the run
+directory and returns its path as `workflow`. The driver reads THAT copy, completely, before any state read,
+dispatch, gate, or factory command other than `init` itself — admission and the `init` invocation are
+specified by the host `SKILL.md`, everything after them here. A host whose agents may read outside the
+workspace may instead read the copy beside its skill; a host that denies such reads must use the staged copy,
+because the packaged one is unreadable there and a run that depends on it fails on a permission refusal
+rather than on anything about the work. Either way the bytes are identical, and a driver that cannot read
+either copy stops without effects.
 
 The host adapter owns only invocation admission, placement, session identity, specialist dispatch, and
 result delivery. This workflow owns the durable chain, gates, repository lifecycle, evidence rules, and

package/bin/factory.js

@@ -17,7 +17,7 @@ import { assertPublicationReady, assertReviewBinding, observeMergeProof, readEvi
 import { readRepositoryConfig, RepositoryConfigError } from "../observe/repository-config.js";
 import { reverifyRepair } from "../observe/repair-reverification.js";
 import { archiveReviewAttempt } from "../state/review-archive.js";
-import { writeProtectedJsonAtomic } from "../core/atomic-write.js";
+import { writeProtectedFileAtomic, writeProtectedJsonAtomic } from "../core/atomic-write.js";
 import { enforceEffectivePushTarget } from "../core/effective-push.js";
 import { resolveSpawnExecutable } from "../core/executable.js";
 import { dispatchInitPublication } from "./init-publication.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"]),
@@ -1336,9 +1336,21 @@ export async function dispatchInit(positional, flags, operations = INIT_OPERATIO
   } catch (error) {
     throw new CliError(`final manifest validation failed for sandbox '${S}'; sandbox was retained`, { cause: error });
   }
+  // `external_directory` is denied for every agent and the canonical workflow ships outside the workspace, so
+  // without this the driver cannot perform the read its own contract requires; the only other way past it is
+  // `--auto`, which blanket-approves every permission ask. Protected writer, not a copy: `bootstrap` has run
+  // repository-controlled commands by now, so a planted destination symlink would redirect a plain write out
+  // of the sandbox, and `assertSafeTarget` rechecks immediately before the rename. Before publication, so a
+  // failure aborts init while a retry is still possible.
+  const workflowBytes = readFileSync(new URL("../WORKFLOW.md", import.meta.url));
+  await writeProtectedFileAtomic(runDir, "WORKFLOW.md", workflowBytes);
+  const workflow = joinPath(runDir, "WORKFLOW.md");
+  if (!readFileSync(workflow).equals(workflowBytes)) {
+    throw new CliError(`staged workflow at '${workflow}' does not match the canonical copy; sandbox was retained`);
+  }
   const { observedRun } = await dispatchInitPublication({ runDir, sandboxPath: S, candidate: run, finalGuard: proveContainedBranch });
   return emit(flags, {
-    run_id: observedRun.run_id, run_dir: runDir, sandbox_path: proof.sandboxPath,
+    run_id: observedRun.run_id, run_dir: runDir, workflow, sandbox_path: proof.sandboxPath,
     branch: observedRun.branch, worktree: observedRun.worktree, pr_base: observedRun.pr_base,
     status: observedRun.status, mode: observedRun.mode,
   });
@@ -1348,13 +1360,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.1",
+  "version": "0.7.3",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",