feature-factory 0.7.4 → 0.8.0

package/README.md

@@ -30,7 +30,6 @@ resolved Git top level:
   "resolve": "<non-empty shell command>",
   "verify": "<non-empty shell command>",
   "publish": "<non-empty shell command>",
-  "publishing_identity": "<non-empty account name>",
   "pr_draft": true,
   "verify_timeout_ms": 900000,
   "bootstrap": "<non-empty shell command>",
@@ -38,15 +37,25 @@ resolved Git top level:
 }
 ```
 
-The root has four required properties and four optional properties: `pr_draft`, `verify_timeout_ms`,
+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. `publishing_identity` is a static non-empty account name, not a command, token, credential, or
-command result. A present `pr_draft` must be a JSON boolean and omission means `true`. Both timeouts are
+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
 operator-owned, committed, and protected as a privileged path: a run cannot create, write, merge,
 archive, package, or repair it.
 
+The publishing identity is not a config key. `factory init` resolves it from `--publishing-identity
+<account>` or the inherited `FACTORY_PUBLISHING_IDENTITY`, refuses when neither supplies at least one
+character, and records the resolved value immutably in `run.json`, where `status --json` reports it as
+`publishing_identity`. The account a run publishes as is a property of the environment it runs in, not of
+the repository, and a tracked file cannot hold two values for one repository published from both a
+maintainer's checkout and an automated host. Absence refuses rather than skipping the guard, so a forgotten
+value stops the run instead of publishing under whatever credential the host happens to carry. Never derive
+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.
 
 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`.
@@ -200,18 +209,19 @@ 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`, `verify`, and `publishing_identity` are consumed now. Configured `publish` remains unconsumed and is not invoked.
+`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.
 Effective push-target capture and comparison are active through the package-owned `factory effective-push` command; they are not deferred to configured `publish`.
-The validated raw `publishing_identity` is retained exactly as parsed, without trimming, normalization,
-case-folding, or reserialization. A missing, non-string, or whitespace-only identity makes a present
-config malformed. `publishing_identity` itself adds no config key or syntax, run status, or factory command. The independent `factory effective-push` command adds no state or flag.
+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
+supplies at least one character, so a created run always carries one; only a manifest written before 0.8.0
+can report `null`. `publishing_identity` is a recorded run field reported by `status`, resolved by `init` from a flag or the environment. The independent `factory effective-push` command adds no state or flag.
 
-With a present valid config, every mode checks that identity at exactly three boundaries: immediately
+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. An absent config skips all three guards and
-preserves existing behavior.
+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
 means identity is unobservable without invoking `gh`, the network, stored authentication, credential

package/WORKFLOW.md

@@ -243,7 +243,6 @@ The optional repository-owned file is `$O/.factory.json`:
   "resolve": "<non-empty shell command>",
   "verify": "<non-empty shell command>",
   "publish": "<non-empty shell command>",
-  "publishing_identity": "<non-empty account name>",
   "pr_draft": true,
   "verify_timeout_ms": 900000,
   "bootstrap": "<non-empty shell command>",
