Handbook

lmeta execution mode

Optional AutomationFlow (lmeta v3) orchestration for the dark-factory driver loop. Default remains the sequential Python driver in driver.py.

Updated

Enabling

Set the environment flag before running pdca, the CLI, or tests:

export FORGE_DARK_FACTORY_VIA_LMETA=1

Accepted truthy values: 1, true, yes, on (case-insensitive). When unset or any other value, only driver.run is used.

pdca.run_campaign selects the implementation lazily at call time so importing forge_dark_factory.pdca does not load driver_lmeta unless the flag is on.

Flow anatomy

Artifact Role
flows/df-driver-loop.lmeta Reference flow (df-driver-loop): classify → route → switch → context → plan → unit loop → proof → assay → optional promote → finalize
src/forge_dark_factory/driver_lmeta.py Loads and resolves flows from flows/**/*.lmeta, binds run_lcdl (df.* task ids) and consumer hooks, returns DriverResult

Orchestration stays in the flow; all persistence and side effects are in hooks (see design note docs/design/LMETA-BRIDGE.md). The lmeta trace is metadata only — machine wiki writers remain in hooks, same as the legacy driver.

run_lcdl task ids (consumer-local)

Task id Wraps
df.classify classify.classify
df.route router.route
df.plan planner.plan_for_target
df.draft worker.draft_patch (ladder via forgeOperatorFallback in the flow)

These are not registered in forge_lcdl.tasks.registry (Cockpit-style routing).

Hook ownership

Hook Side effects
df.prepare_run Target copy, worktree, context pack; records context phase
df.write_plan machine/plan.json; records plan phase
df.begin_unit Binds current patch unit for foreach iteration
df.apply_verify Draft apply, verification, repair loop (driver._apply_verify_repair); records draft-*, apply+verify, repair-*
df.write_proof machine/proof.md
df.assay check_assay, machine/assay.json; records assay phase
df.promote promote_worktree_to_live when configured
df.finalize write_run, H report, freeze gate

Rollback

Unset FORGE_DARK_FACTORY_VIA_LMETA (or set to 0 / false). No code changes required; driver.py is untouched and remains the default path.

Verification

Parity gate: tests/test_driver_lmeta_parity.py (offline poc-sandbox-offline fixture, worker_ladder: [fake]) compares assay verdict fields, phases.json name set, and freeze-gate pass between legacy and lmeta paths.