Handbook

forge-dark-factory

A governed, sequential, local-first autonomous coding loop (PoC).

Updated

The factory takes a narrow goal for a target repo and drives it through a bounded loop: classify -> route -> context -> plan -> draft -> apply -> verify -> repair -> proof -> dual-wiki trace -> escalate. The intelligence lives in deterministic logic (classifier, router, and the forge-lcdl contracts / verification / repair primitives). A small local model is only a cheap worker for bounded atoms; planning, architecture, and ambiguity escalate to a human.

  • Autonomy target (PoC): L1–L3 demonstrated (function, change-set, use-case slice). See docs/AUTONOMY-LEVELS.md and the Platform autonomy hub (per-level building blocks).
  • Non-breaking: depends inward on forge-lcdl / forge-workcells (read-only pinned submodules). No other repo is modified. The apply_fn primitive lives here; forge_lcdl.coding already accepts a caller-supplied apply function.
  • Offline-first: the demo runs with no live model and no network. The local-model path is an optional --worker local backend.

Setup

bash scripts/setup.sh

Creates .venv, checks out submodules, and installs forge-lcdl, forge-workcells, and this package editable.

Layout

Path Role
src/forge_dark_factory/classify.py Cynefin domain + t-shirt sizing (deterministic)
src/forge_dark_factory/capability.py Capability cards (model quality per task class)
src/forge_dark_factory/router.py Engine-tier selection; decompose-before-escalate
src/forge_dark_factory/apply_fn.py Git-worktree patch apply (path allowlist)
src/forge_dark_factory/worker.py Patch drafter: fake (offline) / local (Ollama)
src/forge_dark_factory/driver.py Sequential bounded loop (L1–L3 assay)
src/forge_dark_factory/wiki/ Dual wiki: machine (M) + generated human (H) + freeze gate
sandbox/calculator/ Seeded target for the offline demo

PoC demo

After bash scripts/setup.sh, run:

bash scripts/poc-demo.sh

This drives the full L1 loop on the seeded sandbox (sandbox/calculator, whose multiply is deliberately broken) using the offline fake worker, then proves the result. Expected output:

== Forge Dark Factory - PoC demo (L1, offline fake worker) ==

run_id       : run-<timestamp>-<hex>
tier         : local
final_status : pass
escalated    : False
human_report : runs/run-<...>/human/report.md
machine_dir  : runs/run-<...>/machine

-- verifying dual-wiki freeze gate --
human report matches machine records
-- verifying sandbox tests are green in the applied worktree --
..                                                                       [100%]
2 passed in 0.03s

PoC demo OK

The run leaves a machine record (M) under runs/<id>/machine/, a generated human narrative (H) at runs/<id>/human/report.md, and an SDLC decision entry under ember-logs/. Offline smoke check: python scripts/dark_factory_check.py.

Drive any target directly:

python -m forge_dark_factory.cli run \
  --goal "fix failing multiply" \
  --target sandbox/calculator \
  --out runs \
  --worker fake --fixture sandbox/fixtures/multiply_fix.json \
  --ember-logs ember-logs

Swap --worker fake for --worker local to draft patches with the Granite host (OpenAI-compatible gateway). Env files are auto-discovered from the workspace:

  1. FORGE_DARK_FACTORY_LLM_ENV_FILE (override)
  2. FORGE_LCDL_GRANITE_ENV_FILE
  3. forge-composer-workbench/project-management-certification/certification-llm.local.env
  4. forge-certificators/example-banks/forge-certificator-secrets.env
  5. Other known workspace env files (see src/forge_dark_factory/llm_env.py)

Granite end-to-end demo (no fixture; live model):

bash scripts/poc-demo-granite.sh

Granite probe and calibration harness (long timeout, local-only matrix):

bash scripts/granite-harness.sh --probe-only
bash scripts/granite-harness.sh --skip-readme   # calculator task

See docs/GRANITE-HARNESS.md.

PDCA campaigns

Sequential campaigns with Granite-first drafting, Cursor CLI fallback, model reliability reports, and optional promotion to live checkouts after gates pass.

bash scripts/run-pdca-campaign.sh campaigns/poc-boundary.yaml
bash scripts/run-pdca-campaign.sh campaigns/lenses-production.yaml
bash scripts/run-pdca-campaign.sh campaigns/lenses-production-l2-ci.yaml
bash scripts/run-pdca-campaign.sh campaigns/lenses-production-l3-ci.yaml

Campaign items may declare an optional sublevel: (e.g. sublevel: L2.2) beside level:. The assay gate then enforces that sub-level's distinct evidence in addition to the level's core evidence — e.g. L2.2 requires a recorded pre-existing failing test, and L3.x E2E evidence must match the registered runner allowlist (E2E_RUNNERS in assay_gate.py), not a name lookalike. Sub-level ladder: Blueprints AUTONOMY-LEVELS.md § Sub-levels.

See docs/PDCA-CAMPAIGNS.md for worker ladder, model reports, and promotion policy.

L1 complete when bash scripts/campaign-signoff.sh exits 0 (Granite or Cursor winner per item).

L2 complete when sign-off includes green L2 campaigns (lenses-production-l2-ci.yaml offline; full sign-off adds lenses-production-l2.yaml with Granite or Cursor per item).

L3 complete when sign-off includes green lenses-production-l3-ci.yaml (pytest + Playwright) and optionally lenses-production-l3.yaml with Granite or Cursor per item.

Or pass an env file explicitly:

python -m forge_dark_factory.cli run \
  --goal "fix failing multiply" \
  --target sandbox/calculator \
  --out runs \
  --worker local \
  --llm-env ../forge-composer-workbench/project-management-certification/certification-llm.local.env

Docs