feature-factory 0.9.2 → 0.10.1

package/README.md

@@ -20,6 +20,16 @@ host binding and copies this workflow beside that skill at build/pack time. Inst
 `opencode-feature-factory` or `prime-agent-feature-factory` for a supported host, or build an adapter
 that loads the complete workflow and drives all durable state changes through the CLI.
 
+## Infrastructure failures and attempts
+
+A confirmed host-origin availability or transport failure does not spend a specialist attempt. The active
+driver permits one same-attempt recovery for the canonical role and subject only when the host proves
+execution never started or can recover the same child/session. Unbudgeted research and design create no
+attempt. A second consecutive failure parks the run. The count is memory-only and resets with the driver,
+but resume and reset never prove that prior work did not start: the next driver must recover or prove the
+same prior invocation safe before dispatch. Child text, unknown errors, and excluded auth, quota,
+rate-limit, and configuration failures never trigger a free retry or duplicate possibly-started work.
+
 ## Repository command configuration
 
 A repository operator may provide optional `$O/.factory.json`, where `O` is the physically
@@ -37,9 +47,9 @@ resolved Git top level:
 }
 ```
 
-The root has three required properties and four optional properties: `pr_draft`, `verify_timeout_ms`,
-`bootstrap`, and `bootstrap_timeout_ms`. `resolve`, `verify`, `publish`, and a present `bootstrap` are non-empty command
-strings. There is no `publishing_identity` key, and a file carrying one is malformed because the
+The root has two required properties, `resolve` and `verify`, and five optional properties: `publish`,
+`pr_draft`, `verify_timeout_ms`, `bootstrap`, and `bootstrap_timeout_ms`. Required commands and any present
+`publish` or `bootstrap` are non-empty strings. There is no `publishing_identity` key, and a file carrying one is malformed because the
 optional set is closed. A present `pr_draft` must be a JSON boolean and omission means `true`. Both timeouts are
 positive safe integers. `bootstrap_timeout_ms` requires `bootstrap`.
 Each omitted timeout independently defaults to `900000`; neither shares the other's budget. The file is
@@ -56,7 +66,7 @@ value stops the run instead of publishing under whatever credential the host hap
 it from `gh`, the token, stored authentication, or Git configuration: an expectation read from the
 credential being checked would always match.
 
-Validation refuses the first matching defect in this order: unreadable or invalid JSON, a non-object root, or unknown keys; invalid `pr_draft`; invalid `bootstrap`; `bootstrap_timeout_ms` without `bootstrap`; invalid `bootstrap_timeout_ms`; invalid `verify_timeout_ms`; then missing or invalid required entries.
+Validation refuses the first matching defect in this order: unreadable or invalid JSON, a non-object root, or unknown keys; invalid `pr_draft`; invalid `bootstrap`; `bootstrap_timeout_ms` without `bootstrap`; invalid `bootstrap_timeout_ms`; invalid `verify_timeout_ms`; missing or invalid required entries; then invalid `publish`.
 
 The named forms are `.factory.json entry 'pr_draft' must be a boolean`, `.factory.json entry 'bootstrap' must be a non-empty string`, `.factory.json entry 'bootstrap_timeout_ms' requires a declared bootstrap command`, `.factory.json entry 'bootstrap_timeout_ms' must be a positive integer`, and `.factory.json entry 'verify_timeout_ms' must be a positive integer`.
 
@@ -113,10 +123,14 @@ removed the sandbox destroyed the manifest and every accepted gate with it. `.pa
 id, so a snapshot never occupies the completed archive at `$O/.factory/<R>` and never blocks
 re-initialising the same run id. It is published by a staged, verified swap, so a failed later park cannot degrade the last good
 snapshot. A failed snapshot is reported and never prevents the park. `blocked`
-and `partial` are not snapshotted, and a snapshot is evidence for recovery rather than a resumable run.
-
-Qualified status reports `park_snapshot` for a parked run: the published path, or `null` when no snapshot
-exists. That is how an outside observer verifies the snapshot happened rather than assuming it.
+and `partial` are not snapshotted. A retained sandbox resumes directly; when that sandbox is lost,
+`factory restore <R> --repo <O> --from refs/remotes/<remote>/<feature-branch>` rebuilds a parked,
+lockless sandbox from the snapshot and the exact pushed feature ref. It reports every active slice reset
+to `pending` rather than claiming branch-local work survived.
+
+Qualified status reports `park_snapshot` for an unchanged live park: the published path, or `null` when no
+matching snapshot exists. A restored generation deliberately reports `null` because its manifest and path
+bindings changed; `status.restore` carries its source digest, feature commit, resets, and invalidations.
 Malformed config, malformed payload, a non-zero exit, or unavailable exit status refuses before any
 run effect and never falls back:
 
@@ -144,7 +158,7 @@ A failed, timed-out, dirty, or unobservable fresh init emits no JSON stdout, ret
 
 When both bootstrap keys are absent, init and resume are exact no-ops for bootstrap: no execution, manifest fields, output, or response-shape change.
 
