feature-factory 0.10.2 → 0.10.4

package/README.md

@@ -258,8 +258,9 @@ own the same path. Duplicate, target-already-owned, malformed, privileged, repla
 requests refuse atomically. Resume never amends or reseeds. A merge continues to refuse every unamended
 or privileged changed path.
 
-A parked slice that exhausted its effective limit can receive exactly one audited extension through
-`factory grant-retry <run-id> <slice-id> --scope slice|all --reason <text> --session <id> --repo <sandbox>`.
+A parked slice that exhausted its effective limit can be reopened for one more attempt through
+`factory grant-retry <run-id> <slice-id> --scope slice|all [--max-retries N] --reason <text> --session <id> --repo <sandbox>`;
+`--max-retries` (with `all` only) sets the new run-wide limit in one call instead of raising it by one.
 Slice scope raises only the target's additive allowance. All scope raises `max_retries` for pending later
 waves too, but refuses when another slice is blocked or an exhausted post-merge repair record exists. Both
 scopes reopen only the named slice after exact owner, snapshot, REJECT, evidence, base, current clean head,

package/WORKFLOW.md

@@ -224,12 +224,14 @@ scope deliberately:
 
 ```sh
 factory grant-retry "$R" "$SLICE_ID" --scope slice --reason "$EXTENSION_REASON" --session "$SESSION_ID" --repo "$RUN_REPO"
-factory grant-retry "$R" "$SLICE_ID" --scope all --reason "$EXTENSION_REASON" --session "$SESSION_ID" --repo "$RUN_REPO"
+factory grant-retry "$R" "$SLICE_ID" --scope all [--max-retries "$N"] --reason "$EXTENSION_REASON" --session "$SESSION_ID" --repo "$RUN_REPO"
 ```
 
-`slice` raises only that slice's additive allowance. `all` raises the run-wide default, including every
-pending later wave, but still reopens only `SLICE_ID`; it refuses while another slice is blocked or an
-exhausted post-merge repair exists. Both scopes require `blocked@N` exactly at the current effective limit;
+`slice` raises only that slice's additive allowance by one. `all` raises the run-wide default, including
+every pending later wave, but still reopens only `SLICE_ID`; it refuses while another slice is blocked or an
+exhausted post-merge repair exists. `all` raises by one unless `--max-retries N` sets the new run-wide limit
+directly; `N` must exceed the current limit. Choose `N` for the whole remaining plan: once granted, later
+rejections below it retry without another operator grant. Both scopes require `blocked@N` exactly at the current effective limit;
 a matching REJECT, evidence, immutable base and live clean branch head; the exact fresh lock owner; a
 complete current park snapshot; and immutable attempt-N review and evidence archives. A legacy run missing
 an archive gets a preparation-only refusal: publish the changed plane and invoke the grant again. They

package/agents/backend-builder.md

@@ -106,7 +106,9 @@ Use exactly these field names and exactly this `status` vocabulary. The orchestr
 block to `factory observe --claim`, which compares each field against what it observes itself and
 records every disagreement as a review finding. `completed` is the word the evidence uses; any
 other spelling reads as a disagreement about status and blocks your own slice. `files_changed`
