feature-factory 0.10.0 → 0.10.1

package/README.md

@@ -258,6 +258,17 @@ 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>`.
+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,
+and immutable attempt archives. A legacy run missing one prepares it without granting, then requires a
+fresh snapshot and a second grant invocation. Exhaustion parks with reason `blocked-after-retries` rather
+than terminalizing `partial`. The grant moves the prior canonical snapshot away, so restore cannot recover
+pre-grant authority; run `factory snapshot <run-id> --repo <operator>` and requalify it before the separate
+explicit resume. Restored blocked slices whose physical refs were intentionally cleared do not qualify.
+
 `resolve` and `verify` are consumed now, and the run's recorded `publishing_identity` is compared at the publication guards. Step 6 resolves one selection: a nonblank inherited `FACTORY_PUBLISHING_COMMAND` selects its exact string; that variable set blank or whitespace selects the default; when it is unset, configured `publish` wins if present; otherwise the default wins. Only a selected nondefault command replaces `gh pr create`, after the factory-owned exact push and post-push identity guard. It receives exact `PR_BASE`, `FEATURE_BRANCH`, `PR_DRAFT`, `PR_TITLE`, and absolute `PR_BODY_FILE` environment values. Only exit zero with an absolute HTTPS URL on the last nonempty stdout line is recordable; every other result parks with exact reason `selected publishing command outcome indeterminate; re-observe whether the pull request exists before retry` and no fallback.
 Effective push-target capture and comparison are active through the package-owned `factory effective-push` command; they are not deferred to configured `publish`.
 The recorded `publishing_identity` is read from `status` exactly as reported, without trimming,

package/WORKFLOW.md

@@ -209,9 +209,40 @@ sequence with `UNKNOWN_OUTCOME_REASON`. Never repeat successful siblings.
 A budgeted attempt advances only after a complete specialist response reaches the ordinary workflow and
 that response is rejected on its merits or violates the specialist's required output contract. A complete
 unbudgeted result returns to its ordinary workflow without creating an attempt. Infrastructure recovery is
-the same attempt, not another use of `max_retries`. This rule is instruction rather than CLI enforcement:
-the host owns specialist invocation errors, while the CLI continues to enforce every durable attempt
-transition the driver actually records.
+the same attempt, not another use of `max_retries`. For a slice, an output-contract violation may advance
+only when canonical evidence and its matching REJECT review were recorded; if the malformed output prevents
+either record, park top-level `needs-human` through the common procedure instead of fabricating authority for
+N+1. This rule is instruction rather than CLI enforcement: the host owns specialist invocation errors, while
+the CLI continues to enforce every durable attempt transition the driver actually records.
+
+### Operator-authorized retry extension
+
+A slice that reached its effective retry limit remains terminal until an operator explicitly grants exactly
+one more attempt. Never edit `run.json`. Keep the top-level run in its existing parked state, claim and verify its
+fresh session lock, record a concrete reason why N+1 is now bounded and materially different, and choose one
+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"
+```
+
+`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;
+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
+append the durable authorization, preserve worktree, branch and `base_ref`, clear only the live attempt-bound
+refs, and record `running@(N+1)` while top-level status and `terminal_result` remain parked.
+
+The grant atomically moves the old canonical snapshot away so restore cannot recover pre-grant authority.
+Do not dispatch or resume yet. Republish the updated live plane, then require qualified status
+to report the refreshed `park_snapshot`, unchanged owner, the chosen new effective limit, and only the named
+slice at `running@(N+1)`. Only then run the ordinary explicit
+`factory resume "$R" --session "$SESSION_ID" --repo "$RUN_REPO"` and dispatch that attempt. Resume refreshes
+the staged workflow before its final snapshot check. A grant never invokes a specialist, unlocks, resumes,
+approves, merges, or publishes.
 
 ## The chain
 
@@ -379,6 +410,12 @@ sandbox: the completed handoff is the only thing that archives it, and that hand
 `completed`. So anything that removed the sandbox destroyed the manifest, the approved gates, the ratified
 plan and every review verdict, leaving the run neither resumable nor reconstructable.
 
+`factory snapshot "$R" --repo "$O" --json` performs this publication and is the supported way to do it.
+The steps below remain the definition of what it does; a driver may run the command instead of carrying
+them out itself, and a supervisor that parked a run out-of-band **must** run it, because `factory
+terminal` alone completes step 1 of the park and leaves no recovery evidence. It refuses a run that is
+not parked, so it cannot record a live plane as a snapshot of a moment no resume can return to.
+
 Publish the live plane `P` to `$O/.factory/.parked/$R`. Inspect `$O/.factory` and `$O/.factory/.parked` with
 non-following metadata reads, creating each missing parent one directory at a time and requiring any present
 one to be a real directory rather than a symbolic link. Never write through a symlinked parent, and never
@@ -396,12 +433,11 @@ 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, **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.
+   sorted lexically — and require exact equality, excluding only plane-root `factory.lock` and
+   `run-json.lock`. The first is session liveness and can change on a timer; the second is held by the
+   snapshot command to serialize publication with state transitions. The exclusions are those exact root
+   paths and nothing else: either name below the plane root is run state and must match. Qualified status
+   applies the same exact exclusions at a transition boundary. 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
@@ -1413,11 +1449,16 @@ For a fresh pending slice, set the exact names, require both `refs/heads/$SLICE_
 `SLICE_WORKTREE` path to be absent, and create the worktree from the current feature branch before
 activation:
 
