Software Dark Factory Agentic Engineering Governance

Free and open source · Apache-2.0 · Developer Preview

Software Dark Factory (SDF) is the executable verification loop for governed AI-assisted software delivery.

It makes a repository’s standards, checks, and review evidence executable before human review, so a skeptical reviewer can inspect the delivery context alongside the change.

View on GitHub See the public proof

What SDF produces

A real evidence record, visible before review.

This rendered extract comes from a committed stable v0.1.0 evidence archive. The final pass retains its earlier failed run.

Read the full committed evidence record ↗

Intent

Make the public Developer Preview installation route non-invasive: it now creates or safely reuses an `sdf-demo` evaluation baseline, installs on a separate branch, and targets the draft installation PR at that baseline rather than the receiver's configured default branch.

Review focus

Check that the copyable prompt has the canonical guide URL and the required branch relationship; that existing `sdf-demo` branches cannot be overwritten; and that evaluation, later adoption, cleanup, and the human authority boundary are unambiguous. Confirm the manual walkthrough retains flexible branch choice.

Limits

Documentation and governed evidence only. This does not change CLI behaviour, package version, GitHub defaults, release state, or the manual walkthrough's disposable example mechanics. It does not create, push, merge, approve, deploy, release, or delete any receiver-repository branch or pull request.

Guidance applied

The governed change loop required evidence, configured closeout, and a checked handoff. Engineering guidance kept the public-documents change focused and reviewable. Product guidance kept the Developer Preview claims aligned with the requested human-controlled evaluation boundary. Verification guidance retained the configured verification boundary. The `portable-baseline-docs` evidence archive provided bounded precedent for concise public non-claims and evidence.

Verification history

2 total runs · 1 failed run · final pass followed earlier failure: true · latest run: passed

Continue at your pace

A safe evaluation, then your repository’s standards.

  1. Install SDF safely ↗Use the agent-led Getting Started guide to create an isolated `sdf-demo` evaluation baseline and review the draft installation PR.
  2. Review the first governed change ↗Inspect the public receiver’s ordinary catalog-validation draft PR and its installed repository workflow.
  3. Add your repository’s standards ↗Playbooks are repository-owned standards that SDF routes into the agent’s work. They are a useful next step, not a prerequisite for initial evaluation.
  4. Continue with repository-specific guidance and verification ↗See the stable v0.1.0 release notes, then adapt the guidance and verification your repository actually owns.

Why it exists

AI speeds up code. Review confidence is the bottleneck.

AI-assisted changes may now come from experienced engineers, newer engineers, people outside traditional engineering roles using agents, and several different coding tools or workflows.

That increases both the volume of PRs and the variation in how they arrive. Scope, engineering standards, verification, evidence, and context can differ from change to change, leaving reviewers to reconstruct the delivery story before deciding whether the work is acceptable.

SDF keeps the repository’s expectations attached to the change and presents them through a consistent governed reviewer handoff.

Lost intent

What was asked, why it matters, and what is out of scope can disappear into chat history.

Review overload

Reviewers should not have to reconstruct verification and risk context from a diff alone.

An uneven bar

Standards and checks are more reliable when the repository can declare them as part of the work.

The core thesis

Your team defines what acceptable delivery means.

SDF makes that definition executable before human review: the standards, checks, and evidence expectations belong to the repository. It does not impose a universal methodology from outside.

Although implementation and PR shape may vary, the standards, verification expectations, and reviewer handoff stay consistent while preserving the workflow and judgement that already make sense for the team.

Your standards

Repository-local guidance describes the quality bar and the boundaries that matter for this work.

Your checks

The repository owns the verification it expects to run and record honestly.

Your review

Evidence prepares a reviewer to decide; it does not make the decision for them.

How it works

A repository-local loop for a governed change.

SDF runs locally in the repository. Its commands make the work and its verification history reviewable without taking approval, merge, or release away from people.

01

Install the Front Door

