@patronage/software-factory 1.0.0-alpha.7 → 1.0.0-alpha.9

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

@@ -37,7 +37,7 @@ A stacked release train has one terminal release-owning slice. Interior slices d
 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.
-2. Publish to npm per the [repository operations runbook](../docs/repository-operations.md#publishing) (attended, hand-cut, `pnpm publish` only). **Always pass `--tag` explicitly, on every publish, prerelease or stable** — `pnpm --filter @patronage/software-factory publish --tag next` for a prerelease, `--tag latest` for a stable cut. A filtered 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: on the filtered command it moves `latest`, which the convergence assertion can only report after the fact.
+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. 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.
@@ -60,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

@@ -1224,8 +1224,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       "run-interior-cycle": "run-interior-cycle";
     }>;
     stage: z.ZodEnum<{
-      interior: "interior";
       gate: "gate";
+      interior: "interior";
       "interior-complete": "interior-complete";
     }>;
   }, z.core.$strip>>;
@@ -1241,8 +1241,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        "not-required": "not-required";
         blocked: "blocked";
+        "not-required": "not-required";
         current: "current";
         stale: "stale";
         missing: "missing";
@@ -1253,8 +1253,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        "not-required": "not-required";
         blocked: "blocked";
+        "not-required": "not-required";
         current: "current";
         stale: "stale";
         missing: "missing";
@@ -1517,7 +1517,7 @@ declare const impactStampSchema: z.ZodObject<{
     conservative: "conservative";
   }>;
   reasons: z.ZodArray<z.ZodString>;
-  stampVersion: z.ZodLiteral<2>;
+  stampVersion: z.ZodLiteral<3>;
   targets: z.ZodArray<z.ZodObject<{
     basis: z.ZodString;
     impact: z.ZodEnum<{
@@ -1526,6 +1526,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>;
 /**
@@ -1768,8 +1769,8 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
 //#region src/review-proof-applicability.d.ts
 declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
 declare const reviewStatusSchema: z.ZodEnum<{
-  "not-required": "not-required";
   blocked: "blocked";
+  "not-required": "not-required";
   current: "current";
   stale: "stale";
   missing: "missing";
@@ -2939,8 +2940,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     sessionId: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
   stage: z.ZodEnum<{
-    interior: "interior";
     gate: "gate";
+    interior: "interior";
   }>;
   usage: z.ZodOptional<z.ZodObject<{
     estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
@@ -2992,8 +2993,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     sessionId: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
   stage: z.ZodEnum<{
-    interior: "interior";
     gate: "gate";
+    interior: "interior";
   }>;
   usage: z.ZodOptional<z.ZodObject<{
     estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
@@ -3036,8 +3037,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
       sessionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     stage: z.ZodEnum<{
-      interior: "interior";
       gate: "gate";
+      interior: "interior";
     }>;
     usage: z.ZodOptional<z.ZodObject<{
       estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
@@ -3067,7 +3068,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     staleRepeats: number;
   };
   observedAt: string;
-  stage: "interior" | "gate";
+  stage: "gate" | "interior";
   issue?: number | undefined;
   pr?: number | undefined;
   threadId?: string | undefined;
@@ -3323,8 +3324,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3402,8 +3403,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3472,8 +3473,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     interiorCycle: z.ZodOptional<z.ZodNumber>;
     observedAt: z.ZodString;
     purpose: z.ZodEnum<{
-      review: "review";
       code: "code";
+      review: "review";
     }>;
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
@@ -3545,7 +3546,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   exitCode: number | null;
   harness: string;
   observedAt: string;
-  purpose: "review" | "code";
+  purpose: "code" | "review";
   slotResolution: {
     effort: "high" | "low" | "medium" | "xhigh";
     engine: string;
@@ -4066,13 +4067,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4123,7 +4124,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
         interior: number;
       };
       nextAction: "run-gate-cycle" | "accept-nonblocking-findings" | "escalate-to-triage" | "ready-for-human" | "advance-to-gate" | "run-interior-cycle";
-      stage: "interior" | "gate" | "interior-complete";
+      stage: "gate" | "interior" | "interior-complete";
       forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
     } | undefined;
     reviewRuns?: PrReviewResult[] | undefined;