All chapters
  1. Start hereA software factory, from first principles
  2. Primitive · 1A factory, before AI: input, transformation, check, output
  3. Primitive · 2From repetition to a pattern: what stays, what varies, what to leave alone
  4. Primitive · 3The specification as an executable contract
  5. Primitive · 4Build the smallest factory: four stations, two specs, one manifest
  6. Primitive · 5Assembly stations: typed contracts, owners and failure handling
  7. Primitive · 6AI enters the factory: what a model adds, and what stays deterministic
  8. WatchAlgo · 7The WatchAlgo production story: what the repository shows
  9. WatchAlgo · 8A problem as a production unit: the files one unit must contain
  10. WatchAlgo · 9Station by station: description, solution, implementations, visualization
  11. WatchAlgo · 10The visualizer factory: from algorithm state to renderable steps
  12. WatchAlgo · 11Three flavors and three languages: two different contracts
  13. WatchAlgo · 12Looping over a large backlog: scheduling, limits and a failed-case queue
  14. WatchAlgo · 13Long-running agent execution: context, checkpoints and token limits
  15. WatchAlgo · 14Evidence of correctness: tests the producer cannot talk its way past
  16. WatchAlgo · 15The factory learning loop: defects change the pattern, not only the unit
  17. Enterprise · 16Classify the enterprise demand before choosing a pattern
  18. Enterprise · 17Reference enterprise patterns and their variation points
  19. Enterprise · 18Platform foundations: golden paths, templates, registries and catalogs
  20. Enterprise · 19Pattern versus configuration versus business logic
  21. Enterprise · 20Insurance factory, part 1: building the intake contract
  22. Enterprise · 21Insurance factory, part 2: building the underwriting workflow
  23. Enterprise · 22Insurance factory, part 3: trust and observability built in
  24. Enterprise · 23Data and integration engineering: contracts that survive change
  25. Enterprise · 24The CI/CD and deployment factory: from pull request to production
  26. Enterprise · 25Enterprise governance: owners, approved patterns and provenance
  27. Enterprise · 26Scaling safely: many teams, many agents, one set of boundaries
  28. Operations · 27Factory quality engineering: measuring accepted output, not activity
  29. Operations · 28Failure and recovery scenarios: what breaks a factory, and what restores it
  30. Operations · 29The landscape: which tool for which job, read from its own documentation
  31. Operations · 30Design an enterprise software factory: the blueprint and the rollout
  32. ReferenceSources and verification
  33. ReferenceGlossary
  34. AboutAbout this site
Enterprise · 18

Platform foundations: golden paths, templates, registries and catalogs

The paved road a factory stands on: organization standards, repository templates, artifact registries, environment configuration and a software catalog, and what each one does not decide.

You will separate
Six platform foundations, each with one decision it makes and the decisions it leaves to the factory and the product.
You will query
A software catalog to answer who receives a fix, in one run instead of a week of searching repositories.
You will decide
Whether to plug the factory into the existing delivery platform or build a new one, and how a team leaves the golden path on the record.

On a Monday morning the security reviewer of the synthetic insurer sends one question to every engineering lead: "Which of our services still accept an expired token on some routes and reject it on others?" The authentication code of the intake services came from one pattern, PAT-INTAKE-API, and the fix is a few lines in its middleware. Writing the fix takes an hour.

Finding who needs it takes the rest of the week. One intake service was built by the factory last month. Another was generated from an older version of the pattern and then edited by hand. A third copied the authentication module from the second. Nobody can say which service runs which version, who owns it, or which build is in production, because none of that was written down in one place. The factory built each service correctly. Nothing around the factory recorded what it built.

The learner's question: what does a factory need from the organization it runs in, what does each of those foundations decide, and what does each one leave undecided?

The platform under the factory#

Plain English. A platform is the set of shared services every team uses instead of building its own: a way to start a repository, a place to store builds, a way to configure environments, and a list of what exists and who owns it. A factory is one heavy user of it.

The previous chapters built factories that stand alone. Example C (examples/c-insurance-service/) assembles the broker intake service from PAT-INTAKE-API 2.1.0 and the product spec SPEC-INTAKE-001 in factory run FR-0003, and writes a rollout manifest that names three environments, a five percent canary and a person with the release-approver role. Its README is explicit that the manifest is "documentation only": nothing deploys, nothing is stored outside the example's out/ folder, and no catalog learns that the service exists. That is the right boundary for a teaching example. In an organization, those missing parts are the platform.