+Before creating a pending slice worktree, reload its exact manifest row. Bind `ACTIVATION_START` to
+`FEATURE_BRANCH` when `base_ref` is null. When a restored retry-extension row preserves non-null `base_ref`,
+require its latest audit to name the same base and start the replacement slice branch at that exact historical
+base. This recreates the original retry branch without importing later sibling changes into its owned diff.
+
 ```sh
 SLICE_BRANCH="factory/$R/$SLICE_ID"
 SLICE_WORKTREE="$SLICE_ROOT/$SLICE_ID"
 CHECKED_OUT_FEATURE_BRANCH="$(git -C "$INTEGRATION_WORKTREE" symbolic-ref --quiet --short HEAD)"
-git -C "$RUN_REPO" worktree add -b "$SLICE_BRANCH" "$SLICE_WORKTREE" "$FEATURE_BRANCH"
+git -C "$RUN_REPO" worktree add -b "$SLICE_BRANCH" "$SLICE_WORKTREE" "$ACTIVATION_START"
 $ factory slice "$R" "$SLICE_ID" running --worktree "$SLICE_WORKTREE" --branch "$SLICE_BRANCH" --repo "$RUN_REPO"
 ```
 
@@ -1431,6 +1472,8 @@ Step 0. Require `run_id === R`, select exactly one `slices` row with `id === SLI
 
 ```text
 RECORDED_SLICE = parsedRun.slices row whose id equals SLICE_ID
+MAX_RETRIES = parsedRun.max_retries
+SLICE_RETRY_LIMIT = MAX_RETRIES + (RECORDED_SLICE.extra_attempts when present, otherwise 0)
 SLICE_WORKTREE = RECORDED_SLICE.worktree
 SLICE_BRANCH = RECORDED_SLICE.branch
 SLICE_BASE_REF = RECORDED_SLICE.base_ref
@@ -1444,13 +1487,15 @@ for it. A driver that assumes "this is the first try" observes as attempt 1 whil
 merge then refuses that evidence — `evidence '…' is for attempt 1, slice is at attempt 2` — after the build
 and the review have already been spent. It names the report and the `--attempt` argument below.
 
-Require the row status to be `running` or `review`, every bound value to be non-null, `SLICE_ATTEMPT` to be
-a positive integer, `SLICE_BASE_REF` to
-be a 40-character commit SHA, `SLICE_BRANCH` to equal `factory/R/<slice-id>`, and the physical
-`SLICE_WORKTREE` to equal `SLICE_ROOT/<slice-id>`. Require `git -C "$RUN_REPO" worktree list
---porcelain` to associate that physical path with that exact branch. A pending slice requires both path
-and ref to remain absent; an unrecorded existing path or ref is a collision. Refuse every mismatch
-instead of repairing, deleting, or reassociating it. A merged slice is never dispatched again.
+Require every bound value to be non-null, `MAX_RETRIES`, `SLICE_RETRY_LIMIT`, and `SLICE_ATTEMPT` to be positive integers,
+`SLICE_BASE_REF` to be a 40-character commit SHA, `SLICE_BRANCH` to equal `factory/R/<slice-id>`, and the
+physical `SLICE_WORKTREE` to equal `SLICE_ROOT/<slice-id>`. Require `git -C "$RUN_REPO" worktree list
+--porcelain` to associate that physical path with that exact branch. Before dispatch or observation require
+status `running`. A `review` row is a completed decision checkpoint: on resume consume its recorded review
+through step 4, never re-observe it. A pending slice requires path and branch ref to remain absent. Its
+base is absent unless a restored retry-extension audit preserves that immutable base; any unrecorded path
+or branch ref is a collision. Refuse every mismatch instead of repairing, deleting, or
+reassociating it. A merged slice is never dispatched again.
 
 For a non-empty `SLICE_TEST_PLAN`, select one complete entry and bind `SLICE_TEST_COMMAND` by copying
 that persisted string verbatim. Never shorten, append to, normalize, or source it from the mutable
