feature-factory 0.10.5 → 0.10.7

package/WORKFLOW.md

@@ -909,6 +909,12 @@ with `git check-ref-format --branch "$FEATURE_BRANCH"`. Bind
 `git -C "$O" show-ref --verify --quiet "$FEATURE_REF"` to exit exactly 1 for ref absence. Exit 0 means
 present and every other result is a lookup error; either refuses before init.
 
+Bind `KEY` from how `R` was bound, never from anything else: when the configured resolver returned a
+payload, `KEY` is exactly `R`, its `run_id`; when `R` is a ticket key from the request or branch, `KEY`
+is that key; when `R` was derived from free text, `KEY` is absent and `--issue` is omitted. Never add a
+`#` or other decoration. `issue_key` is immutable after init, and publication reads it for the title
+prefix and closing reference, so a run whose resolver found issue `25` must record `25`.
+
 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
 by running exactly the command below, command first, including each bracketed flag only when its value
@@ -1521,6 +1527,14 @@ Per slice:
    not a detail to reconcile in your head. Omit `--test-cmd` and the slice is not `review_ready`
    unless its ratified `test_plan` is empty — the waiver comes from the plan, not from you.
 
+   When `.factory.json` declares `verify`, this step also runs it on the slice's commit, after the
+   ratified test command and with `FACTORY_VERIFY_SCOPE=slice` in its environment, and records the
+   result as `repository_verify`. A failing repository verify makes the slice not `review_ready`, the
+   same as a failing test, so the review rejects and the slice retries; an empty `test_plan` does not
+   waive it. Its output appears on stderr: give the failing part of it (the lint, format, or test
+   failure) to the builder with the rejection, because otherwise the retry cannot see what to fix. This
+   is what keeps a one-line lint failure from surfacing only after merge, where it cannot be repaired.
+
    `BUILDER_REPORT` is a path and not the report. Write the builder's returned report to
    `BUILDER_REPORT=".factory/$R/artifacts/$SLICE_ID-builder-attempt-$SLICE_ATTEMPT.json"` and pass that path,
    which keeps the report beside the run's other evidence instead of in argv. It holds `status`, `slice`,
@@ -1700,7 +1714,7 @@ Gate 3 remains a fresh independent observation.
 
 ### Post-merge finding routing and repair journal
 
-Route a known post-merge failure before any next-wave action. A production defect parks top-level needs-human; after the external fix, explicitly resume the intact run.
+Route a known post-merge failure before any next-wave action. A production defect parks top-level needs-human. There is no in-band resume for it: production source is never repaired on the integration branch, and a configured command reruns only after a test-only repair. Say so in the reason, and name preserving the feature branch and starting a fresh run as the recovery; do not tell the operator to resume.
 Production source is never repaired on the integration branch. Unclassifiable,
 interrupted-unknown, invalid-config, unsafe dirty or moved replay, unobservable, journal-invalid, or
 repair-exhausted outcomes also terminalize. Clean unchanged repository-verification exhaustion follows

package/agents/spec-writer.md

@@ -49,6 +49,11 @@ Resolve every ambiguity so builders don't have to. Follow the repository's agent
 - Auth/role gating
 - Test plan: unit tests, and acceptance (which criterion maps to which test, and at what level)
 - **Class-wide work:** convert the research inventory into a closed implementation matrix — one row per sink/call site, each assigned an exact primitive/policy, a compatibility (preserve/migrate) or explicit exclusion decision, and a mapped test. No sink is left to the builder to discover.
+- **Document deliverables:** when the issue's deliverable is a specification, contract, or data artifact
+  rather than executable behavior, the brief specifies the content each AC requires and nothing more. Do
+  not expand "test vectors", "examples", or "fixtures" into an executable model, a validator, or an
+  exhaustive corpus unless a criterion says so; an edge case beyond the criteria gets a documented limit,
+  not new mechanism.
 
 ## Output contract
 

package/agents/work-reviewer.md

@@ -78,6 +78,35 @@ When the subject is a **class-wide** requirement — one that **cannot be establ
 - **Precedence for late discoveries:** a genuinely required sink, policy, compatibility decision, migration, or test that is missing is a **blocker no matter which review round surfaces it** — record it once in `required_fixes`, carry it into every later review, and REJECT until observed evidence proves it landed. Only *unrelated* new scope or *optional* extra depth on already-decided rows is a non-blocking note; a required in-scope omission is never downgraded to optional just because it appeared in a later round.
 - **Feasibility rule:** reject a brief whose required behavior cannot be implemented within its allowed mechanisms, dependencies, compatibility constraints, or explicit non-goals — for example, demanding grammar-complete or adversarial-input recognition while forbidding every parser, new dependency, or bounded implementation strategy. Surface the smallest explicit dependency, scope, or design decision needed before builders start; do not approve an impossible implementation envelope as "decision-complete."
 