Platform engineering is the discipline of building and running those shared capabilities as a product for the organization's own teams. Guideline (CNCF Platforms White Paper, TAG App Delivery, read 2026-11-20): the paper defines a platform for cloud-native computing as "an integrated collection of capabilities defined and presented according to the needs of the platform's users". It calls such platforms internal because they serve only the enterprise's own users, and it says a platform should provide capabilities without necessarily implementing them; a platform can be as thin as a wiki of standard procedures.

An internal developer platform is the common name for that collection when its users are the organization's engineers. One honest note: the CNCF paper read here uses "internal platform" and "platform engineering" and does not use the phrase "internal developer platform". This site uses the common phrase and means the same thing.

Before AI. A company Maven parent POM that pins plugin versions, a Jenkins shared library every pipeline imports, an internal Spring Initializr with the company's starters preselected, an internal artifact repository, a wiki page titled "how we deploy": that was a platform, often without the name. A factory reuses all of it. It adds one new kind of user that starts many products quickly and never forgets a step it was given, and also never notices a step it was not given.

Six foundations, and what each one decides#

A useful way to understand each foundation is to ask what single question it answers for the factory, and which question it leaves to someone else. The examples below follow Example C's intake service from its first commit to the moment someone asks who owns it.

Golden path: the supported way to do one common job#

A golden path is a bundled, supported workflow for a common job, offered with a template and documentation, that most teams follow because it is the easiest route. Guideline (CNCF Platforms White Paper, read 2026-11-20): the paper describes a golden path as a bundled workflow, for example a supply chain to build, scan, test, deploy and observe a web app, offered with a project template and documentation. Many organizations call the same thing a paved road; this site uses both words for one idea.

For the intake service, the golden path would be: start from the intake repository template, let the factory fill it from the spec, run the organization's standard CI checks, publish the build to the registry, register it in the catalog, promote through the standard environments. It decides the route. It does not decide the product's business rules, the fields of its submission, or whether R-ROOF-03 escalates at five years or six. Those stay in the spec and the product's own rule module.

Organization standards: rules every product must meet#

A standard is a rule that holds for every product regardless of who built it: logs carry a trace id, personal data is masked, every service has an owner. Example C's pattern already encodes some as constraints (logs_mask_pii, human_decision_roles: ["underwriter"]). A standard decides what must be true. It does not decide how a product meets it; the pattern and the product do, and a gate checks it.

Repository template: the first commit#

A repository template is a concrete starting repository (folders, build file, CI configuration, a catalog descriptor) that a new product is created from. It decides the first commit. It does not keep the product aligned afterwards: a template is copied once, and every later change to the template reaches existing products only if someone carries it there. That is the gap between a template and a pattern with versions, which From repetition to a pattern introduced.

Artifact registry: where a build lives, by digest#

An artifact registry is the store where built, versioned artifacts live (packages, container images, generated contracts), each addressable by a version and a content digest. Example C's factory already computes the digest of every file it writes; the manifest of FR-0003 lists openapi.json as sha256:d79646305fc5.... A registry would keep those files immutable and retrievable by that digest. It decides where the artifact lives and that it cannot change in place. It does not decide whether the artifact is good; the gates of CI/CD and deployment do that before anything is published.

Environment configuration: what changes between deployments#

Environment configuration is every value that differs between the places a product runs (development, staging, production): hostnames, credentials, the address of the real provider. Guideline (The Twelve-Factor App, "Config", read 2026-11-20): it defines an app's config as "everything that is likely to vary between deploys" and says a twelve-factor app stores it in environment variables, managed independently per deploy rather than bundled into named groups. Environment configuration decides what differs per environment. It does not decide what the product does; a retry limit of three attempts is product behavior written in the spec, not a per-environment value.

Software catalog: what exists and who owns it#

A software catalog is the system of record for every product, its owner, its pattern and version, and its relationships. Product (Backstage Software Catalog, as documented on 2026-11-20): the documentation describes a centralized system that tracks ownership and metadata for all software in an organization, with metadata YAML files stored with the code as the source of truth. The catalog decides nothing about how a product is built. It answers the Monday question: who has this, which version, and who must approve a change.

