@patronage/software-factory 0.20.0

package/CONTEXT.md

@@ -0,0 +1,39 @@
+# Software Factory
+
+The shared Patronage software factory: typed lifecycle state, proof gates, and orchestration conventions for agent-driven implementation work across Patronage repos.
+
+**The public glossary lives on the documentation site**: the [Patronage Software Factory glossary](https://factory.patronage.com/glossary) covers the whole factory context — coordination roles (Orchestrator / Coder / Reviewer / Oracle), proof & review, admission, lanes, and cost. This published copy keeps only the sections package consumers and ADRs cite directly; for everything else, the documentation site is the source of truth.
+
+## Language
+
+### Proof reuse
+
+**Proof gate**: A command that emits typed proof of readiness (`pr:verify`, `pr:review`, `pr:ready`). 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).
+
+### 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.
+
+**To-tickets child-issue shape**: The expected shape of a factory child issue emitted by `to-tickets` from a spec — a **tracer-bullet vertical slice**: the thinnest end-to-end change that proves one path, carrying explicit **blocking edges** and **verbatim acceptance criteria**. A well-shaped child is directly dispatchable as one lane. _Avoid_: task breakdown (understates the vertical-slice + edge contract).
+
+**Blocking edge**: A declared dependency link from one child issue to another it must wait on. On the tracker these become native blocking links; the set of edges defines the **frontier** — a ticket is on the frontier once all its blockers are closed, which is how multiple lanes run in parallel; frontier membership is necessary but not sufficient for dispatch (further readiness gating is an orchestrator-skill concern; the in-CLI `plan-child-readiness` planner was removed in the T3 orchestration cut). _Avoid_: dependency (ambiguous), sub-task.
+
+**Verbatim acceptance**: A child issue's acceptance criteria carried word-for-word so a lane's success is checkable without reinterpretation — the overseer copies AC straight from a to-tickets-shaped issue into the worker brief instead of re-authoring the success condition. _Avoid_: paraphrased acceptance, summarized criteria. (Note: the in-CLI dispatch-brief spine that enforced this was removed in the T3 orchestration cut; the convention now lives in orchestrator skill prose.)
+
+### Epic structure
+
+**Epic**: A coherent body of factory work delivered through child lanes, whose structure is a typed dependency **DAG** rather than hand-authored wave tables that drift. Defined by ADR 0018. _Avoid_: milestone, project.
+
+**Epic DAG**: The typed dependency graph that _is_ an epic's structure: **DAG nodes** joined by `depends-on` (hard ordering), `serialize-with` (same-file / migration lock), and `file-territory` (declared write fences) edges. Waves and collision fences are _derived_ from it, never hand-maintained. It is planning-time IR: an ephemeral `dag.yml` generated during planning, validated, published, then deleted — never committed. Its durable rendering is HQ's `epic-structure` ingest event, not a per-epic committed sidecar. Defined by ADR 0018. _Avoid_: wave table (that is a rendered view, not the source), roadmap.
+
+**DAG node**: A unit of plannable work in the epic DAG, identified by a stable **slug** independent of any issue number — so it can be depended-on during planning, before issues exist. A node carries a `status` (open / closed / satisfied-on-main / parked) and, from ratification, its issue number: every node's child issue is minted up front, so the number is known before any lane dispatches. _Avoid_: ticket (a node is the plan abstraction; its minted child issue is the ticket), task.
+
+**Wave**: The _derived_ dependency-layer projection of the epic DAG — the topological rank of a node (wave N holds every node whose dependencies sit in waves `< N`). A rendered view, never hand-maintained. For the current cut a wave is a **dependency layer only**; whether it is also a thermo-gating or human-checkpoint boundary is a per-epic planning-time policy call — the deep Oracle thermo defaults to epic closeout rather than per wave. _Avoid_: phase, sprint. (Note: "deep thermo per wave" means thermo _runs at_ wave boundaries — it does not _define_ the wave.)
+
+**Park**: To hold a DAG node whose scope is still moving _out_ of the dispatch frontier — relabel its issue off `ready-for-agent` (never close it — history and linkage are preserved), so a moving plan costs zero issue churn. The issue already exists (minted at ratification); parking and un-parking are label changes, and the node returns to `ready-for-agent` when its lane finally dispatches. _Avoid_: close, defer (ambiguous).
+
+**Satisfied-on-main**: A node status meaning its work is already true on `main` without a dedicated PR — recorded in the DAG rather than re-derived by a reconciliation scout each wave. _Avoid_: done (reserve for closed-via-PR).
+
+**Lane**: The unit of factory work HQ tracks: begins when an issue is labeled `ready-for-agent` in a profiled repo, or when a PR first bears factory evidence — whichever comes first. Producer-neutral: a human-authored PR seeking admission is a lane. A DAG node whose issue is not yet `ready-for-agent` is plan, not a lane. _Avoid_: run (a lane may span several sessions), task.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patronage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# Patronage Software Factory
+
+`@patronage/software-factory` is the CLI and schema package behind the [Patronage Software Factory documentation](https://factory.patronage.com). The site is the canonical user contract: use its [proof chain](https://factory.patronage.com/admission-chain) for admission, [command reference](https://factory.patronage.com/command-reference) for current syntax, and [operator guides](https://factory.patronage.com/how-to) for recovery and setup.
+
+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; a post-merge canary covers integration risk. 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
+
+This section and the two below describe the source repository; the paths they mention are not part of the installed npm package. The package lives in the repository pnpm workspace and requires Node 24. From the repository root:
+
+```bash
+bash scripts/bootstrap-worktree.sh .
+pnpm --filter @patronage/software-factory build
+pnpm --filter @patronage/software-factory typecheck
+pnpm --filter @patronage/software-factory test
+pnpm --filter @patronage/software-factory check
+```
+
+The package publishes to public npm as `@patronage/software-factory` under MIT. Releases are attended and hand-cut by a maintainer; the repository operations runbook (`docs/repository-operations.md` in the source repository) records the publish procedure.
+
+## Architecture boundaries
+
+Internal architectural packages live under `src/packages/`. Read the package root's `README.md` before editing one. Import only entry points explicitly declared by `dependency-cruiser.config.mjs`; package implementation and fixtures are private. See ADR 0007 (`docs/adr/0007-factory-internal-deep-packages-enforce-module-seams.md` in the source repository).
+
+## Releases
+
+Every epic or close-out sweep ends in an attended release; do not let merged work accumulate untagged.
+
+1. Bump `package.json` and keep its version, the `software-factory-vX.Y.Z` tag, the GitHub release, and the npm publish in agreement.
+2. Cut the tag and GitHub release with notes covering features, deletions, breaking changes, and closed issues. When the release changes the profile `schemaVersion`, state it in the notes — the profile schema version is a separate axis from the package version.
+3. Publish to npm per the repository operations runbook (attended, hand-cut).
+4. Update affected `software-factory-docs/` pages in the same change and confirm the docs version matches the release.
+
+A release whose docs still describe the previous doctrine is not complete.
+
+## Use it in a project
+
+Start with [Installing the factory to a project](https://factory.patronage.com/operators/installing-the-factory). Beginning with the first attended registry release (see Releases above), install from public npm and pin the version:
+
+```bash
+pnpm add -D @patronage/software-factory
+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.
+
+For factory workflow, install the four canonical skills from the repository:
+
+```bash
+npx skills add https://github.com/patronage/software-factory -g --all
+```
+
+They provide procedure and link back to the documentation site; they are not a second command reference.

package/dist/chunk-DrSxFLj_.js

@@ -0,0 +1,14 @@
+import "node:module";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };