@wopr-network/defcon 1.13.0 → 1.15.0

package/README.md

@@ -204,6 +204,50 @@ npx defcon run --flow my-pipeline
 
 Same flow. Same gates. Same escalation. The only difference is who's turning the crank — your agent or DEFCON's runner. Either way, the work doesn't advance until the evidence says it should.
 
+## The Deeper Truth: Defcon Is a Prompt Engineering State Machine
+
+The manifesto above tells you why gates matter. Here's the insight that changes how you think about everything else.
+
+Defcon is not an orchestration engine that happens to give prompts to agents. **Defcon is a prompt engineering state machine.** Every state is a prompt. Every transition is a context transformation. Every gate is a deterministic filter that decides what prompt the agent gets next — or whether it gets one at all.
+
+The flow definition is the engineering artifact. Not the agent code. Not the model selection. The flow.
+
+### Context Assembly Is the Contract
+
+An agent invocation is expensive. An agent invocation where the agent spends tool calls reading its own issue, checking CI status, or finding the PR it's supposed to review — that is a flow engineering defect. The onEnter hook should have assembled that context before the agent fired.
+
+**Every tool call an agent makes to gather context is a failure of the flow definition to provide it.**
+
+When the architect calls Linear to read the issue description — that's already in `entity.refs.linear.description`. Put it in the prompt template. When the coder calls `gh pr list` — that's a missing onEnter hook. When the reviewer runs `gh pr checks` — the gate already verified this.
+
+The measure of a well-engineered state is: **can the agent complete its job with zero context-gathering tool calls?** Every tool call should be *work* — writing code, posting comments, running tests — never reconnaissance.
+
+### Gates Are Prompt Qualification
+
+A gate doesn't just verify that work is done. A gate verifies that **the next state's context can be assembled completely**.
+
+`review-bots-ready` waiting for CI and bot comments isn't patience. It ensures the reviewer's prompt will contain: green CI, all bot findings, full diff. Without the gate, the reviewer either polls (burning tokens) or reviews without full information (wrong answer, another loop).
+
+The cost of a gate is milliseconds of shell execution. The cost of a skipped gate is a full review/fix cycle — potentially minutes and dollars.
+
+### The 1:2.8 Ratio Is Physics
+
+For every 1 coder invocation, there are approximately 2.8 reviewer/fixer invocations. This is not a pipeline inefficiency. It is the actual shape of software.
+
+The coder produces a first approximation. Reality pushes back: CI failures, static analysis findings, edge cases the spec didn't anticipate, style violations the linter catches. 70% of the engineering work happens after the code is written. You cannot prompt-engineer your way out of this. You cannot pre-load enough context to get one-shot correctness. The iteration is load-bearing.
+
+The design question is not "how do we reduce the review/fix loop." It is: **given that ~2.8 cycles is the physics, how do we make each cycle as cheap and fast as possible?**
+
+Every gate that catches a problem before an agent runs saves a full cycle. Every onEnter hook that assembles complete context means the agent spends its tokens on reasoning instead of discovery. Every failure prompt that tells the agent exactly what went wrong reduces the chance of another loop.
+
+### Flow Engineering Is 90% of the Work
+
+The promise is big: software that ships with 100% overhead reduction. But 90% of the engineering work to get there is flow engineering — designing states, writing hooks, placing gates, and crafting prompts. The agent is the easy part. The agent is a commodity. The flow is the competitive advantage.
+
+A poorly written failure prompt extends the loop. A gate that fires too early sends an under-qualified prompt to the reviewer. A missing onEnter hook makes the agent reconstruct context with tool calls instead of reasoning. The flow definition IS the quality of the system.
+
+---
+
 ## The Engine
 
 A **flow** is a state machine. Entities enter it and move through states. At each state an agent does work. At each boundary a deterministic gate verifies the output. Transitions fire on signals — not parsed natural language, not regex, but typed strings agents emit via tool call. The entire definition lives in a database and can be mutated at runtime.

package/dist/src/engine/engine.js

@@ -8,6 +8,8 @@ import { buildInvocation } from "./invocation-builder.js";
 import { executeOnEnter } from "./on-enter.js";
 import { executeOnExit } from "./on-exit.js";
 import { findTransition, isTerminal } from "./state-machine.js";