Diagram: What the platform runs, what the factory does, what each product keeps

Three lanes. The platform lane holds the shared foundations run once for everyone: the repository template, the standard CI checks, the artifact registry, environment configuration and the software catalog. The factory lane consumes the template and the spec, writes artifacts into the registry by digest and registers what it built in the catalog. The product lane keeps the spec, the business-rule module and the release approval. No platform box holds a business rule.

  1. Platform team
    1. repository template: Concrete starting files: folders, build file, CI configuration, catalog descriptor.
    2. standard checks: The supported route: build, scan, test, publish, register, promote.
    3. artifact registry + environment config: Immutable builds addressed by digest, and the values that differ per environment.
    4. software catalog: One record per product: owner, pattern, version, relations.
  2. Factory
    1. check the spec: Refuses a spec that leaves an extension point empty.
    2. generate contracts + service config: Writes the API contract, event schemas and the service configuration.
    3. push artifacts by digest: Every output with its sha256, ready for the registry.
    4. register the product: The last station writes the catalog entry from the manifest.
  3. Product team
    1. product spec: Fields, roles, routes, workflow, events for one product.
    2. business-rule module: The product's own decisions, owned by its domain team.
    3. release approval: A person with the release-approver role signs off before promotion.

Read the three lanes from left to right. The top lane is what the platform team runs once for everyone. The middle lane is the factory: it consumes the template, writes artifacts into the registry and registers what it built. The bottom lane is what stays with each product team: its spec, its rule module and its approval to release. Each arrow crosses a lane boundary at a contract, and none of the platform boxes contains a business rule.

FoundationDecidesDoes not decideExample C today
Golden paththe supported route for a common jobthe product's rules or fieldsnot present: the README describes the route only in text
Organization standardswhat must hold for every producthow a product meets itpartly: constraints in pattern.json
Repository templatethe first commitanything after the first commitnot present
Artifact registrywhere a build lives, immutable, by digestwhether the build is gooddigests computed in the manifest; no store
Environment configurationvalues that differ per deploymentproduct behaviorthree environment names in the rollout manifest; no values
Software catalogwhat exists, owner, version, relationshow anything is builtnot present

The right-hand column is the useful one. Example C already produces most of what a platform needs (an owner role, a pattern version, a spec hash, digests). What it lacks is a place to put them that outlives the run.

The smallest primitive: a catalog that can answer one question#

A catalog does not need a portal to be useful. It needs one record per product with four facts: the product id, the owner, the pattern it pins, and the version. The blast lab keeps exactly such a catalog. Teaching reconstruction: its eight products on three pattern lines are synthetic, except the names that come from the examples (broker-submission-intake and PAT-INTAKE-API 2.1.0 from Example C, running-sum and clamp-list from Example A); every owner and test count is the lab's own.

The script below was written for this page and run on a scratch copy of examples/labcore/. It prints the catalog, then asks the lab's own function b_blast.radius who receives the authentication fix from the opening story. What it demonstrates: with a catalog, the Monday question is a query. What it does not demonstrate: that the catalog is true. A catalog is only as good as the process that keeps it in step with what is deployed.

import sys

sys.path.insert(0, sys.argv[1])
import b_blast  # noqa: E402

cat = b_blast.CATALOG
print("catalog:", len(cat["products"]), "products on", len(cat["patterns"]), "pattern lines")
for p in cat["products"]:
    print(f"  {p['id']:<28} {p['pattern']} {p['version']:<6} owner: {p['owner']}")
r = b_blast.radius(cat, "auth-middleware")
print()
print("change:", r["label"], "|", r["kind"], "->", r["bump"])
for t in r["patterns"]:
    print(f"  pattern {t['pattern']} {t['from']} -> {t['to']} (owner: {t['owner']})")
for a in r["affected"]:
    print(f"  affected {a['product']:<28} {a['tests_selected']} of {a['tests_total']} tests selected")
for n in r["not_affected"]:
    print(f"  not affected {n['product']}: {n['reason']}")