@@ -1504,31 +1549,32 @@ Per slice:
    is no repair available at this step.** The slice is already activated, so `base_ref` is fixed; the suite
    runs in `SLICE_WORKTREE`, so a commit on the integration branch is invisible to the re-observation; and
    bringing that commit into the slice would put an out-of-lane test path in the observed diff, which the
-   merge refuses. Mark the slice `blocked`, stop dispatching its dependents, and follow the wave rule below
-   — the slices that did merge are retained on the integration branch in the retained sandbox
-   rather than discarded. A `partial` run is **surfaced, not published**: Gate 3 refuses the
-   approval that authorizes publication unless every slice is `merged`, so an operator decides
-   what to do with the merged work rather than a PR appearing for a plan that did not finish.
+   merge refuses. This is a ratified-plan conflict, not a merit REJECT: do not mark the slice `blocked`
+   without canonical evidence and a matching max-attempt review. Stop dispatching its dependents and park
+   top-level `needs-human` through the common procedure with the diagnosis below. Retain merged siblings on
+   the integration branch and the whole sandbox for operator replanning. The parked run is **surfaced, not
+   published**: Gate 3 refuses the approval that authorizes publication unless every slice is `merged`, so
+   an operator decides what to do with the work rather than a PR appearing for a plan that did not finish.
 
    **Never narrow the ratified command to get past this.** `factory observe` compares the raw supplied
    slice command with the persisted ratified entries before tokenization or execution and refuses a
-   shortened, appended, or normalized command without writing evidence. A narrowed command is a false green wearing evidence's clothes; blocking is the honest outcome when the verbatim command fails.
+   shortened, appended, or normalized command without writing evidence. A narrowed command is a false green wearing evidence's clothes; parking for replanning is the honest outcome when the verbatim command fails.
 
    If the same incompatibility instead first appears in the **integrated** suite, this step is not involved
    at all — Step 5's NO-GO repair owns it, on the branch where that suite actually runs.
 
-   When you block, record the **diagnosis** and not just the failure, in the terminal transition's
-   `--reason`: which slice owns the test, which assertion cannot hold, and what would make it hold. A
-   reason naming only "tests failed" makes the operator repeat the whole investigation, which is the
-   difference between their fix being one commit and being an afternoon.
+   When you park this plan conflict, record the **diagnosis** and not just the failure in the park
+   terminal transition's `--reason`: which slice owns the test, which assertion cannot hold, and what would
+   make it hold. A reason naming only "tests failed" makes the operator repeat the whole investigation,
+   which is the difference between their fix being one commit and being an afternoon.
 
    An out-of-lane **production** change is a different thing entirely and follows **Ownership disclosure**
    below, where the reviewer decides whether the plan or the change is wrong.
 4. **Review** — `work-reviewer` with subject `<slice-id>`, the observed evidence, the slice spec, and
    the brief. Record both refs — the merge requires each:
      ```sh
-     $ factory slice "$R" "$SLICE_ID" review --evidence-ref "evidence/$SLICE_ID.json" \
-       --review-ref "reviews/$SLICE_ID.json" --repo "$RUN_REPO"
+     $ factory slice "$R" "$SLICE_ID" review --attempts "$SLICE_ATTEMPT" \
+       --evidence-ref "evidence/$SLICE_ID.json" --review-ref "reviews/$SLICE_ID.json" --repo "$RUN_REPO"
      ```
    - On REJECT, before spending an attempt, identify the cause of the remaining failures. If the fix would
      violate an approved story or brief constraint, or repeated findings trace to the same unresolved
@@ -1538,8 +1584,26 @@ Per slice:
      If no such target can be identified, park through the existing parked-stop procedure for replanning
      or operator clarification; preserve the work and do not silently change approved acceptance criteria.
      Unchanged finding counts alone are not a stall: progress can occur within a category that remains open.