@@ -251,11 +250,13 @@ The optional repository-owned file is `$O/.factory.json`:
 }
 ```
 
-The root must be a JSON object with the four required own properties `resolve`, `verify`, `publish`, and
-`publishing_identity`, plus only the optional own properties `pr_draft`, `verify_timeout_ms`, `bootstrap`, and
+The root must be a JSON object with the three required own properties `resolve`, `verify`, and `publish`,
+plus only the optional own properties `pr_draft`, `verify_timeout_ms`, `bootstrap`, and
 `bootstrap_timeout_ms`. `resolve`, `verify`, `publish`, and `bootstrap` are command strings; every present
-command must be non-empty. `publishing_identity` is a static non-empty publishing account name in the
-file itself, not a command, token, credential, or command result. `pr_draft` must be a JSON boolean
+command must be non-empty. There is no `publishing_identity` key: the account a run publishes as is a
+property of the environment it runs in, not of the repository, and a tracked file cannot hold two values
+for one repository published from both a maintainer's checkout and an automated host. A file carrying that
+key is malformed, because the optional set above is closed. `pr_draft` must be a JSON boolean
 when present and defaults to `true` when absent. Both timeout values must be positive
 safe integers when present, and `bootstrap_timeout_ms` is valid only with a declared `bootstrap`.
 `verify_timeout_ms` and `bootstrap_timeout_ms` each independently default to `900000` milliseconds;
@@ -270,15 +271,31 @@ The two bootstrap keys are known keys. Invalid `bootstrap` outranks missing requ
 timeout defect, including an invalid or otherwise orphaned bootstrap timeout. An orphaned
 `bootstrap_timeout_ms` outranks its own invalid shape, and a valid bootstrap with an invalid timeout
 names only `bootstrap_timeout_ms`. Validate this order before executing `resolve`.
-Retain the validated `publishing_identity` string exactly as parsed, without trimming,
-normalizing, case-folding, or reserializing it, as `DECLARED_PUBLISHING_IDENTITY` for this driver
-invocation. Do not tighten the existing non-whitespace validation to the observed-login grammar.
+The publishing identity is not read from this file and not resolved by the driver. `factory init` resolves
+it in code -- `--publishing-identity <account>` when passed, otherwise the inherited
+`FACTORY_PUBLISHING_IDENTITY` -- and refuses when neither supplies at least one character, creating no
+sandbox and no run. It records the resolved value immutably in `run.json`, and `status --json` reports it
+as `publishing_identity`. Bind `DECLARED_PUBLISHING_IDENTITY` from that reported value exactly as
+reported, without trimming, normalizing, case-folding, or reserializing it, and never re-resolve it from
+the environment, a file, or anything else.
+Do not tighten the existing non-whitespace validation to the observed-login grammar: `init` requires only
+that the value contain at least one character, and a declared account name that the observed-login grammar
+would reject is still a legitimate declaration to compare against.
+Never pass `--publishing-identity` from this workflow. The driver has no source for the value -- that is
+the point of resolving it in the CLI -- so the flag would be constructed from an unbound shell variable,
+expand to an empty argument, and be indistinguishable from an operator supplying one. `init` reads the
+inherited environment itself. The flag exists for an explicit human or scripted invocation that has a value
+to state.
+Because init refuses without one, every run created at or after 0.8.0 carries a nonempty value; a manifest
+written earlier may report `null`, which is the only case that skips the publishing-identity guards.
+Never derive this value from `gh`, the token, stored authentication, or Git configuration: an expectation
+read from the credential being checked would always match, and the guard would stop guarding.
 Credential values must not appear in the file; command strings may refer only to credentials supplied
 through inherited environment-variable names.
 
-An absent `$O/.factory.json` means no resolver is declared and no publishing identity is declared, per
-the absence rule below. Do not bind `DECLARED_PUBLISHING_IDENTITY` and skip every publishing-identity
-guard, preserving the existing behavior. If the path is present but malformed, do not execute any entry
+An absent `$O/.factory.json` means no resolver is declared, per the absence rule below. It says nothing
+about the publishing identity, which comes from `init` rather than from this file, so a repository with no
+config file still carries a recorded identity and still runs every publishing-identity guard. If the path is present but malformed, do not execute any entry
 and refuse exactly:
 
 > invalid factory config: .factory.json; no session or run created.
@@ -394,7 +411,8 @@ init and explicit resume. Neither applies to `resolve`, slice observation, or Ga
 change platform placement, background-tool, title-association, host-session, or publication behavior.
 `story-reader` remains lookup-free and capability-free beyond its existing generic read tools.
 
-`resolve`, `verify`, and `publishing_identity` are consumed now. Configured `publish` remains unconsumed and is not invoked.
+`resolve` and `verify` are consumed now, and the run's recorded `publishing_identity` is compared at the
+guards below. Configured `publish` remains unconsumed and is not invoked.
 
 Configured `bootstrap` is consumed only by CLI-owned fresh init and explicit resume; the workflow consumer validates it but never executes it itself.
 
@@ -405,7 +423,7 @@ Effective push-target capture and comparison are active through the package-owne
 | `bootstrap` | Exact configured string as one shell command with `shell: true`, inherited environment and stdin, cwd exactly the selected sandbox, and child stdout and stderr both routed to CLI stderr. Each execution receives its own `bootstrap_timeout_ms`, independently `900000` when omitted. | Numeric exit status or unavailable `null`; output is visible on CLI stderr and never parsed | Clean zero succeeds; dirty or unobservable tracked state outranks unavailable or nonzero exit | Invoked by the CLI once during configured fresh init and again on every explicit configured resume; never invoked by resolver, merge verification or replay, direct repository verification, slice or Gate 3 observation, effective push, or publication. |
 | `verify` | Ordinary shell step in the exact integration-worktree cwd with inherited environment; no structured stdin or factory-specific payload is defined. Each attempt receives the full configured `verify_timeout_ms`, silently `900000` when omitted. | Exit status is authoritative; stdout and stderr are inherited, informational, and unparsed | Zero means success; non-zero means repository verification failed; no numeric child status means unavailable | Invoked after each newly recorded merge through `observe --repository-verify`, with at most two executions in that merge invocation. The timeout and retry never apply to resolver, slice, or Gate 3 commands. |
 | `publish` | Future ordinary shell step in repository-root cwd with inherited environment; no structured stdin or factory-specific payload is defined | Exit status is authoritative; stdout is informational and unparsed | Zero means the command reported success; non-zero means it reported failure | Not invoked. Existing `git push`, `gh pr create`, and `factory pr` behavior remains unchanged; effective push-target equality is enforced separately by <code>factory effective-push</code>. |
-| `publishing_identity` | No runtime input; retain the raw validated config string for this driver invocation | Exact case-sensitive string compared with the observed login | Missing, non-string, or whitespace-only makes the config malformed; mismatch or unobservable identity parks the run | Active at the three mandatory guards below; absent config preserves existing behavior. |
+| `publishing_identity` | No runtime input; read the value `status` reports for the run, recorded at init from `--publishing-identity` or the inherited `FACTORY_PUBLISHING_IDENTITY` | Exact case-sensitive string compared with the observed login | Absent at init refuses before any sandbox exists; mismatch or unobservable identity parks the run | Active at the three mandatory guards below; only a manifest written before 0.8.0 can report `null` and skip them. |
 
 When both bootstrap keys are absent, init and resume are exact no-ops for bootstrap: no execution, manifest fields, output, or response-shape change.
 
@@ -498,10 +516,10 @@ path not disclosed and verified for this recovery. Without a path omission, skip
 In either case order 7 remains the same explicit resume command; the resume command never amends paths,
 changes `test_plan`, or reseeds the plan.
 
-When a validated present config declares `publishing_identity`, the mandatory guard below is the exact
+When the run reports a nonempty `publishing_identity`, the mandatory guard below is the exact
 boundary between completion of resume order 7 and the first operation in resume order 8. Nothing may
 intervene between the verified running/same-owner result and that guard, or between a successful guard
-and reconciliation. An absent config preserves the nine orders without adding an operation.
+and reconciliation. A pre-0.8.0 manifest reporting `null` preserves the nine orders without adding an operation.
 
 For order 1 require the intended run ID, a valid manifest, recorded branch and mode, current parked status, and the original terminal result. Order 2 stays after selection and containment and before effective-push proof. Order 3 never absorbs containment, binding, or the post-selection exact-ref guard. During order 4 preserve every existing exact-ref recheck and the stated provenance sequence. No unrelated observation or effect occurs between order 5 and claim or justified steal. Order 6 requires `lock_session === SESSION_ID`, a fresh lock, unchanged parked status, and a terminal result deeply equal to the one first observed. Invoke `factory resume "$R" --session "$SESSION_ID" --repo "$RUN_REPO"` for order 7 — the same session order 6 just verified as the fresh owner — then require that owner unchanged. Resume refuses without it, and refuses a lock that is absent, stale, or held by anyone else. Order 8 may replay only the existing recorded-merge reconciliation path and must not move pre-lock proofs across the lock boundary. Order 9 never uses the pre-resume observation or the stop reason.
 

package/bin/factory.js

@@ -27,7 +27,7 @@ import {
 } from "../state/session-lock.js";
 
 export const COMMANDS = Object.freeze({
-  init: Object.freeze(["--repo", "--branch", "--worktree", "--pr-base", "--issue", "--issue-key", "--mode", "--max-parallel-slices", "--max-retries", "--now", "--json"]),
+  init: Object.freeze(["--repo", "--branch", "--worktree", "--pr-base", "--issue", "--issue-key", "--publishing-identity", "--mode", "--max-parallel-slices", "--max-retries", "--now", "--json"]),
   status: Object.freeze(["--repo", "--json"]),
   "amend-paths": Object.freeze(["--repo", "--add", "--reason", "--session", "--now", "--json"]),
   resume: Object.freeze(["--repo", "--session", "--now", "--json"]),
@@ -902,6 +902,7 @@ const HANDLERS = {
       mode: run.mode,
       branch: run.branch,
       pr_base: run.pr_base ?? null,
+      publishing_identity: run.publishing_identity ?? null,
       pr_draft: run.pr_draft ?? true,
       lock: lock.state, dead_lock: run.status === "running" && lock.state === "stale",
       lock_session: lock.owner?.session ?? null,
@@ -1372,6 +1373,22 @@ function preflightInit(positional, flags) {
   // the flag, so a run that had read its real issue recorded none. Disagreement refuses, because the key is
   // appended as `Closes #<key>` and preferring one silently would close a stranger's issue.
   if (flags.issue !== undefined && flags.issueKey !== undefined && flags.issue !== flags.issueKey) throw refusal("--issue and --issue-key disagree; pass one");