print("  suite:", r["suite"]["selected"], "of", r["suite"]["total"], "tests")
print("  approvals:", "; ".join(r["approvals"]))
catalog: 8 products on 3 pattern lines
  broker-submission-intake     PAT-INTAKE-API 2.1.0  owner: submissions team
  claim-notice-intake          PAT-INTAKE-API 2.1.0  owner: claims team
  endorsement-request-intake   PAT-INTAKE-API 2.0.0  owner: policy servicing team
  loss-run-request-intake      PAT-INTAKE-API 1.4.0  owner: claims team
  running-sum                  PAT-ALGO-UNIT 1.3.0  owner: algorithm content team
  clamp-list                   PAT-ALGO-UNIT 1.3.0  owner: algorithm content team
  policy-event-relay           PAT-EVENT-WORKER 1.4.0  owner: integration team
  audit-export-job             PAT-EVENT-WORKER 1.4.0  owner: compliance engineering

change: Auth middleware: expired tokens rejected the same way on every route | fix -> patch
  pattern PAT-EVENT-WORKER 1.4.0 -> 1.4.1 (owner: integration team)
  pattern PAT-INTAKE-API 2.1.0 -> 2.1.1 (owner: platform team)
  affected broker-submission-intake     4 of 50 tests selected
  affected claim-notice-intake          4 of 40 tests selected
  affected endorsement-request-intake   3 of 29 tests selected
  affected policy-event-relay           2 of 24 tests selected
  affected audit-export-job             2 of 18 tests selected
  not affected loss-run-request-intake: pinned to PAT-INTAKE-API 1.4.0, an older major line; it keeps that version until it upgrades
  not affected running-sum: PAT-ALGO-UNIT does not ship authentication
  not affected clamp-list: PAT-ALGO-UNIT does not ship authentication
  suite: 15 of 206 tests
  approvals: integration team (owner of PAT-EVENT-WORKER); platform team (owner of PAT-INTAKE-API); security reviewer (authentication is a governed component)

Three lines matter. Five products on two pattern lines receive the fix, and the list names their owners, so the Monday question has an answer with names in it. One intake service is "not affected" only because it is pinned to an older major line: it still has the old behavior, and the catalog is what makes that visible instead of silent. And a security reviewer appears in the approvals because the catalog marks authentication as a governed component. The counts are the lab's synthetic tests, not measurements. How the version bump and the regression suite are computed is the subject of Factory learning loop; this page cares that the question could be asked at all.

The second half of the primitive is the record the factory itself leaves. Example C's manifest for FR-0003 already carries what a catalog entry and a registry need, quoted from a scratch run of run.py:

{
  "factory_run_id": "FR-0003",
  "pattern_id": "PAT-INTAKE-API",
  "pattern_version": "2.1.0",
  "spec_id": "SPEC-INTAKE-001",
  "specification_hash": "sha256:ecb151ab7f7f7b10e9dfa0922a3fe2eeb174e73cdbf04807abab08a34ed2e2ad",
  "artifacts": {
    "openapi.json": "sha256:d79646305fc547b1489df9214098ef3d393ec16a389ba8d0e5e3b13acbec6881",
    "service_config.json": "sha256:1167f3f8d00ffd4316c0e7f6ece5a5966a21f61bf459f6dde7e3461089c58097"
  }
}

(Shortened to two of the five artifacts; the values are as printed.) The integration a platform needs is small: the factory's last station registers this record in the catalog and pushes the files to the registry under their digests. Build the smallest factory is the home of manifests and hashes.

What a platform template looks like in a real tool#

Product (Backstage Software Templates, as documented on 2026-11-20): a template is an entity with apiVersion: scaffolder.backstage.io/v1beta3 and kind: Template, with metadata, a spec.owner and a spec.type. Its spec.parameters are form steps written as JSON Schema plus ui: keys, and its spec.steps are a list of actions such as fetch:template, publish:github and catalog:register. The shape below is assembled from the documented fields for the intake service. Documented shape; not run here, and not checked by this site's build.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: intake-service
  title: Intake service (PAT-INTAKE-API 2.1.0)
  description: Starts a repository the factory fills from a product spec.
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Product
      required: [productName, owner, repoUrl]
      properties:
        productName:
          type: string
        owner:
          type: string
        repoUrl:
          type: string
  steps:
    - id: fetchSkeleton
      name: Fetch the skeleton
      action: fetch:template
      input:
        url: ./skeleton
        values:
          productName: ${{ parameters.productName }}
    - id: publishRepo
      name: Publish
      action: publish:github
      input:
        repoUrl: ${{ parameters.repoUrl }}
    - id: registerEntity
      name: Register in the catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publishRepo.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

Two details come from the documentation and save real debugging. The step ids are camelCase because the page warns that dashes in step ids can make expressions return NaN. And the source pack found two Backstage pages that disagree on the template's apiVersion (backstage.io/v1beta2 on the descriptor-format page); the writing-templates page, quoted above, is the one to follow.

Notice what the template does and does not do. It creates the repository and registers the entity in one run. It does not validate a product spec, it does not run the factory's stations, and it does not re-check the repository next month. A template engine such as Cookiecutter, Yeoman or the Backstage scaffolder is the platform's first-commit service; the factory's pattern and gates still own whether the result is right.

What this is not. This page owns the foundations a factory stands on. The release gates, test tiers and canary of one product are CI/CD and deployment; one change's path from review to production is Diff to Deploy. Who approves a pattern and how exceptions are governed is Enterprise governance. The controls around one coding agent's run are Harness Engineering.

Plug into the delivery platform, or build a new one?#

This page owns one of the site's eleven decisions. A team building its first factory is tempted to build everything it touches: a runner, a store, a registry of what it produced, a dashboard. Most organizations already have most of that.

The question. Should the factory integrate into the existing delivery platform, or bring a new platform of its own?

Diagram: Plug into the delivery platform, extend it, or build beside it

Ask the questions on the left in order. If the existing platform already holds this kind of product and can give the factory a scoped identity, the factory plugs in as one more user. If one capability is missing, extend the platform once for every later factory. Build something new beside the platform only when the product kind does not fit and someone commits to own it after the pilot; otherwise a second catalog and registry drift away from the first.

  1. Ask in order
    1. does the platform hold this kind of product?: Services, jobs and contracts like the ones the factory will make.
    2. can the factory get a scoped identity on it?: Create repositories from the template, push to the registry, register in the catalog, nothing else.
    3. is exactly one capability missing?: For example a runner for station workers with scoped credentials.
    4. will someone own a new platform after the pilot?: A named team, a budget, an on-call rotation.
  2. Least new machinery
    1. integrate: the factory is a platform user: One catalog, one registry, one gate set; reviews already done.
    2. extend the platform once: Fill the gap for every later factory.
    3. build beside it, with an owner: Full control during a pilot, at the cost of a second catalog and registry.
    4. stop: fix ownership first: A platform without an owner fails the factory that depends on it.

Read the questions top to bottom. If the existing platform already runs builds, stores artifacts and records ownership for products like the ones the factory will make, plug in: the factory becomes one more user, and its outputs look like everyone else's. Build something new only for the parts the platform truly cannot provide, and only with an owner who will run it after the pilot.

OptionChoose it whenIt gives youIt costs you
Integrate: the factory is a platform userthe platform covers the product kind (services, jobs) and accepts new producersone catalog, one registry, one set of gates; security review already donethe platform's pace and constraints; requests to the platform team
Extend: add the missing capability to the platformone capability is missing (for example a station runner with scoped credentials)the gap filled once, for every later factorydesign and run work for the platform team
Build new beside the platformthe products are a new kind the platform cannot hold, or the platform has no ownerfull control during a pilota second catalog, registry and gate set that drift from the first

The criteria, in order: does the platform already hold this kind of product; can the factory's identity be given scoped credentials on it; who will own any new piece in a year; and whether the security and compliance reviews already done for the platform would have to be repeated for a new one.

The counterexample. WatchAlgo is a case where building nothing beyond a few scripts was right: one author, static files, no external users. The factory needed a queue, validators and checkpoints, and it had them; a catalog and an approval flow would have cost more than they saved. The enterprise case is the opposite, because the catalog and the approvals are what the security reviewer asks for on Monday.

The failure modes. A factory that builds its own registry produces artifacts the deployment tools cannot find. A factory that keeps its own list of products answers "who has this" for its products only, and the hand-edited copies from the opening story stay invisible. And a factory forced through a platform that cannot hold its product kind gets bent into workarounds, which is the moment to extend the platform instead.