-Bootstrap never runs during resolver intake, merge verification or replay, direct repository verification, slice observation, Gate 3, effective push, configured publication, push, or PR creation. Existing resolver, verify, configured-publish, effective-push, push, PR, and Gate 3 behavior is unchanged.
+Bootstrap never runs during resolver intake, merge verification or replay, direct repository verification, slice observation, Gate 3, effective push, configured publication, push, or PR creation. Bootstrap does not mediate configured publication, effective-push, push, PR, or Gate 3 behavior.
 
 After a slice merge is successfully and atomically recorded, `verify` starts in the exact recorded
 integration worktree. Its configured string is submitted unchanged as one ordinary shell command with
@@ -190,6 +204,30 @@ Gate 3 always runs a separate fresh integrated `test-verifier` observation at th
 overwrites canonical evidence through the existing command mode and never shares, substitutes, or
 optimizes from post-merge evidence, even when the head is unchanged.
 
+## Restoring a lost parked sandbox
+
+Run restore from the canonical operator repository, not from a replacement checkout:
+
+```sh
+factory restore <run-id> --repo <operator-repository> \
+  --from refs/remotes/<remote>/<recorded-feature-branch> --json
+```
+
+The source must be the canonical `$O/.factory/.parked/<run-id>` snapshot. The feature ref must be a full
+remote-tracking ref whose branch suffix exactly matches the manifest and whose commit is still advertised
+by that remote's push endpoint, exactly equal to the operator effective push endpoint. Restore validates
+that snapshot, refuses symlinks that escape its control plane, clones the exact derived sandbox, aligns and
+rechecks the operator's effective push target, and proves every preserved merged-slice Git and evidence
+binding against the pushed head. It omits the old root session lock and publishes the transformed manifest
+last. The run stays parked and no repository-configured bootstrap runs. Nonmerged slices with physical
+branch or worktree state reset to `pending`, and the command reports them. Stale HEAD-bound validator
+approval is invalidated. Gate 3 and test-verifier approval are always invalidated because canonical
+publication evidence names the prior physical generation; canonical verifier records are omitted from the
+copy. The staged slice projection must still match the Brief-bound plan digest and recorded amendments.
+The durable `status.restore` record identifies the source inventory and restored commit. Because the new
+generation has different paths and provenance, `status.park_snapshot` is `null` after a successful restore.
+Claim the new lock and use the ordinary resume sequence only after reviewing those losses.
+
 ## Resuming a parked run
 
 A top-level `needs-human` status is a parked stop, not a final result. `completed`, `partial`, and
@@ -220,7 +258,18 @@ 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.
 
-`resolve` and `verify` are consumed now, and the run's recorded `publishing_identity` is compared at the publication guards. Configured `publish` remains unconsumed and is not invoked.
+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,
 normalization, case-folding, or reserialization. `init` refuses when neither the flag nor the environment
@@ -230,8 +279,8 @@ can report `null`. `publishing_identity` is a recorded run field reported by `st
 With a recorded identity, every mode checks it at exactly three boundaries: immediately
 after verified post-lock ownership, or immediately after an explicit resume is verified running with
 the same fresh owner and before reconciliation or other work; immediately before `git push`, after
-effective push-target equality; and immediately before `gh pr create`, after the push is known
-successful. No operation intervenes across a guard boundary. Only a manifest written before 0.8.0, which can
+effective push-target equality; and immediately before the selected PR-creation command, after the
+factory-owned exact push is known successful. No operation intervenes across a guard boundary. Only a manifest written before 0.8.0, which can
 report `null`, skips all three guards; an absent config does not affect them.
 
 Before each guard, inherited `GH_TOKEN` must exist and contain at least one character. Missing or empty
@@ -268,7 +317,7 @@ session.
 
 Publishing-identity verification is enforcement because it prevents false-green or wrong-account
 publication. Credential provisioning and helper setup are instruction only. Existing push,
-`gh pr create`, `factory pr`, Gate 3, merge, and approval semantics remain unchanged. The live config
+`factory pr`, Gate 3, merge, and approval semantics remain unchanged. The live config
 is not part of this package and no generated config or resolver asset is shipped. See the repository's
 [operator guide](https://github.com/jasoncarreira/feature-factory/blob/main/OPERATING.md) for the
 shared inherited-token helper recipe; it does not acquire, store, install, or repair credentials.
@@ -285,7 +334,12 @@ repositories and compares them exactly. `check` freshly captures both targets an
 configuration. Both modes use shell-free Git subprocesses, write no output on success, and retain the
 sandbox on a fixed redacted failure. Captured targets and child diagnostics are never returned, logged,
 persisted in factory state, printed, or attached as an error cause. The command is independent of
-`publishing_identity`, adds no run state or flag, and configured `publish` remains unconsumed.
+`publishing_identity` and adds no run state or flag. After the factory-owned exact push and post-push
+identity guard, Step 6 resolves one PR-creation 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 the
+selected nondefault command replaces `gh pr create`, so a repository declaration cannot leave a host with
+nothing to delegate to unable to publish at all.
 
 ## Why the code exists at all