feature-factory 0.8.5 → 0.8.7

package/WORKFLOW.md

@@ -177,7 +177,8 @@ reporting anything:
 A park that completes only step 1 is an unreported park with no recovery evidence, which is the state
 this sequence exists to prevent. Verify step 2 the way an outside observer would: qualified status
 reports `park_snapshot` as the published path, or `null` when no snapshot exists. Status reports the path
-only while the snapshot is a complete copy of the live plane by the step 3 inventory and its manifest still
+only while the snapshot is a complete copy of the live plane by the step 3 inventory — `factory.lock`
+excluded, since a heartbeat may land between the copy and the read — and its manifest still
 matches the live one byte for byte, so `null` also covers an interrupted or altered copy and a snapshot
 left by an earlier park: neither is evidence for this park. Publishing again is what makes it correspond.
 
@@ -243,7 +244,12 @@ and "clean up the prior copy" are contradictory instructions once that rename ha
    outside `P`; do not copy slice worktrees or any other part of `S`.
 3. **Verify.** Build source and destination inventories exactly as the completed archive does — every
    entry's relative path, type and mode, a SHA-256 for each regular file, a link target for each symlink,
-   sorted lexically — and require exact equality. An unverified staging tree is never published.
+   sorted lexically — and require exact equality, **excluding the plane-root `factory.lock` only**. That
+   one entry is session liveness rather than run state and is the only thing in the plane designed to
+   change on a timer, so comparing it fails whenever a heartbeat lands between reading the source and
+   reading the copy. The exclusion is that exact path and nothing else: a `factory.lock` anywhere below
+   the plane root is run state and must match. Qualified status excludes the same single path for the same
+   reason. An unverified staging tree is never published.
 4. **Commit.** With no snapshot at the canonical path, rename `.staging-$R` onto it; that rename is the
    commit point. With one present, first rename the canonical snapshot to `.prior-$R`, then rename
    `.staging-$R` onto the canonical path; that second rename is the commit point. If the first rename
@@ -295,8 +301,12 @@ fresh run; an existing run follows these rules solely because its manifest alrea
   every acceptance criterion maps to a slice, and same-wave slices are file-disjoint.
 - **Gate 3 (pre-PR)**: approve only on a GO or GO-WITH-NITS validator verdict with `review_ready`
   observed evidence for the integrated branch. A NO-GO is a NO-GO.
-- **Never auto-merge.** The draft PR is the last externally publishing side effect an autonomous run
-  may perform. After it is recorded, the mandatory local completed handoff in Step 7 still follows and
+- **Never auto-merge.** Recording the pull request is the last externally publishing side effect an
+  autonomous run may perform. Whether that PR is a draft is the repository's `pr_draft` choice and is
+  independent of the run mode: autonomous does not imply draft, and `pr_draft: false` is a supported
+  configuration that publishes ready-for-review in every mode. The constraint here is about stopping
+  after publication, not about draft-ness.
+  After it is recorded, the mandatory local completed handoff in Step 7 still follows and
   is required in every mode: terminalize, fetch the permitted local refs, archive and verify the control
   plane, and remove only the guarded sandbox. Autonomous mode never merges an external PR or performs
   unrelated work after PR recording.
@@ -562,7 +572,7 @@ After derivation, `O` is the physically resolved operator checkout. During boots
 execution, do not switch, reset, clean, stash, create a branch or worktree, write Git configuration, or
 initialize factory state directly in `O`. The only operator-checkout operations before the completed
 handoff are reads and the Step 6 forge command. The explicit Step 7 exclusion applies only after the
-draft PR is recorded: its guarded local-ref fetch, archive, verification, and deterministic sandbox
+pull request is recorded: its guarded local-ref fetch, archive, verification, and deterministic sandbox
 removal remain the sole completed-handoff exception to bootstrap/refusal state preservation.
 
 ### Resume or collision
@@ -1816,10 +1826,10 @@ command; never move it earlier or present stale evidence.
 The compatibility transition name is `factory gate <run-id> pre_pr pending`; the runnable form is the
 repository-qualified command above.
 
-The draft publication signature is `gh pr create --draft --base "<pr_base>" --head "<branch>" --title "<title>" --body-file "<body-file>"`.
-The ready-for-review publication signature is `gh pr create --base "<pr_base>" --head "<branch>" --title "<title>" --body-file "<body-file>"`.
+The `PR_DRAFT=true` draft publication signature is `gh pr create --draft --base "<pr_base>" --head "<branch>" --title "<title>" --body-file "<body-file>"`.
+The `PR_DRAFT=false` ready-for-review publication signature is `gh pr create --base "<pr_base>" --head "<branch>" --title "<title>" --body-file "<body-file>"`.
 
-## Step 6 — Draft PR
+## Step 6 — Draft PR (ready-for-review when `pr_draft` is false)
 
 Immediately before any publication effect, read the delivery intent from the selected run repository,
 then, for a sandbox-selected run, repeat the operator exact-ref-absent and sandbox