-     Otherwise route the fixes back to that builder and re-observe. After `max_retries`, mark the slice
-     `blocked` and stop dispatching its dependents.
+     Only a complete merit REJECT spends an attempt; infrastructure recovery and resume preserve
+     `SLICE_ATTEMPT` under the common rules above. Reload `RUN_MANIFEST`, require the recorded review to name
+     this slice and `SLICE_ATTEMPT` with exact verdict `REJECT`, and require the row still to be `review`.
+     If `SLICE_ATTEMPT >= SLICE_RETRY_LIMIT`, record the terminal slice state and stop dispatching its
+     dependents without creating another attempt:
+     ```sh
+     $ factory slice "$R" "$SLICE_ID" blocked --attempts "$SLICE_ATTEMPT" --repo "$RUN_REPO"
+     ```
+     Then enter the common parked-stop procedure with exact reason `blocked-after-retries`; do not
+     terminalize `partial`. The parked snapshot and retained lock are what make a later audited grant
+     reachable without weakening the terminal slice transition.
+     Otherwise bind `NEXT_SLICE_ATTEMPT = SLICE_ATTEMPT + 1` and, before redispatch, record:
+     ```sh
+     $ factory slice "$R" "$SLICE_ID" running --attempts "$NEXT_SLICE_ATTEMPT" --repo "$RUN_REPO"
+     ```
+     This retry-opening command takes no worktree, branch, evidence, or review flag. Reload the row and
+     require status `running`, attempt `NEXT_SLICE_ATTEMPT`, unchanged worktree, branch, and exact
+     `SLICE_BASE_REF`, and null evidence and review refs. The base is the immutable original branch point,
+     not merely any ancestor and not the integration head after sibling merges. Then set `SLICE_ATTEMPT` to
+     the recorded new value, route the bounded fixes back to that builder, and re-observe.
 5. **Merge (you, serially)** — on APPROVE, merge the slice branch into the feature branch one at a
    time. Builds are concurrent; merges are single-writer, which is what makes the parallelism safe.
    ```sh
@@ -1857,10 +1921,12 @@ content on those paths matches what was reviewed, so unreviewed content inside *
 while movement around it is not. What guards the branch as a whole is the integration pass: the
 validator judges the whole diff and Gate 3 will not approve unless the head it judged is still the head.
 
-Advance waves until all slices are `merged`, or a slice is `blocked`. If some merged and others
-blocked, the run is `partial` — surface it at the next gate rather than pushing on. Record a terminal
-decision only through the checked terminal command.
-Use terminal needs-human only to park a running envelope; use explicit factory resume after the cause is fixed.
+Advance waves until all slices are `merged`, or a slice is `blocked`. A blocked slice stops the wave and
+enters the common parked-stop procedure as top-level `needs-human`; retry exhaustion never terminalizes the
+run as `partial`. Use explicit factory resume only after the cause is fixed or a qualified retry grant was
+recorded and the updated plane was published. Use terminal needs-human only to park a running envelope; use explicit factory resume after the cause is fixed.
+A `partial` run is **surfaced, not published** when some other checked terminal cause creates one; retry
+exhaustion uses the parked path above instead.
 A top-level needs-human sandbox stays retained while parked and continues only after explicit factory resume.
 A `blocked` or `partial` sandbox run retains `RUN_REPO`; stale nonterminal locks retain it
 too. Nothing removes any of those sandboxes automatically. Legacy runs
@@ -2380,11 +2446,11 @@ Never re-do a side effect the manifest shows already done — ticket creation, p
   Specialists are read-only toward them and builders write code only inside the worktree they receive.
 - **Never hand-write `run.json`.** If a `factory` command refuses a transition, the refusal is the
   answer; do not work around it by editing state.
-- **Bounded loops.** `max_retries` per slice and per step, recorded as attempts. On exhaustion mark
-  `blocked` or `partial` with a reason and stop. A bounded loop parks top-level needs-human; explicit resume may repark it if the external cause remains unfixed.
-  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.
+- **Bounded loops.** Each slice is bounded by `max_retries + extra_attempts`; each step uses
+  `max_retries`. On slice exhaustion mark it `blocked` and park top-level needs-human; do not terminalize
+  `partial` solely for retry exhaustion. Explicit resume may repark if the external cause remains unfixed.
+  Qualified status reports the run's `max_retries` and each slice's effective `retry_limit`, so an
+  extended budget is observed rather than assumed.
 - **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,