-must list every path, and `tests.exit` must be the real exit code — a claimed zero against an
+must list every path changed since the slice's `base_ref`, not since your last attempt — on a retry
+the observer diffs the whole slice, because that is what merges, and a list of only this attempt's
+edits is a disagreement. `tests.exit` must be the real exit code — a claimed zero against an
 observed failure is the single most important disagreement this mechanism catches.
 
 If the brief is wrong or impossible as written (e.g. the entity doesn't support it), stop, set `status: blocked` with the reason in `blockers`, and report the conflict — do not silently improvise a different design.

package/agents/frontend-builder.md

@@ -114,7 +114,9 @@ Use exactly these field names and exactly this `status` vocabulary. The orchestr
 block to `factory observe --claim`, which compares each field against what it observes itself and
 records every disagreement as a review finding. `completed` is the word the evidence uses; any
 other spelling reads as a disagreement about status and blocks your own slice. `files_changed`
-must list every path, and `tests.exit` must be the real exit code — a claimed zero against an
+must list every path changed since the slice's `base_ref`, not since your last attempt — on a retry
+the observer diffs the whole slice, because that is what merges, and a list of only this attempt's
+edits is a disagreement. `tests.exit` must be the real exit code — a claimed zero against an
 observed failure is the single most important disagreement this mechanism catches.
 
 If the design brief and the brief conflict, or a token/component the design needs doesn't exist, stop, set `status: blocked` with the reason in `blockers`, and report — don't hardcode around it.

package/bin/factory.js

@@ -40,7 +40,7 @@ export const COMMANDS = Object.freeze({
   status: Object.freeze(["--repo", "--json"]),
   "amend-paths": Object.freeze(["--repo", "--add", "--reason", "--session", "--now", "--json"]),
   resume: Object.freeze(["--repo", "--session", "--now", "--json"]),
-  "grant-retry": Object.freeze(["--repo", "--scope", "--reason", "--session", "--now", "--json"]),
+  "grant-retry": Object.freeze(["--repo", "--scope", "--max-retries", "--reason", "--session", "--now", "--json"]),
   restore: Object.freeze(["--repo", "--from", "--now", "--json"]),
   snapshot: Object.freeze(["--repo", "--json"]),
   decide: Object.freeze(["--repo", "--text", "--session", "--now", "--json"]),
@@ -799,11 +799,16 @@ const HANDLERS = {
     if (positional.length !== 2) throw new CliError("factory grant-retry requires exactly <run-id> <slice-id>");
     const [runId, sliceId] = positional;
     if (!RETRY_EXTENSION_SCOPES.includes(flags.scope)) throw new CliError(`factory grant-retry requires --scope ${RETRY_EXTENSION_SCOPES.join("|")}`);
+    if (flags.maxRetries !== undefined && flags.scope !== "all") throw new CliError("factory grant-retry --max-retries requires --scope all");
     if (typeof flags.reason !== "string" || !flags.reason.trim()) throw new CliError("factory grant-retry requires nonblank --reason <text>");
     if (typeof flags.session !== "string" || !flags.session.trim()) throw new CliError("factory grant-retry requires nonblank --session <id>");
     const runDir = runDirFor(flags, runId), repo = resolve(flags.repo ?? process.cwd());
     const boundBytes = readFileSync(join(runDir, "run.json")), current = validateRun(JSON.parse(boundBytes.toString("utf8")));
     if (current.status !== "needs-human") throw new CliError(`factory grant-retry requires current status needs-human; found '${current.status}'`);
+    // Instruction, not enforcement, on the size: a higher run-wide limit buys more reviewed attempts, never an
+    // unearned merge. Enforced only that it rises, since the grant must reopen the exhausted slice at N+1.
+    const grantedMax = flags.scope === "all" ? integer(flags.maxRetries, current.max_retries + 1, "--max-retries") : current.max_retries;
+    if (flags.scope === "all" && grantedMax <= current.max_retries) throw new CliError(`grant-retry --max-retries must exceed the current run-wide limit ${current.max_retries}`);
     const owner = assertFreshSessionOwner(runDir, runId, flags.session, "grant-retry"), at = stamp(flags);
     if (Date.parse(at) <= Date.parse(current.updated_at)) throw new CliError("grant-retry must move updated_at forwards");
     const qualified = qualifyRetryGrant(repo, runDir, runId, current, sliceId);
@@ -864,7 +869,7 @@ const HANDLERS = {
         const row = { ...existing, status: "running", attempts: existing.attempts + 1,
           ...(flags.scope === "slice" ? { extra_attempts: (existing.extra_attempts ?? 0) + 1 } : {}),
           evidence_ref: null, review_ref: null };
-        const maxRetries = state.max_retries + (flags.scope === "all" ? 1 : 0), newLimit = maxRetries + (row.extra_attempts ?? 0);
+        const maxRetries = grantedMax, newLimit = maxRetries + (row.extra_attempts ?? 0);
         const audit = { scope: flags.scope, slice_id: sliceId, base_ref: existing.base_ref, attempt: row.attempts, previous_limit: previousLimit,
           new_limit: newLimit, previous_max_retries: state.max_retries, max_retries: maxRetries,
           session: flags.session, reason: flags.reason.trim(), at, snapshot_digest: qualified.snapshotDigest,
@@ -1863,7 +1868,7 @@ function usage() {
   factory init <run-id> [--branch B=feature/<run-id>] [--worktree W=.] [--pr-base TARGET] [--issue KEY] [--mode interactive|headless|autonomous]
   factory status <run-id> [--json]
   factory amend-paths <run-id> <slice-id> --add PATH [--add PATH ...] --reason TEXT --session ID [--now ISO]
-  factory grant-retry <run-id> <slice-id> --scope slice|all --reason TEXT --session ID [--now ISO]
+  factory grant-retry <run-id> <slice-id> --scope slice|all [--max-retries N] --reason TEXT --session ID [--now ISO]
   factory decide <run-id> --text TEXT --session ID [--now ISO]
   factory resume <run-id> --session ID [--now ISO]
   factory restore <run-id> --repo OPERATOR --from refs/remotes/REMOTE/BRANCH [--now ISO]

package/core/contracts.js

@@ -66,7 +66,7 @@ const envelope = contract({
         const scope = mode === "grant-retry-all" ? "all" : "slice";
         if (after.status !== "needs-human" || !isDeepStrictEqual(after.terminal_result, before.terminal_result)) throw new Error("grant-retry must preserve the parked envelope and terminal_result");
         if (Date.parse(after.updated_at) <= Date.parse(before.updated_at)) throw new Error("grant-retry must move updated_at forwards");
-        if (scope === "all" ? after.max_retries !== before.max_retries + 1 : after.max_retries !== before.max_retries) throw new Error(`grant-retry ${scope} has an invalid run-wide retry limit`);
+        if (scope === "all" ? !(after.max_retries > before.max_retries) : after.max_retries !== before.max_retries) throw new Error(`grant-retry ${scope} has an invalid run-wide retry limit`);
         if (after.retry_extensions.length !== before.retry_extensions.length + 1 || !isDeepStrictEqual(after.retry_extensions.slice(0, -1), before.retry_extensions) || after.retry_extensions.at(-1)?.scope !== scope) throw new Error("grant-retry must append one matching audit record");
         for (const key of Object.keys(before).filter((key) => !["updated_at", "max_retries", "retry_extensions"].includes(key))) if (!isDeepStrictEqual(before[key], after[key])) throw new Error(`grant-retry cannot change envelope.${key}`);
         for (const key of Object.keys(current).filter((key) => !Object.hasOwn(before, key) && key !== "slices")) if (!isDeepStrictEqual(current[key], candidate[key])) throw new Error(`grant-retry cannot change run.${key}`);
@@ -340,7 +340,8 @@ const slices = contract({
       if (scope === "all" && before.some((entry, entryIndex) => entryIndex !== index && entry.status === "blocked")) throw new Error("grant-retry all cannot strand another blocked slice below the raised limit");
       if (prior.id !== slice.id || prior.status !== "blocked" || slice.status !== "running") throw new Error("grant-retry requires one blocked slice to become running");
       const previousLimit = effectiveRetryLimit(current, prior), nextLimit = effectiveRetryLimit(candidate, slice);
-      if (prior.attempts !== previousLimit || slice.attempts !== prior.attempts + 1 || nextLimit !== previousLimit + 1) throw new Error("grant-retry must open exactly N+1 from the exhausted effective limit");
+      const raise = scope === "all" ? candidate.max_retries - current.max_retries : 1;
+      if (prior.attempts !== previousLimit || slice.attempts !== prior.attempts + 1 || nextLimit !== previousLimit + raise) throw new Error("grant-retry must open exactly N+1 from the exhausted effective limit");
       const previousExtra = prior.extra_attempts ?? 0, nextExtra = slice.extra_attempts ?? 0;
       if (scope === "slice" ? nextExtra !== previousExtra + 1 : nextExtra !== previousExtra) throw new Error(`grant-retry ${scope} has an invalid slice-specific extension`);
       for (const key of new Set([...Object.keys(prior), ...Object.keys(slice)])) if (!["status", "attempts", "extra_attempts", "evidence_ref", "review_ref"].includes(key) && !isDeepStrictEqual(prior[key], slice[key])) throw new Error(`grant-retry cannot change slice '${slice.id}' ${key}`);

package/observe/index.js

@@ -123,10 +123,16 @@ export function runTests(worktree, command, { runner = spawnSync, skipReason = n
   return { cmd: shellCommand ? command : command.join(" "), exit, observed: exit !== null, skipped_reason: null };
 }
 
-// Readiness requires completed, clean, changed, observed-diff evidence and tests
-// observed passing or ratified as explicitly skipped with a reason.
+// Readiness requires completed, clean, changed, observed-diff evidence, no disagreement between
+// the builder's claim and the observation, and tests observed passing or ratified as explicitly
+// skipped with a reason.
 export function deriveReviewReady(evidence) {
   if (evidence.status !== "completed") return false;
+  // Enforcement (false green): a claim that disagrees with observation is itself the finding. It
+  // lives here, not beside the writer, because `readEvidence` recomputes readiness from this
+  // function alone; with the term only at write time, every mismatched record read back as
+  // tampered and wedged its slice where `slice blocked` could never record it.
+  if (evidence.claim_reconciliation?.mismatches?.length > 0) return false;
   // A tree with uncommitted changes cannot produce evidence about the commit it
   // claims, whatever the tests said.
   if (evidence.worktree_clean !== true) return false;
@@ -250,11 +256,8 @@ export function buildEvidence({ subject, runId, attempt, branch, baseRef, worktr
     review_ready: false,
     claim_reconciliation: { claimed: false, mismatches: [] },
   };
-  evidence.review_ready = deriveReviewReady(evidence);
   evidence.claim_reconciliation = reconcileClaim(claim, evidence);
-  // A claim that disagrees with what we observed cannot be review-ready: the
-  // disagreement is itself the finding.
-  if (evidence.claim_reconciliation.mismatches.length > 0) evidence.review_ready = false;
+  evidence.review_ready = deriveReviewReady(evidence);
   return evidence;
 }
 

package/package.json

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

package/state/schema.js

@@ -181,9 +181,10 @@ function retryExtensions(errors, run) {
     for (const key of ["attempt", "previous_limit", "new_limit", "previous_max_retries", "max_retries"]) positiveInt(errors, entry, key, path);
     if (!RETRY_EXTENSION_SCOPES.includes(entry.scope) || !ID.test(entry.slice_id)
       || ["attempt", "previous_limit", "new_limit", "previous_max_retries", "max_retries"].some((key) => !Number.isSafeInteger(entry[key]) || entry[key] < 1)) crossCheck = false;
-    if (Number.isSafeInteger(entry.previous_limit) && entry.new_limit !== entry.previous_limit + 1) errors.push({ path: `${path}.new_limit`, message: "must advance exactly one" });
+    const raise = entry.scope === "all" ? entry.max_retries - entry.previous_max_retries : 1;
+    if (Number.isSafeInteger(entry.previous_limit) && entry.new_limit !== entry.previous_limit + raise) errors.push({ path: `${path}.new_limit`, message: "must advance by the granted raise" });
     if (entry.scope === "slice" && entry.max_retries !== entry.previous_max_retries) errors.push({ path: `${path}.max_retries`, message: "must stay unchanged for slice scope" });
-    if (entry.scope === "all" && entry.max_retries !== entry.previous_max_retries + 1) errors.push({ path: `${path}.max_retries`, message: "must advance exactly one for all scope" });
+    if (entry.scope === "all" && !(raise >= 1)) errors.push({ path: `${path}.max_retries`, message: "must rise for all scope" });
     for (const key of ["session", "reason"]) required(errors, entry, key, path);
     pattern(errors, entry, "at", ISO, path);
     pattern(errors, entry, "snapshot_digest", DIGEST, path);
@@ -196,7 +197,7 @@ function retryExtensions(errors, run) {
     }
   });
   if (!crossCheck) return;
-  let maxRetries = run.max_retries - value.filter((entry) => entry.scope === "all").length;
+  let maxRetries = run.max_retries - value.reduce((sum, entry) => sum + (entry.scope === "all" ? entry.max_retries - entry.previous_max_retries : 0), 0);
   if (maxRetries < 1) return void errors.push({ path: "run.retry_extensions", message: "contains more run-wide grants than the final max_retries permits" });
   const extras = new Map(), latestGrant = new Map(), grantBases = new Map(), archiveRefs = new Set();
   let previousAt = null;
@@ -212,10 +213,10 @@ function retryExtensions(errors, run) {
     previousAt = Date.parse(entry.at);
     const previousLimit = maxRetries + previousExtra;
     if (entry.previous_max_retries !== maxRetries || entry.previous_limit !== previousLimit) errors.push({ path, message: "does not continue the recorded retry limits" });
-    if (entry.scope === "all") maxRetries += 1;
+    if (entry.scope === "all") maxRetries = entry.max_retries;
     else extras.set(entry.slice_id, previousExtra + 1);
     const newLimit = maxRetries + (extras.get(entry.slice_id) ?? 0);
-    if (entry.max_retries !== maxRetries || entry.new_limit !== newLimit || entry.attempt !== newLimit) errors.push({ path, message: "does not bind the granted attempt and resulting limits" });
+    if (entry.max_retries !== maxRetries || entry.new_limit !== newLimit || entry.attempt !== previousLimit + 1) errors.push({ path, message: "does not bind the granted attempt and resulting limits" });
     if (grantBases.has(entry.slice_id) && grantBases.get(entry.slice_id) !== entry.base_ref) errors.push({ path: `${path}.base_ref`, message: "changes the slice's immutable retry base" });
     grantBases.set(entry.slice_id, entry.base_ref); latestGrant.set(entry.slice_id, entry.attempt);
   }