+## Specification subjects (documents, contracts, data artifacts)
+
+When the deliverable is a document or a data artifact — a specification, a contract, a protocol or
+topology description, a fixture corpus — rather than executable behavior, the class-wide rules above do
+not apply beyond what the acceptance criteria require. For code the in-scope members already exist in the
+repository, so enumerating them ends. For a document the members are whatever it chooses to specify, and
+each answer creates new surface to review; exhaustive enumeration and the late-discovery precedence rule
+then turn every fix into the next round's findings. Three contract runs in a row inflated this way (130k
+lines of corpus JSON, 25k lines of test vectors with a validator inside a Markdown file, a 72 KB
+topology document with its own SQL schemas and a quarantine system).
+One boundary decides everything beyond the criteria, in both directions: **does the content commit an
+implementer to build, store, or conform to something?** Call that an obligation.
+- **The bar is the acceptance criteria, not completeness.** A behavior an AC requires that the document
+  omits or gets wrong is a BLOCKER, in any round.
+- **Missing depth is not a finding.** Do not ask for an obligation no AC requires — deeper design,
+  internal schemas, tuning values, or handling for rare edge cases. Note it at most; never block on it.
+- **Added obligation beyond the criteria is a finding.** A schema, mechanism, subsystem, executable model,
+  or corpus that no AC requires, and that an implementer would have to build, store, or conform to, is
+  unapproved scope expansion: require it removed or reduced to a documented limit, the same way unapproved
+  scope in a brief is rejected. A reviewer that stops asking for more while accepting whatever the builder
+  adds unprompted has not stopped the ratchet.
+- **Explanatory depth is neither.** Rationale, worked examples, and clarification of a required behavior
+  add no obligation; accept them without comment.
+- **A documented limit satisfies an edge case.** "X is out of scope" or "behavior is undefined for X" is
+  an acceptable answer unless an AC requires X to be handled.
+- **No executable models by default.** A validator, generator, exhaustive corpus, or test vectors is an
+  obligation like any other: required only when an AC asks for one. Judge whether what is specified is
+  correct and consistent.
+
 ## What to check, by subject
 
 - **`work-decomposer` satisfiability:** for every slice, check that its ratified `test_plan` can be made
@@ -116,6 +145,9 @@ When the subject is a **class-wide** requirement — one that **cannot be establ
   - Code comments follow the target repository's documented policy; do not invent a blanket ban.
   - **Slice discipline:** the diff stays within the slice's `paths` (out-of-lane edits are a finding).
   - The slice's `acceptance` is actually implemented. This is never waived.
+  - A present `repository_verify` that did not exit zero is a BLOCKER: the repository's own verify
+    (lint, format, full suite) fails on this commit and will fail again after merge, where it cannot be
+    repaired. Name the failing check in `required_fixes`. An empty `test_plan` does not waive it.
   - The observed tests cover that acceptance — **unless the slice's ratified `test_plan` is empty**,
     which the plan decided at Gate 2 and which the workflow and `deriveReviewReady` both honour. A
     docs-only slice reviewed against tests it was ratified not to have is rejected forever; that

package/bin/factory.js

@@ -400,10 +400,10 @@ function branchPoint(run) {
   return base;
 }
 
