feature-factory 0.8.3 → 0.8.5

package/WORKFLOW.md

@@ -99,36 +99,52 @@ must APPROVE before you accept that step. Story, research, and design are not au
 
 Before any intake action, including ticket, story, or design detection, branch intent, run-id
 derivation, manifest or state reads, and every `factory` command, process the raw invocation arguments
-as follows. The platform skill first performs any host-specific placement admission and supplies this
-workflow the unchanged admitted request. Placement is not a run mode.
-
-Ignore leading whitespace. The **mode prefix** is the maximal consecutive sequence of
-whitespace-delimited tokens that are exactly and case-sensitively `--autonomous` or `--headless`.
-The first other token ends the prefix.
-
-1. If both distinct flags occur in that prefix, in either order, return exactly:
+as follows.
+
+**The platform skill owns invocation-option admission, and this workflow never parses the
+invocation.** Each host skill defines the complete leading option prefix its `/feature` invocation
+accepts -- placement, mode, and host options such as `--base` and `--max-retries` -- consumes exactly
+those spans and their separators, and supplies this workflow two things: the **admitted mode tokens**,
+which are the exact case-sensitive `--autonomous` and `--headless` tokens it consumed, and the
+**admitted remainder**, the request bytes beginning at the first token it did not consume, preserved
+unchanged. This workflow never decides where that prefix ends. Placement is not a run mode.
+
+Defining a terminator here would contradict the skill that already applied one, and every option later
+added to a host would become request content on this side only. That is not hypothetical. `--base` and
+`--max-retries` were added to the host skills while this section still ended the prefix at the first
+non-mode token, so the two documents disagreed over whether `--max-retries 5 <run-id>` was an option
+pair or part of the run id. Read alone, this section silently derived the run id `max-retries-5-1606`;
+read alongside the skill, a driver correctly refused to run at all. Both documents governing the same
+bytes is the defect, so only one of them does.
+
+The rules below are host-independent and are stated over the admitted mode tokens and the admitted
+remainder.
+
+1. If both distinct mode tokens were admitted, in either order, return exactly:
    `conflicting mode flags: --autonomous and --headless; choose one`. Return immediately, before any
    intake, run-id derivation, state read, or CLI action. Never fall back to interactive or another
    mode.
-2. Otherwise remove every token in the recognized prefix and its separating whitespace. Use only the
-   unchanged remainder for ticket detection, story content, design detection, branch intent, and
-   run-id derivation.
+2. Otherwise use only the unchanged admitted remainder for ticket detection, story content, design
+   detection, branch intent, and run-id derivation.
 3. Apply exactly one mapping for a new manifest:
    - `--autonomous` maps only to `factory init --mode autonomous`.
    - `--headless` maps only to `factory init --mode headless`.
-   - With no recognized leading mode token, omit `--mode`; existing `factory init` records
+   - With no admitted mode token, omit `--mode`; existing `factory init` records
      `interactive`.
 
-Those three compatibility phrases name init command stems, not runnable invocations. The selected
-fresh-run invocation is fully qualified in Step 0 and ends with `--repo "$RUN_REPO"`.
+Those three compatibility phrases name init command stems, not runnable invocations. The one runnable
+fresh-run invocation is the fully qualified command block in Step 0; copy that block rather than
+assembling init from the phrases here. It is the single factory invocation whose repository flag is
+`--repo "$O"`, and it ends with `--json`.
 
-Repeated copies of one recognized flag are idempotent: remove them all and select that mode once. An
-exact mode token after the first other token is request content and neither selects nor conflicts.
+Repeated copies of one mode token are idempotent: the skill consumes them all and this workflow
+selects that mode once. A mode token the skill did not admit, standing after the first request token,
+is request content and neither selects nor conflicts.
 Natural-language intent, `--interactive`, capitalization variants, abbreviations, assignment or
 punctuation forms, quoted lookalikes, and near misses are request content, not selectors. Do not add a
 generic malformed-option rejection.
 
-After successful nonconflicting admission, reject an empty, whitespace-only, or mode-only remainder
+After successful nonconflicting admission, reject an empty or whitespace-only admitted remainder
 with exactly `missing /feature request; no run created.` This rejection and a mode conflict precede
 run-id derivation and every tool, client, state, or CLI action.
 
@@ -661,11 +677,19 @@ present and every other result is a lookup error; either refuses before init.
 
 An explicit `PR_BASE` wins. Otherwise require the symbolic branch in the configured operator worktree;
 detached, missing, escaping, or unprovable worktree state is refused by init. Request one fresh sandbox
-with the operator repository as `--repo`, command first and repository flag last, and include issue and
-admitted mode flags only when present:
+by running exactly the command below, command first, including each bracketed flag only when its value
+is present. Do not reconstruct this command from prose anywhere in this document: the block is the only
+shape, and every host skill carries it verbatim because a driver must run it before this file exists.
+
+Two properties of it are not guesses. Init is the one factory command whose repository flag is the
+operator repository `$O` rather than `$RUN_REPO`, because `RUN_REPO` does not exist until this response
+binds it. And `--json` is mandatory and terminal: without it a successful init still changes state and
+publishes `run.json`, but this workflow binds paths only from a JSON response, repeating init is
+forbidden, and the run can then do nothing but stop -- a live sandbox with `status: running` and no
+driver, which is the worst outcome this document has.
 
 ```sh
-INIT_RESPONSE="$(factory init "$R" --branch "$FEATURE_BRANCH" [--worktree "$WORKTREE"] [--pr-base "$PR_BASE"] [--issue "$KEY"] [--mode "$MODE"] --repo "$O" --json)"
+INIT_RESPONSE="$(factory init "$R" --branch "$FEATURE_BRANCH" [--worktree "$WORKTREE"] [--pr-base "$PR_BASE"] [--issue "$KEY"] [--mode "$MODE"] [--max-retries "$MAX_RETRIES"] --repo "$O" --json)"
 ```
 
 The init request pre-reserves the deterministic sandbox, performs exactly one
@@ -2091,6 +2115,9 @@ Never re-do a side effect the manifest shows already done — ticket creation, p
   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.
 - **Draft PR only.** Never merge, force-push, or close tickets. Humans merge.
 - **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.

package/bin/factory.js

@@ -953,6 +953,11 @@ const HANDLERS = {
       mode: run.mode,
       branch: run.branch,
       pr_base: run.pr_base ?? null,
+      // Reported, not defaulted: `max_retries` is a required schema-validated positive integer, so an
+      // absent value is an invalid manifest that never reaches here. An operator forwarding
+      // `--max-retries` previously had no way to confirm the budget took effect -- init recorded it and
+      // nothing read it back.
+      max_retries: run.max_retries,
       publishing_identity: run.publishing_identity ?? null,
       park_snapshot: run.status === "needs-human" ? observedParkSnapshot(resolve(flags.repo ?? process.cwd()), runId, runDir) : null,
       pr_draft: run.pr_draft ?? true,

package/package.json

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