+  // Enforcement: the publishing identity is the expectation every publication guard compares the observed
+  // `gh api /user` login against, so a run without one publishes unchecked. It used to be a required key in
+  // the checked-in `.factory.json`, which cannot hold two values for one repository published from two
+  // environments -- 0.7.5 tried an environment override read by the driver, and the driver never looked.
+  // Resolved here instead, in code, so no agent has to comply: the flag wins, then the environment.
+  // Absence refuses rather than skipping the guard, because a forgotten value must not silently publish
+  // as whatever credential the host happens to carry.
+  // `??` was wrong here: it falls through only on nullish, so `--publishing-identity ""` -- what an unbound
+  // shell variable expands to -- would mask a perfectly good inherited value and refuse the run. Both
+  // sources are held to the same rule instead: a source counts only if it carries at least one character,
+  // and the flag wins over the environment only when it actually supplies one.
+  const publishingIdentity = [flags.publishingIdentity, process.env.FACTORY_PUBLISHING_IDENTITY]
+    .find((candidate) => typeof candidate === "string" && candidate.length > 0);
+  if (publishingIdentity === undefined) {
+    throw refusal("factory init requires a publishing identity; pass --publishing-identity <account> or set FACTORY_PUBLISHING_IDENTITY");
+  }
   const runId = positional[0];
   try {
     const at = stamp(flags);
@@ -1379,6 +1396,7 @@ function preflightInit(positional, flags) {
       version: SCHEMA_VERSION,
       run_id: runId,
       issue_key: flags.issue ?? flags.issueKey ?? null,
+        publishing_identity: publishingIdentity,
       branch: flags.branch ?? `feature/${runId}`,
       worktree: flags.worktree ?? ".",
       pr_base: flags.prBase ?? null,

package/observe/repository-config.js

@@ -11,7 +11,12 @@ export function parseRepositoryConfig(bytes) {
   } catch {
     throw new RepositoryConfigError("invalid .factory.json");
   }
-  const requiredKeys = ["publish", "publishing_identity", "resolve", "verify"];
+  // 0.8.0 dropped `publishing_identity`: the account a run publishes as belongs to the environment it runs
+  // in, not to a tracked file that can hold one value for a repository published from two of them. It is
+  // resolved by `init` from a flag or the environment and recorded in `run.json`. The allowed set below is
+  // closed, so a file still carrying the key is malformed rather than silently ignored -- which is what
+  // makes the removal visible to whoever has to edit it.
+  const requiredKeys = ["publish", "resolve", "verify"];
   const allowedKeys = [...requiredKeys, "pr_draft", "verify_timeout_ms", "bootstrap", "bootstrap_timeout_ms"];
   if (!config || typeof config !== "object" || Array.isArray(config)
     || Object.keys(config).some((keyName) => !allowedKeys.includes(keyName))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-factory",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,6 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --import ../../tools/resolve-guard.mjs --test test/*.test.js"
+    "test": "FACTORY_PUBLISHING_IDENTITY=factory-test node --import ../../tools/resolve-guard.mjs --test test/*.test.js"
   }
 }

package/state/schema.js

@@ -15,6 +15,10 @@ export const RUN_KEYS = Object.freeze([
   "version", "run_id", "issue_key", "branch", "worktree", "pr_base", "pr_draft", "created_at", "updated_at",
   "status", "mode", "max_parallel_slices", "max_retries",
   "gates", "steps", "slices", "validator", "terminal_result", "pr_url",
+  // Recorded at init from the flag or the environment, never from a checked-in file: the account
+  // a run is expected to publish as is a property of where it runs, not of the repository. Absent
+  // only in manifests written before 0.8.0, which still read.
+  "publishing_identity",
   // Digest of the plan bytes the brief gate approved, so the seed ratifies that plan and not a
   // later edit of the same filename. See the check in `slices-seed`.
   "plan_digest",
@@ -109,7 +113,7 @@ export function validateRun(run) {
   for (const key of ["branch", "worktree"]) required(errors, run, key, "run");
   for (const key of ["created_at", "updated_at"]) pattern(errors, run, key, ISO, "run");
   for (const key of ["max_parallel_slices", "max_retries"]) positiveInt(errors, run, key, "run");
-  for (const key of ["issue_key", "pr_base", "pr_url", "plan_digest"]) optionalString(errors, run, key, "run");
+  for (const key of ["issue_key", "pr_base", "pr_url", "plan_digest", "publishing_identity"]) optionalString(errors, run, key, "run");
   if (Object.hasOwn(run, "pr_draft") && typeof run.pr_draft !== "boolean") {
     errors.push({ path: "run.pr_draft", message: "must be a boolean" });
   }