Software Factory: design

1. Ends, lifecycle and domains

The factory exists to realise customer value across several Products and keep it healthy over time. Autonomy, agents and infrastructure are only means; Values state the ends. This design proposes mechanisms, which may be replaced when Evidence favours something simpler or more reliable.

The lifecycle

1. Objective and problem. Planning links an Objective to a customer problem, using Signals such as usage, support, research, sales conversations and incidents. A research report does not count as a customer interview.
2. Validation. Before building, the Slice states its Outcome, how to measure it and what would disprove it. Use the cheapest convincing Evidence: existing data, a prototype or a limited alpha.
3. Build and check. Delivery produces a Candidate; Assurance judges it independently.
4. Release. Operations exposes the change according to risk and watches customer health.
5. Measure. Planning compares observed results with the Outcome and records an Assessment concluding Supported, Rejected or Inconclusive. Never hide a Rejected conclusion.
6. Keep, renew or retire. A Capability is kept while it serves customers, renewed when Evidence shows friction, and retired deliberately when it no longer earns its cost.

Technical completion of a Run, confirmed customer availability and the Assessment are distinct. Only a Supported Assessment of independently checked realised benefit counts as a value win. A Rejected conclusion may close an experiment as learning, never as an achieved improvement; an Inconclusive Assessment records its next decision. Long observation windows do not keep delivery Runs open.

Decision domains

Three shared foundations support the domains as modules in one application, not as services:

• Execution runs isolated work.
• Evidence store keeps Evidence with its provenance.
• Action gateway checks Authority and records external effects.

Agents act on behalf of a domain; they are never the system of record. The same domains and lifecycle govern changes to the factory itself, so there is no separate improvement organisation.

Operations owns foundation health, backups, capacity, incidents, customer status and vendor access. Each Product has its own customer identities by default. Planning owns insight from support; Growth maintains customer-facing guidance. Product Packs reuse Recipes and contracts while keeping each Product's data isolated.

2. One language

Use these terms consistently in code, tickets, diagrams and reports.

Capabilities change on purpose

Track disposition (Required, Retiring or Retired) separately from health (Healthy, Degraded or Unknown). After an accidental regression, restore safe required or replacement behaviour without undoing a valid retirement. Planning decides retirement within Authority, citing Evidence; Assurance independently verifies the revised baseline. Retirement honours customer, migration, notice, data and recovery obligations; see Self-improvement.

3. Deliver with evidence

Independent assurance

Assurance controls pinned scenarios, runners, fixtures, provenance and Verdict issuance. Delivery cannot alter their authoritative versions; Planning owns scope. Changes to Assurance itself require a separately pinned evaluator or trusted bootstrap path.

A Verdict names the exact Candidate, environment and scenario revision. Any input change requires a fresh Verdict. An Inconclusive Verdict never promotes.

Exercise UI work live. Screenshots and recordings are supporting Evidence, not proof on their own. Producer-written reports are context; independent collectors reproduce decisive observations. Derived claims retain source links and uncertainty. Model reviewers supplement executable checks. Where risk is high, verify with a different provider or method to reduce correlated error.

Test coverage and passing CI show which cases ran, not that requirements are met or customers were helped. Combine a fixed regression suite with fresh scenarios so the factory cannot tune itself to known tests.

Security and privacy

• Threat-model each change in proportion to its risk.
• Scan code, dependencies and secrets, and check runtime behaviour.
• Give implementation workers isolated workspaces and no release credentials.
• Keep customer content, secrets and raw identifiers out of permanent history. Retention covers linkable references and backups. Test deletion, and use synthetic accounts in UI tests.
• Remediate security findings within severity deadlines.

Progressive release

Operations integrates only the exact prospective merge-queue Candidate covered by Assurance's current Verdict, then confirms the integrated revision and released artefact. Any change to a relevant input invalidates the applicable Verdict.

Potentially unsafe changes reach the alpha channel before stable. Declared observation windows, health and customer-flow guardrails decide promotion or recovery. Where binary rollback is insufficient, use compatible migrations, disablement or forward repair. Not every change is reversible; monitoring continues after release.

Use flags for reversible exposure and A/B tests for genuine uncertainty; neither is required ceremony. A channel Receipt plus an independent probe from the customer access path establishes availability; neither a merge nor an upload does. Growth uses that fact.

Measurement

Before exposure, Planning sets a measurement contract within its Authority: baseline, target, population, window, guardrails and decision rule. Assurance independently checks instrumentation, adverse segment effects and the decision rule's application. Causal claims need proportionate causal methods; label observational findings as such. A missing threshold blocks only execution that depends on it. Track customer task success, adoption, reliability, latency, support load and cost.

Docs and marketing

Update documentation in the same Slice as the behaviour it describes. Within Policy, Growth writes release notes, website copy, blog posts and launch material only from confirmed release facts. Advertising requires an explicit budget. Acquisition results return to Planning as Signals.

Discovery and post-development terms (proposed)

Terms of the proposed lifecycle design: designed, not implemented, and used as consistently as those in section 2.

Service access terms

Terms of the service access module, whose first increment (names only, on test fixtures) is built and provisionally accepted — Fable 5.1 (max) round 1; Astra review pending (Codex usage limit until 2026-10-03 18:00); the Product vault is designed, not implemented. They are used as consistently as those in section 2.

