@patronage/software-factory 1.0.0-alpha.0 → 1.0.0-alpha.10

package/CONTEXT.md

@@ -6,12 +6,22 @@ The shared Patronage software factory: typed lifecycle state, proof gates, and o
 
 ## Language
 
+### Admission
+
+**Candidate**: The exact patch under admission — the `headSha` / `patchId` / `mergeBaseSha` identity every piece of evidence binds to. A GitHub draft pull request is not a Candidate; GitHub's draft boolean is the machine lifecycle authority, and ready-for-review is the Candidate state. Experiment and interactive describe human intent only and create no machine states.
+
+**Promotion**: The one transition from a draft pull request into a Candidate. `pr:publish` is the promotion verb. Its composed handoff finishes proof while draft, promotes, then evaluates Candidate demands at the unchanged head. Draft open and synchronize events run no substantive hosted Verify battery; `ready_for_review` starts the complete applicable Candidate pass.
+
 ### Proof reuse
 
 **Proof gate**: A command that emits a typed proof — the self-timed set is `pr:verify`, `pr:review`, `pr:ready`, `boundary:check`, and `factory:closeout`; one execution is a **gate run**. Typed proof files are the source of readiness truth; prose never substitutes.
 
 **Proof-reuse gate**: The decision that consumes trusted verification proof and determines whether hosted CI may skip work already performed. Refusing reuse runs the hosted suite; it does not fail the candidate. Defined by ADR 0022. _Avoid_: proof gate (that produces readiness proof rather than reusing it).
 