Golden path or a justified deviation?#

The second decision on this page is about staying on the path. A golden path is only useful if most products follow it; it is only honest if some can leave it with a reason.

The question. When a product team wants to leave the golden path, is that a defect to block or a deviation to allow, and how is it recorded?

OptionChoose it whenFailure mode
Strict compliance, no exceptionsthe rule protects something irreversible (who may decide, masking of personal data)teams work around the gate instead of through it
Deviation with a logged exceptionthe product has a real need the path does not serveexceptions pile up unread and never expire
Change the paththe same exception is requested by several teamsthe path grows switches until nobody can test it

The criteria: how severe the harm is if the rule is broken; whether the deviation can be checked by a gate anyway; and how many teams are asking. The counterexample is in Example C itself: human_decision_roles: ["underwriter"] admits no exception at all, and the factory refuses a spec that opens the decision route to the agent (test_spec_cannot_open_the_decision_route_to_the_agent). A rule like that belongs in the pattern as enforced code, not on a path a team may leave.

For everything else, an exception is a record, not a conversation. Teaching reconstruction: a minimal exception record a catalog could hold, with an owner, a reason, a compensating check and an expiry date:

{
  "exception_id": "EXC-0012",
  "product": "endorsement-request-intake",
  "rule": "golden path: promote through dev, staging, production",
  "deviation": "no staging environment until the partner sandbox exists",
  "reason": "the partner offers no test system; staging would call production",
  "compensating_check": "contract tests against a recorded fake of the partner API on every change",
  "approved_by_role": "platform team",
  "expires": "2027-03-31",
  "status": "approved"
}

The fields that matter are the last four. A compensating check makes the deviation still testable. An approving role makes it someone's decision. An expiry date makes the platform team look again. A status lets the catalog count open exceptions per rule, which is how a team learns that a rule should change. Enterprise governance owns the approval process and its roles.

In a coding agent. A coding agent such as Claude Code or Codex, running headless as a station worker, is a platform user with unusual habits: it follows the template it is given exactly, and it will also edit generated files if nothing stops it. Give it the same golden path as a person: a checkout created from the repository template, credentials scoped to that repository, and the organization's standard checks, not its own, deciding whether the work advances. The runtime controls around that run are Harness Engineering.

Try it#

The lab opens on the platform view of the synthetic catalog: an authentication fix in the shared middleware. Pick other changes to see which products, owners and approvals each one reaches, and read the products the lab lists as not affected, with the reason.

The table holds the same result for a reader without JavaScript. docs/LABS.md has no plain table for this lab yet, so it was written for this page from the scratch run above of examples/labcore/b_blast.py : radius (change auth-middleware). Counts are the lab's synthetic tests.

ProductPattern and versionOwnerResultTests selected
broker-submission-intakePAT-INTAKE-API 2.1.0submissions teamaffected4 of 50
claim-notice-intakePAT-INTAKE-API 2.1.0claims teamaffected4 of 40
endorsement-request-intakePAT-INTAKE-API 2.0.0policy servicing teamaffected (same major line)3 of 29
loss-run-request-intakePAT-INTAKE-API 1.4.0claims teamnot affected: older major line, keeps the old behavior0
policy-event-relayPAT-EVENT-WORKER 1.4.0integration teamaffected2 of 24
audit-export-jobPAT-EVENT-WORKER 1.4.0compliance engineeringaffected2 of 18
running-sum, clamp-listPAT-ALGO-UNIT 1.3.0algorithm content teamnot affected: no authentication0

Totals: patch bump on two pattern lines (to 2.1.1 and 1.4.1), 15 of 206 tests selected, three approvals including the security reviewer. No model takes part in this lab. Where the examples put an agent at a station, the agent there is a scripted stand-in, so these results show how the factory mechanics work, not how good any model is.

WatchAlgo in practice#

WatchAlgo ran without a platform in this page's sense, and its repository shows both why that was reasonable and what it cost.

