Vinculum Loop — the autonomous, governed dev loop for any project

Two pieces work together. Keep them distinct:

1. The loop = orchestration. The dark-factory-build skill + the Workflow tool. This is what actually runs: mission → discover → PO → design → TDD build → deploy → test → ship — autonomously, sub-agent-fanned, Promise-Theory-verified. Works on any project today.
2. The substrate = trust / provenance (optional, not in this package). A separate, harness/LLM-agnostic signed-provenance layer can record every decision/action as a hash-chained, append-only ledger entry. It is not bundled here and not required — the loop runs fully without it. Enable it later only if your org wants cryptographic provenance.

You run the loop with dark-factory-build. The signed-provenance substrate is an optional layer underneath — the loop's correctness rests on Promise-Theory verification, not on signing.

When to use

• "Give me a mission objective and full autonomy" → the 2-trigger contract.
• "Run the loop / vinculum loop on <project>."
• Any non-trivial build you want done end-to-end: evidence-gated, ticketed, documented.

The contract the loop guarantees (the VR invariants)

• VR-5 — 2-trigger notify: come back only when the objective is met or blocked on all fronts. No step-wise check-ins.
• A/B/C decisions: A = hard blocker → escalate · B = reversible → decide + log · C = "is it done?" → own the judgment.
• VR-1 — evidence-gated (Promise Theory): decisions rest on proven claims; a sub-agent's "done / all passing" is unverified until you re-run its evidence.
• VR-3 — sensitive data never cleartext public: keep PHI/secrets private; publish only hashes/metadata.
• VR-7 — harness/LLM-agnostic: Claude Code or any agentic harness; API key, subscription, or local OS model.
• VR-2 / VR-6 — sign-before-act + append-only hash-chained ledger: provided by the optional provenance substrate. Not active in the default unsigned mode described here.

How to run it on a NEW project

1. Frame: mission objective + explicit hard-stops (prod deploy, merge to protected branch, financial/on-chain spend, outbound mail/posts).
2. Orchestrate: invoke dark-factory-build, or launch a Workflow running discover → PO → design → TDD build → deploy(dev) → test → QA, each stage blind-verified (df-adversary-gate).
3. Record decisions: the loop's durable decision record is the stage docs + tickets it writes. (Optional: an internal signed-ledger substrate can additionally sign + hash-chain each entry — not included here, not required.)
4. Autonomy: act in dev/non-prod by default; HARD-STOP at the boundaries in step 1 — production deploys, merges to a protected branch, financial or on-chain spend, outbound mail or public posts, and customer-visible configuration. Escalate rather than guess. The generic stance is work-autonomously, which ships here — an organisation MAY bind a stricter one on top of it. The stance is method and lives at Tier 1; what an organisation adds is the binding: which boundaries its estate treats as real-world, and which of its own skills implement them. Reference a binding by name only, never by path — it resolves on that lane and nowhere else.
5. Keep the operator's page (next section) from the first moment something is theirs.

The operator's page — operator-todo.md

Everything only the human can do goes on one page at the notepad root, operator-todo.md, beside NOTES.md. The agent writes it, the human works it while the loop keeps running, and either of them updates it to unblock the mission. It is how a mission asks for a login, a decision or a merge without stopping every other front.

• At mission start, from the notepad: df-operator-todo init. It is idempotent, and df-mission start runs it too.
• The moment an item is the operator's: df-operator-todo add --id <slug> --category <decision|approval|credential|access|irreversible|attention> --task "<what>" --why "<why it is theirs>" --context "<what this is about and what stays broken, in plain English>" --do "<the exact command, URL or PR>". Add --blocking only when the loop cannot go on without it; the default is that the loop continues. Re-adding an id updates that entry, so a blocker re-found every iteration stays one line.
• When it is done: df-operator-todo done --id <slug> --verified "<evidence>", or --by-operator when the human says so. Never remove an item you did not see done.
• df-operator-todo list prints the page. A finished item is deleted; the notepad's git history keeps it.

• ⛔ BEFORE EVERY MESSAGE TO THE OPERATOR: df-operator-todo publish, then end the message with the link it prints. The markdown page is the source; publish renders it to HTML and updates ONE object in place, so the operator keeps one link and can pin it. The Stop gate runs publish --check and names a page that is older than the queue.

  Operator ruling 2026-10-30: "one engram html accessible via a public link, with all the things you need from me: decisions and actions … Every time you update things and write me a message, you update the same file … If you need something from me, it has to be in this file. If something is done, it has to be removed."

  • ⛔ Never publish a second page. The link must never change, or the pin keeps showing a queue that stopped moving while every report says "updated". publish adopts an existing page by title and then updates by id, so re-running a first publish is safe even after a timeout.
  • ⚠️ The page is PUBLIC where the operator asked for a public link: no secret, no token, nothing that leads to one, and no customer, client or patient data. Full repo URLs and pathnames are the POINT — they are what stops the operator asking "what repo, what app" — but internal hostnames and endpoints stay off it.
  • ⚠️ A page over 25 KB is TRUNCATED by the render route, silently, so publish refuses instead and names the biggest items. Close what is done; do not shorten the context.
  • Per machine, in the Tier-3 record's settings.env (never in Tier 1, which is public and these carry estate ids): DF_ENGRAM_PAGES_NS, DF_ENGRAM_PAGES_URL, and optionally DF_AGENT_ID and DF_OPERATOR_CHANNEL. With them unset, publish --check passes and nothing is gated.
  • What the page is published to, and how a machine is authorised to reach it: Engram.