4. Reliability contracts

Facts and messages

A Command asks one domain to act. An Event records a fact its domain accepted; it informs but grants no permission.

Every Command carries an ID. Repeats return the recorded result; a changed payload under the same ID is rejected. Version checks reject stale concurrent decisions.

Slice and Action decisions are event-sourced because their history must be explainable. Immutable Candidates and Verdicts are stored directly. Rebuilding views never issues Commands or Actions.

Workers

Execution issues an increasing ownership version (epoch) for each owned work or resource scope. Candidates and Actions carry their scope and epoch; scope owners reject stale claims. A replacement worker atomically adopts an unfinished Action under its new epoch, preserving identity and intent. A hung worker is stopped or quarantined before its resources are reused. Workers run in bounded Attempts. Claude and OpenAI workers implement one contract and are compared on measured quality, latency and cost per role.

External effects

The Action gateway records each Action before any dispatch. A dispatch is one external call, not a new worker Attempt or logical Action. The Action key combines the Product, operation, target, intent and a logical occurrence allocated by the requesting domain. Retries and replacement Runs reuse the key; a changed payload is rejected. Each adapter proves its execute and reconcile contract against the real service; an empty listing alone never proves absence.

• A lost acknowledgement makes the result unknown; an unknown result forbids blind retry.
• Reconciliation continues independently of the Run. Only confirmation that the Action was not applied permits a guarded retry.
• Authority, Policy, epoch and Verdict are rechecked at dispatch.
• Cancellation stops new work but cannot undo a confirmed remote effect.
• A Run cannot succeed while a required Action is unresolved.

Blockers and Escalation

Classify each failure first: reconcile uncertain Actions; retry known-safe failures; change remedy or provider; then replan within Budget. Wait durably for outside dependencies while continuing other work.

Escalate only when no permitted remedy remains within current Authority and Budget. Record what was tried and ask for the one missing decision, access or resource. Never weaken tests, redefine acceptance or bypass security to avoid Escalation. Limits never increase automatically.

Demonstrated, not assumed

Inject duplicates, stale workers, revoked Authority, corrupt Evidence, provider loss and crashes around commits and acknowledgements. Prove backup restoration and zero external writes on replay. Measure recovery, stranded work, false Verdicts and duplicate effects. Claim availability only against a target and observation window.

Proposed stack: prototype with TypeScript, Temporal, PostgreSQL and an artefact store. PostgreSQL owns facts and public Run state; Temporal owns the workflow cursor. Commit facts, results and outbox entries atomically; deduplicate workflow delivery. Reconcile unfinished work; terminal Runs stay terminal. See architecture.

5. Evolve without losing trust

Every improvement, including one to the factory itself, is an ordinary slice: independently checked, released according to risk and backed by a tested recovery plan. Authors never approve their own changes.

Recovery that survives the factory

Recovery runs outside the factory or product deployment it restores, without the failed planner or provider. Operations owns bounded recovery, drills, flap protection and artefacts independently verified as healthy. Before restored state dispatches work, reconcile it with current authority and action records, and quarantine unresolved effects. Apply deletion obligations before customer exposure. A failed recovery waits safely and escalates to its commissioned destination. Never update recovery and its target together. Restore service before diagnosis.

Rhythms

• Continuous healing. Detect failing checks, stalled runs and degraded capabilities. Contain, restore and verify, then fix the cause in a slice.
• Nightly research. Test new tools, models and methods against observed weaknesses using disprovable claims and baselines. Adopt only measured gains and record rejections to prevent churn. No-change nights are valid, and missed windows coalesce into one pass.
• Weekly defrag. Inventory consumers first, then remove duplication, dead code, stale flags, obsolete prompts and abandoned work. Preserve required capabilities, safely restoring any accidental loss. Correct wrong checks in separate, independently judged changes that preserve intended behaviour.
• Interface renewal. Redesign when evidence shows friction, outdated patterns or accessibility gaps, never for novelty alone. Release progressively and measure task success.

Incidents come first, and improvement capacity is bounded to protect product delivery. Prove backup restoration, deletion and factory-down recovery before unattended self-update. Details: self-improvement.

Policy evolves within authority

Each domain may revise its policy and targets within its authority; Planning owns retirement. Changes are recorded and independently assessed. Only expanding authority needs an explicit owner decision. Neither success nor majority model agreement grants authority. Active work keeps its pinned policy, and its pinned acceptance cannot be weakened. Current revocations still apply at dispatch.

Build order

E01-E05 complete a real pilot value loop. Next, strengthen coordination, assurance, restoration and privacy; E10 must precede E09 self-update. Then prove provider, product and account reuse, and sustained operation. Dependencies, not numbers, set the exact order, and safety proof always precedes the exposure that needs it. Commission the pilot, authority, access, budgets, measurement and recovery targets, schedules and stack before dependent work. See values and the implementation guide.

Decision-domain studies

Added to this page by the docs site from Module studies. Documented, not drawn: text only, with no image.

These are the domains from the design. No domain has a completed customer-value epic. These studies are documented only, and no domain image is planned yet. When one is made, it uses a pale blue circle backdrop.