Observed in the repository (zenalgo-frontend, HEAD 1b183564; docs/EVIDENCE.md rows 15 and 16): there is no test suite in the app's package.json (its scripts are dev, build, start and lint); content checks are validators run by the pipeline. Content is published as static JSON from public/content. The remote holds only main (ea250663, 217 visualizations) while the live site serves content of the 2,162-visualization era, and the sitemap generator is untracked. EVIDENCE.md labels the conclusion an inference: consistent with a command-line deploy of the local working tree, with no deployment record inspected.

Read that through this page's table. There was no artifact registry: the published build cannot be tied to a commit. There was no catalog beyond the folders themselves, though the folder scheme wa-NNNNNN and a work list rebuilt from disk (row 11) did the job of one for a single author. There was no environment configuration problem worth the name, because there was one environment.

Reported by the author: the corpus of 3,246 problems was produced by a repeatable process over long sessions (The WatchAlgo story holds the evidence and its limits). Teaching reconstruction: the smallest platform addition that would have paid for itself is the registry rule "publish from a tagged commit and record the commit in the deployment", which is exactly the row EVIDENCE.md lists as missing.

Enterprise translation#

In the insurer's organization, the platform team owns the intake repository template, the registry, the catalog and the environment definitions; it also owns PAT-INTAKE-API, because the pattern is a platform product. Domain teams own the product specs and rule modules: the submissions team owns broker-submission-intake, the claims team owns its own intake products. The factory is a platform user with its own identity, allowed to create repositories from the template, push artifacts to the registry and register entities in the catalog, and nothing else.

What dominates the critical path is rarely the factory. It is the security review of the factory's identity and permissions, the agreement on which standards are enforced by gates and which are guidance, and the migration of the existing hand-built services into the catalog so that "who has this" includes them. A factory that produces new services into a catalog that does not list the old ones answers the Monday question for the easy half only.

Failure test#

The failure: a product team copies the authentication module out of the template into its own code, so its service no longer depends on the pattern's component. The catalog still says it pins PAT-INTAKE-API 2.1.0. When the platform team ships the expired-token fix, the catalog reports the product as affected, the selective tests run against the pattern's middleware, and the team's copy keeps the old behavior.

How the factory catches it: not by the catalog alone, and this is the lesson. A catalog records declared dependencies; it cannot see a copy. What catches the drift is a gate that checks the product against the pattern on every build: a contract check like Example C's gate_contract, which compares the generated contract with the spec and fails on a hand edit (test_contract_gate_catches_a_hand_edited_contract opens the decision route to broker, drops 403 and adds GET /admin, and the gate fails). A platform that only scaffolds and never re-checks has no defense against the copy.

What to run or toggle: in a scratch copy of Example C, run /opt/homebrew/bin/python3 -m unittest tests.test_factory_gates and read the contract-gate test. In the lab, pick the authentication change and read the not-affected row for loss-run-request-intake: a product that is honestly on an older line is visible; a product that silently forked is not.

Where to go deeper#

Checklist for Monday#

Exercises#

  1. A team asks to raise the provider retry limit from three to five attempts in production only. Environment configuration or product spec?
Answer 1Product behavior, so the spec

The retry limit is product behavior (Example C declares it in external_systems.roof_assessment_provider.retry in the spec) and is tested by the factory's tests. Changing it per environment would mean production runs behavior that no test environment ran.

  1. The catalog says nine services pin PAT-INTAKE-API, but the registry shows builds for eleven. What do the two extra builds tell you?
Answer 2Unregistered producers

Something is publishing builds without registering them: a hand-built service, a forked copy or a second factory. Until they are in the catalog, no change to the pattern will reach them through the normal process.

  1. Why is "only an underwriter may record a decision" not a candidate for a logged exception?
Answer 3Irreversible harm

Breaking it lets a non-person or an unauthorized role decide an insurance outcome, which no compensating check repairs after the fact. Rules of that kind are enforced in the pattern, and the factory refuses a spec that breaks them.

Advanced perspective#

The platform as a product, and how to tell if it worksUsers, measures, and what the factory adds to them