`sdf init` installs the repository Front Door.

02

Declare early when useful

`sdf start --change-id <id>` optionally scaffolds evidence when early declaration is useful; it is not required for every change.

03

Close the configured boundary

`sdf close --change-id <id>` runs the repository’s full configured verification boundary and prepares the reviewer handoff. Focused checks support the work, but are not closeout.

04

Check installation status

`sdf status` optionally checks the installed Front Door and release identity; it is not a required lifecycle step.

A governed change in practice

Give the reviewer the story with the PR.

The current demonstration shows the difference between a useful AI-generated pull request and one that carries its delivery context into review.

Inspect the public project, then watch the Go demonstration to see the loop and consistent reviewer handoff in practice.

Before SDF

Reviewer reconstructs the story from the diff.

  • What was asked?
  • What changed?
  • What was checked?
  • What risk remains?
  • Is this acceptable to merge?
  • What context will be lost?

Standard AI PR

Standard AI PR overview

Reviewer gets a useful summary, but still has to infer the delivery evidence.

Testing notes

Testing notes

Checks may be listed, but risk, standards, and merge confidence still need to be reconstructed.

With SDF

Reviewer gets the story with the PR.

  • Intent and review focus
  • Scope and limits
  • Repository guidance applied
  • Verification results
  • Risks, unknowns, and evidence links
  • Human merge decision remains with the team

Intent

Intent and boundaries

Reviewer starts with what changed and what was deliberately left untouched.

Review focus

Review focus and limits

The handoff tells reviewers what to scrutinise and names the limits of the change.

Guidance

Guidance applied

Reviewers see which repository playbooks, standards, and verification guidance shaped the implementation.

Verification

Run context and verification

Declared run context and verification results are visible before review when those values are genuinely available.

See the public proof Inspect SDF on GitHub

Deliberate boundaries

Scope discipline is part of the product.

SDF makes a delivery boundary visible. It does not turn that boundary into autonomous software delivery.

No code writing or repair

SDF does not write or repair application code.

No agent replacement

It works around coding agents; it does not replace them.

No approval or deployment

It does not approve, merge, or deploy changes.

No correctness proof

Verification results are evidence, not a proof that software is correct.

No universal process

Teams keep ownership of their own engineering standards and workflow.

Project status

A portable baseline, designed to be adapted.

SDF 0.1.0 is a free, open-source Developer Preview. It provides the common governed-change loop for repository guidance, configured verification, retained evidence and human reviewer handoff.

Applications and teams differ in technology stack, architecture, size, product shape, delivery workflow, engineering standards and confidence with coding agents. Each receiver repository is expected to adapt the baseline with the playbooks, checks, risks and evidence expectations that make sense for its own context. The portable baseline remains useful before any advanced customisation.

Useful as a baseline

Install the CLI and use the common governed-change loop without adopting a universal engineering methodology.

Adapted by the receiver

A monolith, a group of microservices, an AI power-user team and a more cautious team can each define their own standards, checks and evidence expectations.

Playbooks, not prescriptions

The public sdf-cli playbooks show how this project encodes its own engineering guidance. They are working examples and reference material, not universal standards to copy wholesale.

Receiver-specific implementations can extend the baseline where useful—for example with model, token and cost accounting, retained evidence used as working memory, or human-reviewed learning and improvement loops. These are case-by-case adaptations, not capabilities automatically enabled by SDF 0.1.0.

Questions, receiver adaptations and contributions are welcome through GitHub.

View repository playbook examples Discuss or contribute on GitHub

Built by John Butler

A small, serious engineering project.

John Butler built SDF from the experience of owning startup software end to end, where speed matters but review confidence and delivery discipline cannot disappear.

SDF started with a lights-off ambition. Building towards it showed that greater autonomy first requires repository-owned standards, executable verification, retained evidence and clear human authority boundaries.

The current Developer Preview keeps human judgement where it matters while making more of the delivery process explicit and executable.

Why the name?