taskforce-loop-engineering 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.15.0 - 2026-08-20
+
+- Reconcile project-scoped human gates against the authoritative project contract and acceptance ledger, superseding stale or optional deferred gates without replay.
+- Strengthen doctor and project status checks for structured gate context, acceptance-ledger drift, execution-ledger reconciliation, and project completion.
+- Make active-task supersession project-aware across active and waiting tasks, and add end-to-end regression coverage for durable gate materialization.
+
+## 0.14.0 - 2026-08-14
+
+- Add the platform-neutral runtime adapter SDK v1 with OpenClaw, Hermes, Codex CLI, and Claude Code factories, shared conformance tests, fail-closed effects, redacted telemetry, migration guidance, and a credential-free demo.
+
 ## 0.13.0 - 2026-08-14
 
 - Add versioned OpenClaw, Hermes, and custom runtime adapter contracts with a shared conformance suite.

package/README.md

@@ -1,5 +1,15 @@
 # Taskforce Loop Engineering
 
+[![production trust](https://github.com/ambitioncn/taskforce-loop-engineering/actions/workflows/production-trust.yml/badge.svg)](https://github.com/ambitioncn/taskforce-loop-engineering/actions/workflows/production-trust.yml)
+
+## Platform-neutral adapter SDK
+
+OpenClaw, Hermes, Codex CLI, and Claude Code share the versioned runtime
+contract in `lib/runtime-adapter-sdk.mjs`. Start without credentials or network
+access with `npm run demo:adapter`, then verify every runtime using
+`npm run check:adapters`. See [docs/runtime-adapter-sdk.md](docs/runtime-adapter-sdk.md)
+for the contract, compatibility matrix, migration, and extension guide.
+
 ## 0.13 production trust
 
 The local production-trust contract, runtime adapter v1, durable journal,
@@ -7,7 +17,11 @@ multi-worker canary, non-destructive Ironman upgrade planner, safe demo and
 unified acceptance are documented in
 [docs/production-trust-contract.md](docs/production-trust-contract.md). Run
 `npm run check:production-trust`; external publishing and deployment remain
-separately authorized actions.
+separately authorized actions. The command writes integrity-sealed evidence and
+a redacted public summary to `.production-evidence/`. The default canary is
+offline and fixture-only: it performs no model call or external side effect.
+Copy `templates/github-production-trust.yml` into `.github/workflows/` only
+when publication is separately approved.
 
 ## Read-only operator dashboard (P3)
 

package/docs/adapter-sdk-terminal-contract.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "project": "P2 platform-neutral runtime adapter SDK",
+  "terminal_acceptance": [
+    "versioned platform-neutral contract",
+    "OpenClaw Hermes Codex CLI and Claude Code reproducible paths",
+    "unified capability session run step effect gate continuation telemetry and errors",
+    "compatibility matrix conformance migration and extension docs",
+    "credential-free demo and read-only dashboard path",
+    "redaction fail-closed 0.13 P0 P1 regression package and clean-install evidence"
+  ],
+  "backlog": [
+    {"id":"P2-1","status":"done","evidence":"lib/runtime-adapter-sdk.mjs"},
+    {"id":"P2-2","status":"done","evidence":"scripts/runtime-adapter-conformance.mjs"},
+    {"id":"P2-3","status":"done","evidence":"docs/runtime-adapter-sdk.md"},
+    {"id":"P2-4","status":"done","evidence":"examples/adapter-sdk-demo.mjs"},
+    {"id":"P2-5","status":"done","evidence":"npm run check; npm pack --pack-destination; clean npm install and packaged conformance"}
+  ]
+}

package/docs/production-trust-backlog.json

@@ -1,13 +1,18 @@
 {
-  "version": 1,
-  "project": "0.13-production-trust",
+  "version": 3,
+  "project": "p1-production-trust-evidence",
   "terminal_contract": "production-trust-contract.md",
+  "milestone_completion_is_project_completion": false,
   "items": [
-    {"id":"PT-1","outcome":"versioned runtime adapter contract","evidence":["lib/runtime-adapter-v1.mjs","scripts/runtime-adapter-contract-self-test.mjs"],"required":true},
-    {"id":"PT-2","outcome":"durable journal, replay, migration, backup/restore","evidence":["lib/durable-journal.mjs","scripts/durable-journal-self-test.mjs"],"required":true},
-    {"id":"PT-3","outcome":"multi-agent soak/canary report","evidence":["scripts/production-soak.mjs"],"required":true},
-    {"id":"PT-4","outcome":"non-destructive customized-layout upgrade plan","evidence":["lib/upgrade-planner.mjs","scripts/upgrade-planner-self-test.mjs"],"required":true},
-    {"id":"PT-5","outcome":"safe public demo and operations guide","evidence":["examples/safe-canary.mjs","docs/production-operations.md"],"required":true},
-    {"id":"PT-6","outcome":"unified local release acceptance","evidence":["scripts/production-acceptance.mjs"],"required":true}
+    {"id":"P1-1","outcome":"schema-versioned evidence, public summary, integrity and redaction","evidence":["lib/production-evidence.mjs","templates/production-evidence.schema.json","scripts/production-evidence-self-test.mjs"],"required":true},
+    {"id":"P1-2","outcome":"ledger-backed multi-agent soak and kill/restart chaos","evidence":["scripts/production-soak.mjs","lib/execution-ledger.mjs"],"required":true},
+    {"id":"P1-3","outcome":"claim lease handoff parked gate and stale-fence rejection","evidence":["scripts/production-soak.mjs",".production-evidence/evidence.json"],"required":true},
+    {"id":"P1-4","outcome":"unknown outcome crash boundaries and accepted-before-settle reconciliation","evidence":["scripts/production-soak.mjs","lib/execution-ledger.mjs"],"required":true},
+    {"id":"P1-5","outcome":"step replay resume divergence and zero duplicate effects","evidence":["scripts/production-soak.mjs","scripts/execution-ledger-self-test.mjs"],"required":true},
+    {"id":"P1-6","outcome":"baseline trend threshold attribution recovery cost and error metrics","evidence":["lib/production-evidence.mjs","scripts/production-evidence-self-test.mjs"],"required":true},
+    {"id":"P1-7","outcome":"OpenClaw Hermes and custom adapter compatibility matrix","evidence":["lib/runtime-adapter-v1.mjs","scripts/production-soak.mjs"],"required":true},
+    {"id":"P1-8","outcome":"GitHub CI candidate badge doctor and dashboard projection","evidence":["templates/github-production-trust.yml","README.md","lib/core.mjs","lib/operator-dashboard.mjs"],"required":true},
+    {"id":"P1-9","outcome":"offline determinism privacy and tamper negative tests","evidence":["scripts/production-evidence-self-test.mjs","scripts/production-soak.mjs"],"required":true},
+    {"id":"P1-10","outcome":"full regression package content and clean-install acceptance","evidence":["package.json","scripts/production-acceptance.mjs"],"required":true}
   ]
 }

package/docs/production-trust-contract.md

@@ -1,54 +1,53 @@
-# Production Trust Contract (0.13)
-
-Status: local release candidate. This contract is terminal only when every
-required item in `production-trust-backlog.json` is accepted by recorded local
-evidence. Publishing and production deployment are deliberately outside it.
-
-## Required outcomes
-
-1. Runtime adapters implement contract v1 and pass the same conformance suite.
-   OpenClaw and Hermes are supported integrations; the custom adapter is the
-   reference extension point.
-2. State mutations use a checksummed append-only journal with atomic snapshot
-   checkpoints, replay, migration from version-1 JSON state, backup and restore.
-   A committed external P1 side effect is never inferred from local intent:
-   ambiguous attempts remain `unknown` until reconciled with upstream evidence.
-3. The deterministic multi-worker canary covers heartbeat, claim, lease expiry,
-   fenced handoff, crash/restart replay, concurrent claims, quota, parked gates,
-   and unknown-outcome reconciliation and emits an auditable JSON report.
-4. Upgrade planning detects unmanaged or locally modified Ironman layouts and
-   produces a non-destructive plan. Customized dispatcher/config files are
-   preserved; application requires a separate explicit confirmation and has a
-   backup-based rollback plan.
-5. The public demo is credential-free, loopback/local-only, makes no paid call
-   or external write, and labels support boundaries.
-6. Release acceptance includes threat model, reliability/performance thresholds,
-   full regression, package dry-run, and clean-install verification.
-
-## Release thresholds
-
-- Adapter conformance: all three fixtures pass; incompatible major versions fail.
-- Journal: torn tail is ignored, checksum corruption fails closed, snapshot and
-  replay agree, backup restore agrees, migration is idempotent.
-- Canary: all scenarios pass, duplicate settled side effects = 0, stale fencing
-  tokens accepted = 0, unreconciled unknown outcomes = 0.
-- Regression: `npm run check` and `npm run check:production-trust` pass.
-- Packaging: `npm pack --dry-run` contains all contract, runtime and demo assets.
-
-## Threat model and trust boundaries
-
-Untrusted inputs include adapter responses, task JSON, journal tails, installer
-layouts, and human-gate text. Controls are schema validation, bounded strings,
-checksums, atomic rename, fencing tokens, canonical idempotency keys, path
-containment, fail-closed version negotiation, and explicit confirmation gates.
-The package does not claim Byzantine-worker protection, distributed consensus,
-or exactly-once behavior from an upstream service lacking idempotency/reconcile
-APIs. Host compromise, stolen credentials, and malicious runtime binaries remain
-operator responsibilities.
-
-## Support levels
-
-- OpenClaw: supported, contract-tested adapter and managed installer.
-- Hermes: supported, contract-tested adapter and managed installer.
-- Custom runtime: contract/example support; lifecycle is operator-owned.
-- Distributed database/HA: not provided by the local journal backend.
+# P1 Production-Trust Evidence Terminal Contract
+
+Status: local release candidate. Project completion requires every required P1
+backlog item to have repeatable evidence; a scenario or milestone alone is not
+project completion. Push, publication, deployment, production credentials,
+real paid calls, production process control, and external effects are excluded.
+
+## Terminal outcome
+
+P1 turns the P0 schema-v2 execution ledger and effect protocol into a sustainable
+production-trust evidence system. CI/canary runs emit schema-versioned,
+integrity-sealed evidence plus a secret-redacted public summary. Baselines,
+trends, explicit thresholds, failure attribution, runtime compatibility, cost,
+error rate, and recovery time remain independently reviewable.
+
+## Required acceptance
+
+1. The deterministic multi-agent canary exercises long soak, exclusive claim,
+   lease expiry, kill/restart handoff, stale fencing, parked gate, crash before
+   and after submit, accepted-before-local-settle, reconciliation, checkpoint
+   resume, reusable replay, and replay divergence through the P0 ledger/effect
+   protocol. It does not maintain a second execution state store.
+2. Duplicate settled effects and accepted stale fences are exactly zero;
+   unreconciled unknown outcomes are zero at terminal acceptance. Recovery time,
+   error rate, model calls, and paid-call cost meet recorded thresholds.
+3. OpenClaw, Hermes, and custom runtime-adapter fixtures pass contract v1 using
+   simulated I/O. The boundary is explicit: fixtures prove adapter compatibility,
+   not availability of a real gateway or provider.
+4. Evidence schema v1 supports baselines and metric deltas, threshold failures
+   with attribution, SHA-256 tamper detection, credential-shaped field redaction,
+   and a minimized public summary. Offline reruns require no network or secret.
+5. GitHub CI template/artifact upload and badge markup are release candidates;
+   no workflow is published in this local task. Doctor and dashboard project the
+   latest evidence state without mutating it.
+6. Full regression, package dry-run, package content inspection, and clean local
+   install pass. The packaged candidate includes schema, CI template, library,
+   canary, tests, docs, and backlog.
+
+## Real/simulated boundary and deferred canary
+
+`production-soak.mjs` is the authoritative offline CI canary. The separate
+`live-runtime-soak.mjs` may perform runtime probes and is not invoked by release
+acceptance. A real long-duration OpenClaw/Hermes run, production credentials,
+paid inference, or external side effect needs a separate human authorization and
+must produce a successor evidence artifact clearly labeled `real_runtime`.
+
+## Trust limits
+
+SHA-256 detects later artifact changes but is not an external timestamp or
+signature. Local filesystem leases provide single-host coordination, not
+distributed consensus or Byzantine-worker protection. Exactly-once effects still
+depend on an upstream idempotency/reconciliation API. Unknown outcomes lacking
+authoritative evidence fail closed and remain reconciliation debt.

package/docs/runtime-adapter-sdk.md

@@ -0,0 +1,50 @@
+# Runtime Adapter SDK v1
+
+`lib/runtime-adapter-sdk.mjs` is the platform-neutral contract. Contract id is
+`loop.runtime-adapter`, semantic version `1.0.0`; consumers must reject unknown
+major versions. The SDK normalizes capabilities, session/run identity, step
+ledger events, authorized effects, human gates, heartbeat/continuation,
+redacted evidence/telemetry, and stable `AdapterError` codes.
+
+## Ten-minute, credential-free path
+
+From this package, run `npm run demo:adapter`, `npm run check:adapters`, then
+`npm run check`. All four paths use the same in-memory transport and make no
+network calls. The existing dashboard remains a read-only projection; the demo
+prints the command for opening it against a local workspace.
+
+## Runtime paths
+
+| Runtime | Factory | Integration transport |
+| --- | --- | --- |
+| OpenClaw | `createOpenClawAdapter` | map invoke to trusted session/task tools |
+| Hermes | `createHermesAdapter` | map invoke to Hermes run lifecycle |
+| Codex CLI | `createCodexCliAdapter` | map invoke to local Codex exec/resume |
+| Claude Code | `createClaudeCodeAdapter` | map invoke to local Claude session/resume |
+
+Each transport implements `invoke(operation, payload)`. Operations are
+`run.start`, `run.heartbeat`, and `run.continue`. Side effects never pass through
+that generic transport: call `prepareEffect` first, persist its idempotency key
+in the P0/P1 ledger, obtain explicit authorization, then submit through the
+product-specific effect adapter. Missing authorization fails closed.
+
+## Compatibility and migration
+
+| Surface | Status |
+| --- | --- |
+| package 0.13 / P0 / P1 ledgers | compatible; unchanged |
+| `runtime-adapter-v1.mjs` OpenClaw/Hermes/custom fixtures | retained |
+| SDK v1 four-runtime contract | additive and preferred |
+| future SDK major | rejected until explicitly supported |
+
+Migrate by replacing fixture imports with a `create*Adapter(transport)` factory,
+creating a session then run, recording every step, and routing effects through
+`prepareEffect`. Convert caught errors using `AdapterError.toJSON()`; never log
+raw credentials. To extend, add a runtime to `RUNTIMES`, a thin factory, and run
+the exported conformance function with an offline transport before connecting a
+real runtime.
+
+Error codes are `INVALID_INPUT`, `UNSUPPORTED_CONTRACT`,
+`UNSUPPORTED_VERSION`, `UNSUPPORTED_RUNTIME`, `INVALID_ADAPTER`,
+`INVALID_STEP_STATE`, `EFFECT_KEY_REQUIRED`, `EFFECT_NOT_AUTHORIZED`,
+`INVALID_GATE_DECISION`, and retryable `TRANSPORT_FAILURE`.

package/examples/adapter-sdk-demo.mjs

@@ -0,0 +1,9 @@
+import { createMemoryTransport, createOpenClawAdapter } from '../lib/runtime-adapter-sdk.mjs';
+
+const adapter = createOpenClawAdapter(createMemoryTransport());
+const session = await adapter.createSession({ key: 'ten-minute-demo' });
+const run = await adapter.startRun({ sessionId: session.sessionId, requestId: 'demo', input: { prompt: 'credential-free' } });
+await adapter.recordStep({ runId: run.runId, stepId: 'hello', evidence: [{ kind: 'local-demo' }] });
+const heartbeat = await adapter.heartbeat({ runId: run.runId });
+await adapter.continueRun({ runId: run.runId, continuationToken: heartbeat.continuationToken });
+console.log(JSON.stringify({ session, run, heartbeat, dashboard: 'run `loop-engineering dashboard --root .` for the existing read-only projection', telemetry: adapter.telemetry }, null, 2));

package/examples/code-worktree-queue.json

@@ -0,0 +1,35 @@
+{
+  "queue": "code-tasks",
+  "description": "L2 assisted code task queue. Each task runs in an isolated git worktree and records verification plus diff summaries. It never pushes, merges, or deletes worktrees.",
+  "dispatcher": "node scripts/dispatch-code-task.mjs",
+  "preflightConfig": "configs/loops/workspace-health.json",
+  "timeoutMs": 1800000,
+  "leaseMs": 1860000,
+  "staleActiveMs": 3600000,
+  "retry": {
+    "maxAttempts": 1,
+    "retryDelayMs": 0,
+    "retryExitCodes": [
+      1
+    ],
+    "requiresHumanActionPatterns": [
+      "INSTALL_FAILED_USER_RESTRICTED",
+      "device unauthorized",
+      "no devices/emulators found",
+      "Permission denied",
+      "Operation not permitted",
+      "requires human",
+      "需要人工",
+      "权限未开"
+    ]
+  },
+  "worktree": {
+    "enabled": true,
+    "baseDir": "runtime/loops/code-tasks/worktrees",
+    "branchPrefix": "loop/code-tasks",
+    "verifyCommands": [
+      "npm test"
+    ],
+    "keepOnSuccess": true
+  }
+}

package/examples/queue-runner.json

@@ -0,0 +1,37 @@
+{
+  "queue": "agent-tasks",
+  "description": "Generic queue runner config. Keep dispatcher local to the target workspace.",
+  "dispatcher": "node scripts/dispatch-task.mjs",
+  "preflightConfig": "configs/loops/workspace-health.json",
+  "timeoutMs": 1800000,
+  "leaseMs": 1860000,
+  "staleActiveMs": 3600000,
+  "scheduler": {
+    "initialInterval": "10m",
+    "minInterval": "1m",
+    "maxInterval": "4h",
+    "speedupFactor": 0.5,
+    "backoffFactor": 2,
+    "idleBackoffFactor": 2,
+    "humanGateBackoffFactor": 3,
+    "longRunHeadroomFactor": 1.25,
+    "jitter": "30s"
+  },
+  "retry": {
+    "maxAttempts": 1,
+    "retryDelayMs": 0,
+    "retryExitCodes": [
+      1
+    ],
+    "requiresHumanActionPatterns": [
+      "INSTALL_FAILED_USER_RESTRICTED",
+      "device unauthorized",
+      "no devices/emulators found",
+      "Permission denied",
+      "Operation not permitted",
+      "requires human",
+      "需要人工",
+      "权限未开"
+    ]
+  }
+}

package/examples/safe-canary.mjs

@@ -0,0 +1,5 @@
+import { customAdapterExample } from '../lib/runtime-adapter-v1.mjs';
+const audit = [];
+const io = { invoke: async (binary, args) => (audit.push({ binary, args, externalWrite: false, paid: false }), { accepted: true }), now: () => new Date().toISOString(), lookup: async () => ({ status: 'not_accepted' }) };
+await customAdapterExample.dispatch({ prompt: 'credential-free local canary', worker: 'demo' }, io);
+console.log(JSON.stringify({ support: 'example-contract-only', credentialsUsed: false, externalWrites: false, paidCalls: false, audit }, null, 2));

package/examples/workspace-health.json

@@ -0,0 +1,35 @@
+{
+  "id": "workspace-health",
+  "goal": "Keep this workspace loop-ready and detect obvious drift.",
+  "level": "L1",
+  "mode": "report-only",
+  "maxRuntimeMs": 120000,
+  "description": "A safe first loop: local read-only checks plus durable run ledger.",
+  "humanGates": [
+    "source edits",
+    "external messages",
+    "destructive commands",
+    "production config changes"
+  ],
+  "breaker": {
+    "maxConsecutiveFailures": 3,
+    "sameFailureThreshold": 2
+  },
+  "checks": [
+    {
+      "id": "git-status",
+      "type": "command",
+      "cmd": "git status --short",
+      "expectExitCode": 0,
+      "timeoutMs": 10000,
+      "allowNonEmptyOutput": true
+    },
+    {
+      "id": "loop-config-dir",
+      "type": "files",
+      "paths": [
+        "configs/loops"
+      ]
+    }
+  ]
+}

package/lib/action-reservations.mjs

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
+import { migrateActionReservation } from './execution-ledger.mjs';
 
 const ACTION_KINDS = new Set(['paid_api', 'notification', 'deployment', 'process_control', 'publication', 'external_message', 'gated_mutation']);
 const TERMINAL_STATES = new Set(['settled', 'released']);
@@ -194,3 +195,9 @@ export async function migrateLegacyActionArtifact(root, legacy) {
   const scope = legacy.authorization_scope ?? legacy.authorization?.scope ?? 'legacy:unscoped';
   return reserveAction(root, { idempotencyKey: key, kind: legacy.kind ?? 'gated_mutation', request, authorizationScope: scope });
 }
+
+export async function projectActionToEffectProtocol(root, idempotencyKey) {
+  const reservation = await inspectAction(root, idempotencyKey);
+  if (!reservation) throw new Error('Action reservation not found.');
+  return migrateActionReservation(root, reservation);
+}