Guideline (CNCF Platforms White Paper, read 2026-11-20): the paper lists seven attributes of a platform, starting with "platform as a product" and including self-service, reduced cognitive load, optional and composable, and secure by default. It says platform teams own interfaces and experiences (portals, APIs, templates, command-line tools), not necessarily the infrastructure, and should build a capability themselves only when no provider can supply it. For measuring success it names user measures (active users and retention, surveys, SPACE-framework productivity measures) and organizational ones (request-to-fulfillment time, time to deploy a new service, time for a new user to submit a first code change), and it cites the four DORA delivery measures by their older names.

A factory changes what those measures mean. "Time to deploy a new service" can drop sharply when a factory fills a template from a spec, while the time to an accepted, reviewed, approved service barely moves because approval dominates. Measure both. Factory quality engineering is the home of lead time and cost per accepted unit; the platform team should report the platform's measures with the factory's outputs counted separately, so a fast generator does not hide a slow review queue.

The paper also says it should be read alongside the later Platform Engineering Maturity Model; that page was not read for this site.

Where the catalog's truth livesDescriptor files with the code, registration by the factory, drift checks

A catalog that someone edits by hand in a web form drifts within months. Product (Backstage Software Catalog, as documented on 2026-11-20): metadata YAML files stored with the code in source control are the source of truth; entities are registered manually, automatically when created by a Software Template, or through static locations in configuration. The recommended file name is catalog-info.yaml, and a Component requires spec.type, spec.lifecycle and spec.owner.

The factory-specific design follows from that. The descriptor is a generated artifact: the factory writes it from the spec and the pattern (owner, pattern id and version, spec hash), commits it with the product, and the catalog reads it. A hand edit to the descriptor is then a difference between a generated file and its source, which the same contract-style gate that protects the API contract can catch. Two consequences to plan for: products the factory did not build need descriptors written once by people, and the catalog must distinguish "declared" from "verified by the last build", or the Monday answer is a list of claims.

Environment names versus environment valuesWhy the rollout manifest's three names are not configuration

Example C's spec lists environments: ["dev", "staging", "production"] in its rollout section. Those are stages of promotion, a process decision. The values a service needs in each (hostnames, credentials, the provider endpoint) appear nowhere in the example, correctly: the provider is a stub and the tokens are demo strings.

Guideline (The Twelve-Factor App, "Config", read 2026-11-20): config is everything likely to vary between deploys, stored in environment variables, and each variable is managed independently per deploy rather than grouped into named environments, which the page says does not scale cleanly. That is compatible with promotion stages: the stage names say where a build goes next; the variables say how it connects there. The page's test is whether the codebase could be made open source at any moment without compromising any credentials. For a factory the corresponding rule is stricter: no credential may appear in a spec, a template, a generated file or a prompt. Example C's forbidden-secrets gate scans every file for credential shapes and allowlists only tokens with the DEMO-NOT-A-SECRET- prefix; a real platform puts the scan in the standard checks, so every factory gets it.

Who pays for the platform the factory needsAmortizing core assets, and the cost of a second catalog

Guideline (SEI Software Product Lines, read 2026-11-20): the SEI material lists core assets amortized across products, among them architecture, test plans, processes and tools, and names "core asset development" as one of three essential activities, alongside product development and management. A platform is a core asset in that sense, and its cost is justified across many products, not by the first one.

The trap for a factory pilot is to account the other way: the pilot builds its own runner, registry and product list because the platform team's queue is long, and the pilot looks cheap. The cost appears later, as a second catalog that the security reviewer does not trust, artifacts the deployment tools cannot find, and a migration onto the platform after the pilot succeeds. A sounder plan budgets the integration work (an identity for the factory, a registry namespace, a catalog descriptor) into the pilot, and builds new only what the platform truly lacks. Design an enterprise software factory covers pilot selection.

In one breath#

A factory builds products; a platform makes them findable, storable, configurable and owned. Each foundation answers one question and leaves others alone: the golden path sets the route, standards say what must hold, the repository template writes the first commit, the registry keeps builds immutable by digest, environment configuration holds what varies per deployment, and the catalog says what exists and who owns it. None of them decides a business rule, and a catalog without a re-checking gate cannot see a copied component.

The intake service now has a place in the organization: a template to start from, a registry for its builds, a catalog entry with an owner. What the platform cannot tell you is which parts of the service belong to the shared pattern, which are per-product settings, and which are business logic that must never be shared. Pattern versus configuration versus business logic draws those three lines in Example C's own files.