-async function writeObservedEvidence({ repo, runDir, runId, subject, attempt, branch, baseRef, worktree, status, blockedReason, claim, testCommand, skipReason, shellCommand, testTimeoutMs }) {
+async function writeObservedEvidence({ repo, runDir, runId, subject, attempt, branch, baseRef, worktree, status, blockedReason, claim, testCommand, skipReason, shellCommand, testTimeoutMs, repositoryVerify = null }) {
   const evidence = buildEvidence({
     subject, attempt, branch, baseRef, worktree, status, blockedReason, claim, runId,
-    testCommand, skipReason, shellCommand, testTimeoutMs,
+    testCommand, skipReason, shellCommand, testTimeoutMs, repositoryVerify,
   });
   const ancestry = observeAncestry(worktree, baseRef, "HEAD");
   if (ancestry !== "ancestor") {
@@ -420,7 +420,8 @@ async function writeObservedEvidence({ repo, runDir, runId, subject, attempt, br
 
 function canonicalRepositoryVerifyEvidence(evidence, { runId, run, integration, verifyCommand }) {
   const baseRef = branchPoint(run);
-  const keys = Object.keys(evidence).sort();
+  // `repository_verify` is slice-only: null on test-verifier evidence, absent on evidence written before #372.
+  const keys = Object.keys(evidence).filter((key) => key !== "repository_verify").sort();
   const commandNames = [
     "git rev-parse HEAD",
     `git --literal-pathspecs diff --name-only -z ${baseRef}...HEAD`,
@@ -438,7 +439,8 @@ function canonicalRepositoryVerifyEvidence(evidence, { runId, run, integration,
     && ((tests.observed === true && Number.isInteger(tests.exit))
       || (tests.observed === false && tests.exit === null));
   const reconciliation = evidence.claim_reconciliation;
-  return JSON.stringify(keys) === JSON.stringify([...EVIDENCE_KEYS].sort())
+  return JSON.stringify(keys) === JSON.stringify(EVIDENCE_KEYS.filter((key) => key !== "repository_verify").sort())
+    && (evidence.repository_verify ?? null) === null
     && evidence.subject === "test-verifier" && evidence.run_id === runId
     && Number.isSafeInteger(evidence.attempt) && evidence.attempt >= 1
     && evidence.branch === run.branch && evidence.base_ref === baseRef
@@ -1166,6 +1168,14 @@ const HANDLERS = {
         + `expected ${JSON.stringify(slice.test_plan)}; received ${JSON.stringify(flags.testCmd)}`,
       );
     }
+    // A slice also runs the configured repository `verify`, read from its own committed config (#372).
+    let sliceVerify = null;
+    if (slice) {
+      try { sliceVerify = readRepositoryConfig(worktree, { optional: true }); } catch (error) {
+        if (error instanceof RepositoryConfigError) throw new CliError(error.message);
+        throw error;
+      }
+    }
     const skipReason = slice && slice.test_plan.length === 0
       ? `test_plan for '${subject}' was approved empty at slices-seed`
       : null;
@@ -1179,12 +1189,14 @@ const HANDLERS = {
       testCommand: flags.repositoryVerify ? repositoryVerify.command : flags.testCmd ? flags.testCmd.split(" ").filter(Boolean) : null,
       skipReason, shellCommand: flags.repositoryVerify === true,
       testTimeoutMs: flags.repositoryVerify ? repositoryVerify.timeoutMs : undefined,
+      repositoryVerify: sliceVerify && { command: sliceVerify.command, timeoutMs: sliceVerify.timeoutMs },
     });
     return emit(flags, {
       run_id: runId, subject, evidence_ref: evidenceRef(subject),
       review_ready: evidence.review_ready, files_changed: evidence.files_changed.length,
       tests: evidence.tests.observed ? `exit ${evidence.tests.exit}` : `skipped: ${evidence.tests.skipped_reason}`,
       ancestry, mismatches: evidence.claim_reconciliation.mismatches.map((entry) => entry.field),
+      repository_verify: evidence.repository_verify && (evidence.repository_verify.observed ? `exit ${evidence.repository_verify.exit}` : "not run"),
     });
   },
   async init(positional, flags) {

package/observe/index.js

@@ -14,7 +14,7 @@ export const EVIDENCE_KEYS = Object.freeze([
   "subject", "run_id", "attempt", "branch", "base_ref", "worktree", "status", "blocked_reason",
   "worktree_clean",
   "files_changed", "diff_stat", "diff_observed", "commands", "tests", "commit",
-  "observed_by", "review_ready", "claim_reconciliation",
+  "observed_by", "review_ready", "claim_reconciliation", "repository_verify",
 ]);
 
 export function git(cwd, args, { runner = spawnSync } = {}) {
@@ -109,7 +109,7 @@ export function observeAncestry(worktree, ancestor, descendant, options = {}) {
 // Attack 1: the test command is run here, by us, and its exit code is recorded
 // from the process rather than from anybody's report. `observed: false` means we
 // could not run it, which is not the same as a pass.
-export function runTests(worktree, command, { runner = spawnSync, skipReason = null, shellCommand = false, timeoutMs = DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS } = {}) {
+export function runTests(worktree, command, { runner = spawnSync, skipReason = null, shellCommand = false, timeoutMs = DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS, stdio = "inherit", env = process.env } = {}) {
   if (!command) {
     // Finding 1: defaulting a skip reason let omission manufacture review readiness.
     // Tests must be observed green or explicitly skipped with a caller-declared reason;
@@ -117,7 +117,7 @@ export function runTests(worktree, command, { runner = spawnSync, skipReason = n
     return { cmd: null, exit: null, observed: false, skipped_reason: skipReason };
   }
   const result = shellCommand
-    ? runner(command, [], { cwd: worktree, shell: true, stdio: "inherit", env: process.env, timeout: timeoutMs })
+    ? runner(command, [], { cwd: worktree, shell: true, stdio, env, timeout: timeoutMs })
     : runner(command[0], command.slice(1), { cwd: worktree, encoding: "utf8", shell: false });
   const exit = Number.isInteger(result?.status) ? result.status : null;
   return { cmd: shellCommand ? command : command.join(" "), exit, observed: exit !== null, skipped_reason: null };
@@ -133,6 +133,9 @@ export function deriveReviewReady(evidence) {
   // function alone; with the term only at write time, every mismatched record read back as
   // tampered and wedged its slice where `slice blocked` could never record it.
   if (evidence.claim_reconciliation?.mismatches?.length > 0) return false;
+  // Absent on evidence written before #372, and null when no `verify` is configured.
+  const verify = evidence.repository_verify;
+  if (verify && !(verify.observed === true && verify.exit === 0)) return false;
   // A tree with uncommitted changes cannot produce evidence about the commit it
   // claims, whatever the tests said.
   if (evidence.worktree_clean !== true) return false;
@@ -201,7 +204,7 @@ export function privilegedPaths(filesChanged) {
     || PRIVILEGED_EXACT.includes(file));
 }
 
-export function buildEvidence({ subject, runId, attempt, branch, baseRef, worktree, status, blockedReason = null, claim = null, testCommand = null, skipReason = null, shellCommand = false, testTimeoutMs = DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS, options = {} }) {
+export function buildEvidence({ subject, runId, attempt, branch, baseRef, worktree, status, blockedReason = null, claim = null, testCommand = null, skipReason = null, shellCommand = false, testTimeoutMs = DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS, repositoryVerify = null, options = {} }) {
   // Cleanliness is established before anything else is observed, because every later
   // fact - the diff, the commit, and above all the test result - is only about the
   // recorded commit if the tree has nothing uncommitted in it.
@@ -210,8 +213,20 @@ export function buildEvidence({ subject, runId, attempt, branch, baseRef, worktr
   // Tests are not run at all against a dirty tree: running them would produce a
   // result about bytes that are not going to merge.
   const tests = cleanliness.clean
-    ? runTests(worktree, testCommand, { ...options, skipReason, shellCommand, timeoutMs: testTimeoutMs })
+    ? runTests(worktree, testCommand, { ...options, skipReason, shellCommand, timeoutMs: testTimeoutMs,
+      ...(shellCommand ? { env: { ...process.env, FACTORY_VERIFY_SCOPE: "integration" } } : {}) })
     : { cmd: testCommand ? (shellCommand ? testCommand : testCommand.join(" ")) : null, exit: null, observed: false, skipped_reason: null };
+  // Enforcement (false green, #372): a slice ran only its ratified test command, so the repository's
+  // configured `verify` (lint, format, full suite) first ran after merge, where production repair is
+  // forbidden and one Clippy warning parked a 13-slice run. The same suite now runs on the slice's commit.
+  // Skipped after a failing test run, which is already not review-ready; its output goes to stderr so
+  // `observe --json` stays one JSON object. `FACTORY_VERIFY_SCOPE` tells the command which run this is.
+  const verifyRuns = repositoryVerify && cleanliness.clean && !(tests.observed && tests.exit !== 0);
+  const verified = !repositoryVerify ? null : verifyRuns
+    ? (({ cmd, exit, observed }) => ({ cmd, exit, observed }))(runTests(worktree, repositoryVerify.command,
+      { ...options, shellCommand: true, timeoutMs: repositoryVerify.timeoutMs, stdio: ["ignore", 2, 2],
+        env: { ...process.env, FACTORY_VERIFY_SCOPE: "slice" } }))
+    : { cmd: repositoryVerify.command, exit: null, observed: false };
 
   // Third round, finding 1: cleanliness was a pre-test snapshot, so a test that wrote
   // tracked files left the tree dirty while the evidence still claimed a clean HEAD -
@@ -255,6 +270,7 @@ export function buildEvidence({ subject, runId, attempt, branch, baseRef, worktr
     observed_by: "orchestrator",
     review_ready: false,
     claim_reconciliation: { claimed: false, mismatches: [] },
+    repository_verify: verified,
   };
   evidence.claim_reconciliation = reconcileClaim(claim, evidence);
   evidence.review_ready = deriveReviewReady(evidence);

package/package.json

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