⚠️ Only actions waiting on the human belong there. An FYI, a status line, a finding, or work you are able to do yourself is not an item: if you cannot name which of the six categories it needs, it was never theirs. A page of things nobody has to act on teaches the reader to skim the ones they do.

The heartbeat tick — how an attended loop survives the orchestrator's attention

The unattended shape has df-supervisor.sh, which is bash and has no context window, so it ticks by itself. The attended shape has no such thing: the orchestrator is a session, and a session that finishes a turn simply stops. Long authorised work then sits, done or not, until somebody happens to look.

So when you are running attended and the work outlives one turn, set a tick — a scheduled prompt that re-enters this loop and asks is there queued work I should be doing? Point it at the mission's own state files, not at a summary you wrote, because the files are the state and the summary decays. End it with an instruction to stop the tick when the queue is empty.

⚠️ CronList — or your harness's equivalent listing — is the ONLY proof a tick is live. Three failure modes, each observed:

• A job id written in a file is not evidence. A tick never survives a session restart, so a file naming one describes a job that may have died hours ago while reading as current.
• Never compose an id. Copy it from the tool that minted it. A plausible-looking id typed from memory produces a record of a tick that never existed — indistinguishable, on the page, from one that did.
• A tick firing over an empty queue is worse than no tick. It manufactures no-change wake-ups, and an operator who sees seven of them learns to ignore the eighth. Delete it the moment its scope is finished, and verify the deletion the same way you verified the creation.

⚠️ A tick is a reminder, not a mechanism. It does not make work happen; it makes you look. If the work itself must survive the session, that is the unattended shape, and the supervisor is the answer.

Re-check a kept promise only when it could have changed

This rule covers every tick, reminder and gate, not only this one. A promise already verified kept is not re-checked until its state could have changed or a minimum interval has passed, whichever you can measure. Re-checking it anyway produces the same answer and costs a full turn. CFEngine puts a lock on every promise for exactly this reason: ifelapsed, "The minimum time (in minutes) which should have passed since the last time that promise was verified. It will not be executed again until this amount of time has elapsed", and the lock is per promise, not global ("These locks do not prevent the whole of cf-agent from running, only atomic promise checks on the same objects", controlling frequency).

• Prefer a state signal to a clock. Did the turn do any work, did the queue file change, did the count on the operator's page move? A reminder keyed to a change fires when it matters; a timer fires on schedule whether or not anything happened.
• Fall back to an interval only when there is no signal. Then choose one on purpose, and never zero: an interval of zero is a re-check on every turn.
• When you write a new gate or tick, state its re-check condition in its first comment. "Fires after every turn" should read as the bug it is.

⚠️ Measured 2026-09-18: a Stop-hook completeness gate re-checked the same promise after every reply, which is effectively an interval of zero. It forced 1,355 extra turns in one day, mostly concluding that nothing had changed. The fix (T1 #201) keys it on a state signal: the gate stays silent after a turn that made no tool calls.

Maturity — be honest about what is wired

• Shipped & usable now (this package): the autonomous loop itself — A/B/C autonomy gate, evidence gating, Promise-Theory sub-agent verification, stage docs + tickets. Runs via dark-factory-build + Workflow, unsigned, on any project today.
• Optional / separate (not in this package): a signed DSSE ledger + hash-chain verify + on-chain anchoring live in an internal provenance substrate (a standalone Go library plus an external blockchain). They are still maturing and are not required to run the loop. Until adopted, provenance rests on Promise-Theory verification + the stage docs/tickets the loop writes.

Running it today — no signing required

You do not need any substrate, keys, blockchain, or external repo to use the loop right now. The default is unsigned mode: run dark-factory-build + the df-* skills and let provenance rest on Promise-Theory verification (df-adversary-gate) plus the stage docs and tickets the loop writes. Signed / on-chain provenance is an optional add-on, supplied separately and still being wired — every stage in this skill works without it.

Related skills

dark-factory-build (the engine) · df-product-owner / df-solution-architect / df-tdd-developer / df-qa / df-adversary-gate / df-dispatch-subagents · critical-thinking / work-autonomously (the operating stance). An organisation may bind a stricter stance, and its own memory-recall skill, on top of these (Tier-2).

See also the repo's HOW-TO-AUTONOMOUS-BUILD.md for the narrative walkthrough.