+const MERGE_BLOCKED_THRESHOLD = 3;
+const MERGE_BLOCKED_STUCK_MESSAGE = "PR blocked in merge queue 3+ times — likely branch protection or queue contention issue";
 export class Engine {
     entityRepo;
     flowRepo;
@@ -93,10 +95,31 @@ export class Engine {
             return { gated: true, ...routing, terminal: false };
         }
         // Gate passed or redirected — determine the actual destination.
-        const toState = routing.kind === "redirect" ? routing.toState : transition.toState;
+        let toState = routing.kind === "redirect" ? routing.toState : transition.toState;
         const trigger = routing.kind === "redirect" ? routing.trigger : signal;
         const spawnFlow = routing.kind === "redirect" ? null : transition.spawnFlow;
         const { gatesPassed } = routing;
+        // 4a. Merge-blocked loop detection: if the watcher sends "blocked" from
+        // "merging", increment a counter. After MERGE_BLOCKED_THRESHOLD cycles,
+        // override the destination to "stuck" to break the loop.
+        if (signal === "blocked" && entity.state === "merging") {
+            const prevCount = (typeof entity.artifacts?.merge_blocked_count === "number" ? entity.artifacts.merge_blocked_count : 0);
+            const newCount = prevCount + 1;
+            await this.entityRepo.updateArtifacts(entityId, { merge_blocked_count: newCount });
+            if (newCount >= MERGE_BLOCKED_THRESHOLD) {
+                const stuckState = flow.states.find((s) => s.name === "stuck");
+                if (stuckState) {
+                    toState = "stuck";
+                    await this.entityRepo.updateArtifacts(entityId, {
+                        merge_blocked_message: MERGE_BLOCKED_STUCK_MESSAGE,
+                    });
+                    this.logger.warn(`[engine] Entity ${entityId} merge-blocked ${newCount} times, transitioning to stuck`);
+                }
+                else {
+                    this.logger.warn(`merge_blocked_count >= threshold but no stuck state in flow ${flow.name} — entity ${entityId} will continue looping`);
+                }
+            }
+        }
         // 4b. Execute onExit hook on the DEPARTING state (before transition)
         const departingStateDef = flow.states.find((s) => s.name === entity.state);
         if (departingStateDef?.onExit) {
@@ -145,6 +168,18 @@ export class Engine {
         // 6b. Execute onEnter hook if defined on the new state
         const newStateDef = flow.states.find((s) => s.name === toState);
         if (newStateDef?.onEnter) {
+            // Clear stale onEnter artifact keys so the hook re-runs on state re-entry.
+            // Only the keys belonging to THIS state's onEnter are removed; other artifacts are preserved.
+            const keysToRemove = [...newStateDef.onEnter.artifacts, "onEnter_error"];
+            const currentArtifacts = updated.artifacts ?? {};
+            const hasStaleKeys = keysToRemove.some((k) => currentArtifacts[k] !== undefined);
+            if (hasStaleKeys) {
+                await this.entityRepo.removeArtifactKeys(entityId, keysToRemove);
+                // Refresh in-memory entity so executeOnEnter sees cleared artifacts
+                const refreshed = await this.entityRepo.get(entityId);
+                if (refreshed)
+                    updated = refreshed;
+            }
             const onEnterResult = await executeOnEnter(newStateDef.onEnter, updated, this.entityRepo);
             if (onEnterResult.skipped) {
                 await emitter.emit({

package/dist/src/engine/invocation-builder.js

@@ -46,7 +46,7 @@ export async function buildInvocation(state, entity, adapters, flow, logger = co
     let systemPrompt = "";
     let userContent = "";
     if (state.promptTemplate) {
-        const template = getHandlebars().compile(state.promptTemplate);
+        const template = getHandlebars().compile(state.promptTemplate, { noEscape: true });
         prompt = template(context);
         systemPrompt = `${INJECTION_WARNING}\n\n${prompt}`;
         userContent = `<external-data>\n${JSON.stringify(entityDataForContext(entity), null, 2)}\n</external-data>`;

package/dist/src/execution/cli.js

@@ -474,9 +474,11 @@ program
     sqlite.close();
 });
 // ─── provision-worktree ───
+// TODO(WOP-2014): Remove this subcommand once nuke containers are deployed and stable.
+// Nuke workers provision their own workspace inside the container, making this unnecessary.
 program
     .command("provision-worktree")
-    .description("Provision a git worktree and branch for an issue")
+    .description("[DEPRECATED] Provision a git worktree and branch for an issue (superseded by nuke containers)")
     .argument("<repo>", "GitHub repo (e.g. wopr-network/defcon)")
     .argument("<issue-key>", "Issue key (e.g. WOP-392)")
     .option("--base-path <path>", "Worktree base directory", join(homedir(), "worktrees"))

package/dist/src/execution/provision-worktree.js

@@ -1,3 +1,8 @@
+/**
+ * @deprecated provision-worktree is superseded by nuke containerized workers (WOP-2014).
+ * Nuke containers provision their own workspace inside the container.
+ * TODO: remove this file once nuke is deployed and stable.
+ */
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";

package/dist/src/repositories/drizzle/entity.repo.d.ts

@@ -12,6 +12,7 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
     transition(id: string, toState: string, _trigger: string, artifacts?: Partial<Artifacts>, _invocationId?: string | null): Promise<Entity>;
     updateArtifacts(id: string, artifacts: Partial<Artifacts>): Promise<void>;
+    removeArtifactKeys(id: string, keys: string[]): Promise<void>;
     claim(flowId: string, state: string, agentId: string): Promise<Entity | null>;
     claimById(entityId: string, agentId: string): Promise<Entity | null>;
     release(entityId: string, agentId: string): Promise<void>;

package/dist/src/repositories/drizzle/entity.repo.js

@@ -101,6 +101,19 @@ export class DrizzleEntityRepository {
             .set({ artifacts: { ...existing, ...artifacts }, updatedAt: Date.now() })
             .where(eq(entities.id, id));
     }
+    async removeArtifactKeys(id, keys) {
+        if (keys.length === 0)
+            return;
+        const rows = await this.db.select().from(entities).where(eq(entities.id, id)).limit(1);
+        if (rows.length === 0)
+            throw new NotFoundError(`Entity not found: ${id}`);
+        const existing = rows[0].artifacts ?? {};
+        const cleaned = { ...existing };
+        for (const key of keys) {
+            delete cleaned[key];
+        }
+        await this.db.update(entities).set({ artifacts: cleaned, updatedAt: Date.now() }).where(eq(entities.id, id));
+    }
     async claim(flowId, state, agentId) {
         return this.db.transaction((tx) => {
             const rows = tx

package/dist/src/repositories/event-sourced/entity.repo.d.ts

@@ -11,6 +11,7 @@ export declare class EventSourcedEntityRepository implements IEntityRepository {
     hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
     transition(id: string, toState: string, trigger: string, artifacts?: Partial<Artifacts>): Promise<Entity>;
     updateArtifacts(id: string, artifacts: Partial<Artifacts>): Promise<void>;
+    removeArtifactKeys(id: string, keys: string[]): Promise<void>;
     claim(flowId: string, state: string, agentId: string): Promise<Entity | null>;
     claimById(entityId: string, agentId: string): Promise<Entity | null>;
     release(entityId: string, agentId: string): Promise<void>;

package/dist/src/repositories/event-sourced/entity.repo.js

@@ -48,6 +48,10 @@ export class EventSourcedEntityRepository {
     async updateArtifacts(id, artifacts) {
         return this.mutable.updateArtifacts(id, artifacts);
     }
+    async removeArtifactKeys(id, keys) {
+        await this.mutable.removeArtifactKeys(id, keys);
+        await this.domainEvents.append("entity.artifacts_removed", id, { keys });
+    }
     async claim(flowId, state, agentId) {
         return this.mutable.claim(flowId, state, agentId);
     }

package/dist/src/repositories/event-sourced/replay.js

@@ -59,6 +59,21 @@ export function replayEntity(snapshot, events, entityId) {
                 state.updatedAt = new Date(event.emittedAt);
                 break;
             }
+            case "entity.artifacts_removed": {
+                if (!state)
+                    break;
+                const p = event.payload;
+                const keys = p.keys;
+                if (state.artifacts && Array.isArray(keys)) {
+                    const updated = { ...state.artifacts };
+                    for (const key of keys) {
+                        delete updated[key];
+                    }
+                    state.artifacts = updated;
+                }
+                state.updatedAt = new Date(event.emittedAt);
+                break;
+            }
             // invocation.*, gate.*, onEnter.*, onExit.*, flow.spawned — no entity state mutation
         }
     }

package/dist/src/repositories/interfaces.d.ts

@@ -237,6 +237,8 @@ export interface IEntityRepository {
     /** Merge partial artifacts into an entity's existing artifact bag. Performs a shallow merge
      *  ({ ...existing, ...artifacts }) — only the specified keys are updated; unspecified keys are preserved. */
     updateArtifacts(id: string, artifacts: Partial<Artifacts>): Promise<void>;
+    /** Remove specific keys from an entity's artifact bag. Keys that don't exist are ignored. */
+    removeArtifactKeys(id: string, keys: string[]): Promise<void>;
     /** Atomically claim one unclaimed entity in the given flow+state for the specified agent. Returns null if none available. Uses compare-and-swap (UPDATE WHERE claimedBy IS NULL). */
     claim(flowId: string, state: string, agentId: string): Promise<Entity | null>;
     /** Atomically claim a specific entity by ID for the specified agent. Returns null if already claimed. Uses compare-and-swap (UPDATE WHERE claimedBy IS NULL). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/defcon",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "engines": {