@@ -1951,12 +1961,13 @@ whatever mapping the repository documents, and update the tracker only through *
 
 ## Step 7 — Summary and completed sandbox handoff
 
-After draft PR recording, `interactive`, `headless`, and `autonomous` modes all enter this same mandatory
+After the pull request is recorded -- draft or ready for review, as `pr_draft`
+selected -- `interactive`, `headless`, and `autonomous` modes all enter this same mandatory
 local completed handoff. In autonomous mode this is the sole narrow exception to the external-side-effect
 stop: perform only the terminalize, local-ref fetch, archive, verification, and guarded sandbox-removal
 sequence below, with no external PR merge or unrelated work after PR recording.
 
-After `factory pr` records the draft PR, stop the heartbeat loop and wait for any heartbeat call already
+After `factory pr` records the pull request, stop the heartbeat loop and wait for any heartbeat call already
 in flight to return. Before terminalization or any filesystem or Git side effect, require that the loop
 is no longer active and no dispatched agent call remains in flight, directly read and validate exactly
 `RUN_MANIFEST`, and require no step with status `running` and no slice with status `running` or `review`.
@@ -1975,6 +1986,12 @@ Terminalize before any housekeeping, through the repository selected in Step 0:
 factory terminal "$R" completed --reason "draft-pr-recorded" --repo "$RUN_REPO"
 ```
 
+`draft-pr-recorded` is a fixed protocol token meaning this run's pull request was created and recorded.
+It does not assert the PR is a draft: a `pr_draft: false` run records a ready-for-review PR and
+terminalizes with this same reason. Never vary it by mode or by `pr_draft`; downstream consumers match
+it exactly.
+
+
 Do not replay or retry any handoff phase. A later invocation that finds a completed sandbox reports its
 path for manual recovery and leaves it intact. For the same reason, do not invent durable phase state or
 infer that an interrupted effect is safe to repeat.
@@ -2118,7 +2135,8 @@ Never re-do a side effect the manifest shows already done — ticket creation, p
   Qualified status reports the run's `max_retries`, so the budget a run is actually bounded by is
   observable rather than assumed: a forwarded `--max-retries` that never reached the manifest is visible
   as a different number instead of silently running at the default.
-- **Draft PR only.** Never merge, force-push, or close tickets. Humans merge.
+- **Publish a PR and stop.** Never merge, force-push, or close tickets. Humans merge. Draft or
+  ready-for-review is `pr_draft`'s decision, not this rule's.
 - **Scope discipline and no fabrication.** Flag out-of-scope work at the next gate. Never invent paths,
   keys, versions, or test passes — if the evidence is thin, say so and ask.
 - **A repository may lock its own scope, and a lock is not a defect.** A check whose assertion *is* a

package/bin/factory.js

@@ -23,7 +23,7 @@ import { resolveSpawnExecutable } from "../core/executable.js";
 import { dispatchInitPublication } from "./init-publication.js";
 import { CONTROL_PLANE, SCHEMA_VERSION, GATE_NAMES, GATE_STATUSES, MODES, SLICE_STATUSES, STEP_STATUSES, TERMINAL_STATUSES, repositoryRelativePath, validateRun } from "../state/schema.js";
 import {
-  claimSessionLock, inspectSessionLock, refreshSessionLock, releaseSessionLock, SessionLockHeldError,
+  claimSessionLock, inspectSessionLock, refreshSessionLock, releaseSessionLock, SESSION_LOCK_FILE, SessionLockHeldError,
 } from "../state/session-lock.js";
 
 export const COMMANDS = Object.freeze({
@@ -175,6 +175,15 @@ function briefDigestFor(decision, state, runDir) {
 function planeInventory(root) {
   const entries = [];
   const record = (rel, full) => {
+    // The session lock is liveness, not run state, and it is the one entry in the plane designed to change
+    // on a timer. Comparing it made every snapshot invalid within one heartbeat: a live park published a
+    // complete, byte-correct plane and `status` reported `park_snapshot: null` eleven seconds later,
+    // because the copy held `heartbeat_at` 23:28:25 and the plane had moved to 23:28:36. The whole point
+    // of the field was to answer "did the driver publish it", and it answered "no" for a snapshot that was
+    // there -- the same disagree-with-your-own-description defect the 0.8.3 work existed to remove,
+    // reintroduced by the check built to remove it. Every existing test publishes and reads back with no
+    // heartbeat in between, which is why three review rounds and a real park all missed it.
+    if (rel === SESSION_LOCK_FILE) return;
     const stat = lstatSync(full);
     const mode = (stat.mode & 0o7777).toString(8);
     if (stat.isSymbolicLink()) entries.push(`${rel} l ${mode} ${readlinkSync(full)}`);

package/package.json

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