+### Impact
+
+**Impact**: The candidate-bound classification of which declared product targets a changed path or lockfile graph can reach. Path impact is opt-in: a target is affected if and only if a valid changed path matches one of its declared globs. A valid path matched by no target is **unsubscribed** and demands no target-scoped work, while remaining explicit in the stamp basis and human summary. Shared paths affect every target that subscribes to them. Invalid paths and unreadable or malformed required inputs still fail closed. Impact may withdraw target-scoped work; it never certifies a merge target, whose push-triggered verification stays full. Defined by ADR 0027. _Avoid_: affectedness; ownership (the declaration is a subscription, not an implicit filesystem owner).
+
 ### Planning intake
 
 **Spec**: The single through-line planning artifact — a technical, non-technical, or blended description of the work to be built, produced by `to-spec`. The term supersedes "PRD"; older artifacts titled "PRD:" (e.g. #232) are specs by another name. _Avoid_: PRD (retired), requirements doc.

package/README.md

@@ -4,7 +4,7 @@
 
 The factory admits a pull request from evidence bound to its candidate. It validates policy and proof; it does not schedule workers, choose models, or run reviews. Those are jobs for the harness or operator.
 
-Admission is fail closed. A clean-session review and required verification produce typed proof, then readiness decides whether the candidate may proceed. Evidence stays current when the candidate patch is unchanged; the push-triggered Verify workflow covers integration risk on every factory merge target and freezes further merges into a target when that target goes red. Epic policy, including review minimums and auto-merge authority, lives in the boundary manifest. HQ observes this work; it never blocks a gate.
+Admission is fail closed. A clean-session review and required verification produce typed proof, then readiness decides whether the candidate may proceed. Evidence stays current when the candidate patch is unchanged; the push-triggered Verify workflow covers integration risk on every factory merge target — `main` and the `epic/**` integration branches. When a target goes red, the factory refuses new readiness decisions and authorized arming against that target; candidates armed before the target went red can still land. Epic policy, including review minimums and auto-merge authority, lives in the boundary manifest. HQ observes this work; it never blocks a gate.
 
 ## Develop the package
 
@@ -30,18 +30,24 @@ This is the release checklist. It lives here and nowhere else; the repository ru
 
 Releases are attended and hand-cut. Nothing in the factory publishes, tags, or releases on its own, and no step below may be automated as a drive-by.
 
-1. Bump `package.json` to valid SemVer. The assertion derives its expected stable or prerelease channel from the version; it accepts no channel flag.
-2. Publish to npm per the [repository operations runbook](../docs/repository-operations.md#publishing) (attended, hand-cut, `pnpm publish` only). A stable version uses `pnpm --filter @patronage/software-factory publish`, which assigns npm `latest`. A prerelease must use `pnpm --filter @patronage/software-factory publish --tag next`; bare `pnpm publish` defaults to `latest` and would move it before the post-hoc assertion can reject the release.
+The factory family has one version posture (ADR 0026, `docs/adr/0026-factory-family-version-lines-move-in-lockstep.md` in the source repository): `@patronage/factory-ci` moves in lockstep majors with this CLI. From factory-ci's first release in the CLI's current series onward, majors and prerelease series move together while patch and prerelease increments stay independent per package. A consumer pins a factory-ci from the same major/prerelease series as its CLI; there is no compatibility matrix. Until that first lockstep release, factory-ci's published 0.x line is the named pre-adoption state and pairs with any CLI version. `@patronage/alchemy-d1-state` keeps independent SemVer. Lockstep is a rule the maintainer follows when cutting releases, never automation.
+
+A stacked release train has one terminal release-owning slice. Interior slices do not bump `package.json` or cut a checkpoint unless the boundary explicitly intends a separately published release at that slice: a lower-slice bump consumes the release window before the terminal slice lands, and the train must then advance the version and re-earn its terminal evidence.
+
+A stable cut has two phases. Phase 1 is the verified package candidate: steps 1 through 4 below, ending in the attended npm publish, tag, and GitHub release. Phase 2 is post-publication stable-doc convergence: steps 5 and 6, a normal admitted docs PR followed by the read-only convergence assertion from a clean `main`. Stable docs must never claim an unpublished version, so they cannot land in the phase-1 change. Prerelease behavior is unchanged: prerelease notes may land before publish while stable docs keep naming the prior stable version.
+
+1. Bump `package.json` to valid SemVer. The assertion derives its expected stable or prerelease channel from the version; it accepts no channel flag. Before publishing, prove production HQ accepts this candidate's proof schema. The manifest bump triggers the CI-only `HQ Deploy` workflow because HQ bundles this package's public schemas. From a clean `main`, record `RELEASE_SHA="$(git rev-parse HEAD)"`, find the `HQ Deploy` run with `gh run list --workflow "HQ Deploy" --commit "$RELEASE_SHA"`, and use `gh run watch <run-id> --exit-status`; an older green deployment does not count. Then, outside a sandbox, run `psf hq:flush --cwd <candidate-worktree>` against the candidate's retained `pr-verify-proof`. The release may proceed only when the current proof exists, the exact-SHA deployment passed, and the drain reports that proof `delivered` or `duplicate` (or no pending spool because its original delivery already succeeded), with `rejected 0` and no event remaining. This is an attended release-compatibility gate; it does not make HQ authoritative for ordinary admission.
+2. Build and review one pnpm tarball, then publish that exact tarball per the [repository operations runbook](../docs/repository-operations.md#publishing) (attended and hand-cut). Publishing the workspace directory is not allowed because it rebuilds during `prepack` after the artifact review. **Always pass `--tag` explicitly, on every publish, prerelease or stable**: `pnpm publish "$SOFTWARE_FACTORY_TARBALL" --tag next --access public` for a prerelease, `--tag latest` for a stable cut. A filtered directory publish takes pnpm's recursive path, which passes its own `--tag` (defaulting to `latest`) to npm and therefore ignores the `publishConfig.tag: next` pin both factory packages carry; that is how 1.0.0-alpha.6 briefly took `latest` (#658). The pins stay as belt and braces, but they are not the control. Omitting the flag is not a safe failure: it moves `latest`, which the convergence assertion can only report after the fact. The attended token path does not promise an npm provenance attestation; the source SHA and reviewed tarball SRI are its operational provenance.
 3. Cut the `software-factory-vX.Y.Z` tag and push it.
 4. Cut the GitHub release for that tag, with notes covering features, deletions, breaking changes, and closed issues. Mark it as a prerelease exactly when its SemVer version has a prerelease component. When the release changes the profile `schemaVersion`, state it in the notes — the profile schema version is a separate axis from the package version.
-5. Update affected `software-factory-docs/` pages. Stable docs must state the current stable version. Prerelease docs may record the candidate and its migration notes, but must not represent it as the current stable release.
-6. Confirm the five facts converge:
+5. Converge the stable docs after publication. Update affected `software-factory-docs/` pages through a normal admitted docs PR. Stable docs must state the current stable version. Prerelease docs may record the candidate and its migration notes, but must not represent it as the current stable release.
+6. After the docs PR merges, confirm the six facts converge from a clean checkout of `main`:
 
    ```bash
    pnpm --filter @patronage/software-factory exec tsx scripts/assert-publish-manifest.ts --release .
    ```
 
-   It reads what you just did and derives the channel from the manifest version. A stable release must converge exactly among manifest, npm `latest`, non-prerelease GitHub release, tag, and stable docs. A prerelease must exist on npm, own npm `next`, leave npm `latest` at the stable docs version, and have its prerelease GitHub release and tag. It publishes nothing. Step 6 is the only step a machine performs, and it performs it after you.
+   It reads what you just did and derives the channel from the manifest version. A stable release must converge exactly among manifest, npm `latest`, non-prerelease GitHub release, tag, and stable docs. A prerelease must exist on npm, own npm `next`, leave npm `latest` at the stable docs version, and have its prerelease GitHub release and tag. The sixth fact is the factory-ci pairing above: the assertion passes while every observed published `@patronage/factory-ci` version is pre-adoption 0.x and names that state, fails once a lockstep factory-ci release exists whose newest published version is outside the CLI's major/prerelease series, and fails when the registry read yields no readable factory-ci versions or contains an entry that does not parse — missing or unreadable data is an unsatisfied fact, not pre-adoption. It publishes nothing. Step 6 is the only step a machine performs, and it performs it after you.
 
 ## Use it in a project
 
@@ -54,6 +60,8 @@ pnpm exec patronage-factory --help   # or: psf --help
 
 The repository profile declares its admission policy. Operator-local settings and HQ credentials are documented separately, so they do not become committed project configuration.
 
+Generated production workflows may call `psf production:impact --before <sha> --after <sha> --github-output <path>`. The command recomputes the profile's opt-in impact subscriptions from those exact real commits and emits stable demanded/withdrawn target outputs, the changed-file decision basis, and unsubscribed paths. It only withdraws work: missing, zero, malformed, unreachable, non-ancestral, or otherwise unclassifiable identities leave every known target demanded. The factory owns this decision seam; each consumer owns its deploy jobs, commands, credentials, topology, and post-deploy convergence/no-op proof. Merge-target Verify remains full and does not consult this command.
+
 For factory workflow, install the four canonical skills from the repository:
 
 ```bash

package/dist/index.d.ts

@@ -145,8 +145,6 @@ interface HqIngestDependencies {
    * `timeoutMs`: see the note there.
    */
   journalFlushBudgetMs?: number;
-  /** @deprecated Legacy sidecars are now streamed directly; retained for API compatibility. */
-  sidecarReclaimMs?: number;
   /**
    * Setup budget for callers that own the process lifetime — honored AS GIVEN,
    * above the `DEFAULT_HQ_INGEST_TIMEOUT_MS` ceiling that clamps `timeoutMs`.
@@ -184,12 +182,6 @@ interface HqSpoolEntryOutcome {
   kind: string;
   spool: string;
   /**
-   * `migrated` belongs to the legacy JSONL journal only: the row was moved
-   * into the current spool without being delivered. The spool pass that runs
-   * after it in the same drain supersedes that line with a real outcome when
-   * it gets to the row; a `migrated` line that survives the run means the row
-   * is still waiting.
-   *
    * `undeliverable` is the one terminal verdict (#445). Every other status
    * describes a moment: HQ was unreachable, HQ refused this content today, the
    * row moved. Retrying is meaningful for all of them. A wrong-origin entry is
@@ -198,13 +190,11 @@ interface HqSpoolEntryOutcome {
    * run. Leaving it spooled asks the operator to retry something that provably
    * cannot succeed, and the count it inflates is the one doctor goes red on.
    */
-  status: "delivered" | "duplicate" | "migrated" | "rejected" | "undeliverable" | "unreachable";
+  status: "delivered" | "duplicate" | "rejected" | "undeliverable" | "unreachable";
 }
 interface HqSpoolFlushInput {
   clientId: string;
   clientSecret: string;
-  /** Repository root whose legacy `.factory-memory` spool is also drained. */
-  cwd: string;
   /** The profile's HQ origin; entries recorded against another are refused. */
   endpoint: string;
   /** Operator-named spool directories; replaces the default two locations. */
@@ -239,13 +229,13 @@ interface HqSpoolFlushSummary {
 interface HqSpoolWorkCount {
   /**
    * The earliest moment learned across pending spool files (their own write
-   * time) and legacy journal rows (their own `failedAt`). Absent only when
+   * time). Absent only when
    * `pending` is `0`, or when every timestamp source was unreadable within
    * budget — an estimate for doctor's remediation message (#394), never a
    * precise audit trail.
    */
   oldestQueuedAt?: string;
-  /** Spooled events and replayable journals waiting in the locations below. */
+  /** Spooled events waiting in the locations below. */
   pending: number;
   /** Locations that exist and hold spooled work. */
   spools: string[];
@@ -266,7 +256,7 @@ interface HqSpoolWorkCount {
  * same locations `flushHqSpool` drains are inspected here, read-only: no
  * directory is created, nothing is secured, and nothing is delivered.
  */
-declare function countHqSpoolWork(input: Pick<HqSpoolFlushInput, "cwd" | "explicitDirectories" | "repository">, dependencies?: {
+declare function countHqSpoolWork(input: Pick<HqSpoolFlushInput, "explicitDirectories" | "repository">, dependencies?: {
   budgetMs?: number;
   env?: NodeJS.ProcessEnv;
 }): Promise<HqSpoolWorkCount>;
@@ -275,7 +265,7 @@ interface HqSpoolOrphan {
   /** The `hq-retry-spool` directory itself, ready to pass to `--dir`. */
   directory: string;
   oldestQueuedAt?: string;
-  /** Spooled events and journal rows waiting there. */
+  /** Spooled events waiting there. */
   pending: number;
   /**
    * The location exists but could not be listed. As everywhere else in this
@@ -537,6 +527,7 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
     targets: z.ZodArray<z.ZodObject<{
       importers: z.ZodArray<z.ZodString>;
       name: z.ZodString;
+      paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
   }, z.core.$strict>>;
   proof: z.ZodObject<{
@@ -752,8 +743,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    active: "active";
     stale: "stale";
+    active: "active";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -1252,8 +1243,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        stale: "stale";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1264,8 +1255,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        stale: "stale";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -1276,8 +1267,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
     docsOnlyVerifiedHeadSha: z.ZodOptional<z.ZodString>;
     prVerify: z.ZodEnum<{
-      stale: "stale";
       passed: "passed";
+      stale: "stale";
       missing: "missing";
     }>;
     trivialDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
@@ -1371,6 +1362,7 @@ interface GitHubPullRequest {
   baseRefName: string;
   baseRefOid: string;
   body: string;
+  headRefName?: string;
   headRefOid: string;
   isDraft: boolean;
   mergeStateStatus: string;
@@ -1522,11 +1514,11 @@ declare function runPrReady(args: PrReadyArgs, dependencies?: PrReadyDependencie
  */
 declare const impactStampSchema: z.ZodObject<{
   basis: z.ZodEnum<{
-    "lockfile-scoped": "lockfile-scoped";
+    "target-scoped": "target-scoped";
     conservative: "conservative";
   }>;
   reasons: z.ZodArray<z.ZodString>;
-  stampVersion: z.ZodLiteral<1>;
+  stampVersion: z.ZodLiteral<3>;
   targets: z.ZodArray<z.ZodObject<{
     basis: z.ZodString;
     impact: z.ZodEnum<{
@@ -1535,6 +1527,7 @@ declare const impactStampSchema: z.ZodObject<{
     }>;
     name: z.ZodString;
   }, z.core.$strip>>;
+  unsubscribedPaths: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 type ImpactStamp = z.infer<typeof impactStampSchema>;
 /**
@@ -1560,7 +1553,7 @@ interface ImpactScopeDecision {
  * external proof demand (#542 wave 2), a verification-battery command, or a
  * preview (Alchemy) lifecycle stack (#430 wave 3).
  *
- * The only release path is a `lockfile-scoped` stamp of exactly this build's
+ * The only release path is a `target-scoped` stamp of exactly this build's
  * stamp version whose target entry for exactly this name is provably
  * `not-affected`. Every other input — no trusted stamp, an unknown stamp
  * version, a conservative stamp, a name the stamp does not classify, or an
@@ -1779,8 +1772,8 @@ declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale"
 declare const reviewStatusSchema: z.ZodEnum<{
   blocked: "blocked";
   "not-required": "not-required";
-  stale: "stale";
   current: "current";
+  stale: "stale";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -2186,9 +2179,9 @@ declare const retroEnvelopeV1Schema: z.ZodObject<{
   kind: z.ZodLiteral<"retro-envelope">;
   outcome: z.ZodOptional<z.ZodObject<{
     status: z.ZodEnum<{
-      blocked: "blocked";
       success: "success";
       fail: "fail";
+      blocked: "blocked";
       "ship-with-followups": "ship-with-followups";
     }>;
     verdict: z.ZodOptional<z.ZodString>;
@@ -2335,7 +2328,9 @@ type BoundaryCheckProofRecord = z.infer<typeof boundaryCheckProofSchema>;
 //#endregion
 //#region src/boundary-check.d.ts
 interface BoundaryPullRequestRef {
+  baseRefName?: string;
   headRefOid?: string;
+  headRefName?: string;
   mergeCommitOid?: string;
   number: number;
   state: "OPEN" | "CLOSED" | "MERGED";
@@ -3929,12 +3924,14 @@ declare const boundaryManifestBaseSchema: z.ZodObject<{
     }>;
   }, z.core.$loose>>;
   declaredBy: z.ZodString;
+  integrationBranch: z.ZodOptional<z.ZodString>;
   prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   schemaVersion: z.ZodLiteral<1>;
   topology: z.ZodEnum<{
     flagged: "flagged";
     "each-to-main": "each-to-main";
     stacked: "stacked";
+    "each-to-epic": "each-to-epic";
   }>;
   waves: z.ZodArray<z.ZodObject<{
     autoMerge: z.ZodOptional<z.ZodBoolean>;
@@ -3957,12 +3954,14 @@ declare const boundaryManifestSchema: z.ZodObject<{
     }>;
   }, z.core.$loose>>;
   declaredBy: z.ZodString;
+  integrationBranch: z.ZodOptional<z.ZodString>;
   prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   schemaVersion: z.ZodLiteral<1>;
   topology: z.ZodEnum<{
     flagged: "flagged";
     "each-to-main": "each-to-main";
     stacked: "stacked";
+    "each-to-epic": "each-to-epic";
   }>;
   waves: z.ZodArray<z.ZodObject<{
     autoMerge: z.ZodOptional<z.ZodBoolean>;
@@ -4075,13 +4074,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "blocked" | "not-required" | "stale" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "blocked" | "not-required" | "stale" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4089,7 +4088,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     schemaVersion: 1;
     verification: {
       command: "patronage-factory pr:verify";
-      prVerify: "stale" | "passed" | "missing";
+      prVerify: "passed" | "stale" | "missing";
       docsOnlyDeltaAccepted?: boolean | undefined;
       docsOnlyVerifiedHeadSha?: string | undefined;
       trivialDeltaAccepted?: boolean | undefined;