feature-factory 0.7.0 → 0.7.2

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
@@ -887,7 +896,14 @@ The first successful seed is the **ratification point** for two decisions:
   per-merge proof and verification are what keep that safe.
 - `test_plan` — the exact executable commands authorized to prove the slice. Each non-empty entry is
   one complete, independently sufficient command string that must be supplied verbatim as one
-  `--test-cmd` value. A slice with a non-empty `test_plan` is not `review_ready` until one ratified
+  `--test-cmd` value. Each entry is executed as argv split on single spaces with no shell, so a shell
+  operator, a quote that groups an argument, a substitution or a redirection is inert payload or a hard
+  failure rather than syntax, and seeding refuses an entry it cannot execute that way. Entries
+  are alternatives, not a sequence: a slice needing several commands to run in order names one script
+  committed in the repository. `argv[0]` is resolved against the repository when the plan is seeded, before
+  any slice has implemented anything, so a script the work itself creates cannot be `argv[0]`: name an
+  interpreter that already resolves and pass the script as an argument, as in `sh scripts/verify-all.sh`.
+  A slice with a non-empty `test_plan` is not `review_ready` until one ratified
   command exits zero. A slice with an **empty** `test_plan` is exempt. That exemption is a decision for
   the engineer at Gate 2, so decide it in the plan and present it: there is no flag that waives tests at
   observation time.

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";
@@ -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,
   });

package/package.json

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

package/state/review-archive.js

@@ -25,8 +25,20 @@ export function attemptArchiveRef(ref, attempt) {
   return join(dir === "." ? "" : dir, `${stem}.attempt-${attempt}.json`);
 }
 
+// An archive has nothing to preserve: its content is already the frozen copy. Handed one anyway --
+// run 1551 reported an archive path back as `--review-ref`, and the suffix was appended twice, leaving
+// `spec-writer.attempt-1.attempt-1.json` beside the real archive with identical bytes. Harmless to
+// state, because the live record is untouched and `createOnly` protects the genuine archive, but the
+// reviews directory is the one place an operator reads to reconstruct why a run blocked, and a file
+// naming an attempt of an attempt invites them to look for a second verdict that does not exist.
+//
+// Instruction, not enforcement, and a no-op rather than a refusal: this module must never fail the
+// step that earned the verdict, which is the contract stated at the top of this file.
+const ARCHIVE_REF = /\.attempt-\d+\.json$/u;
+
 export async function archiveReviewAttempt(runDir, ref) {
   if (typeof ref !== "string" || !ref.trim()) return null;
+  if (ARCHIVE_REF.test(ref)) return null;
   let record;
   try {
     record = JSON.parse(readFileSync(join(runDir, ref), "utf8"));