owenloop 0.4.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +58 -31
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{cli.d.ts → src/cli.d.ts} +18 -3
- package/dist/{cli.js → src/cli.js} +770 -114
- package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
- package/dist/{credentials.js → src/credentials.js} +14 -12
- package/dist/{defs.js → src/defs.js} +36 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +14 -14
- package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
- package/dist/{hub.js → src/hub.js} +370 -12
- package/dist/{index.d.ts → src/index.d.ts} +1 -1
- package/dist/{index.js → src/index.js} +1 -1
- package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
- package/dist/{mcp → src/mcp}/serve.js +168 -31
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +6 -9
- package/dist/{model.js → src/model.js} +1 -1
- package/dist/{types.d.ts → src/types.d.ts} +18 -18
- package/dist/{util.d.ts → src/util.d.ts} +3 -2
- package/dist/{util.js → src/util.js} +3 -2
- package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
- package/dist/{owenwork.js → src/work-settings.js} +27 -27
- package/docs/authoring.md +93 -53
- package/docs/cli.md +597 -76
- package/docs/design.md +33 -33
- package/docs/embedding.md +10 -9
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- /package/dist/{add.d.ts → src/add.d.ts} +0 -0
- /package/dist/{add.js → src/add.js} +0 -0
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{lock.d.ts → src/lock.d.ts} +0 -0
- /package/dist/{lock.js → src/lock.js} +0 -0
- /package/dist/{model.d.ts → src/model.d.ts} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /package/dist/{untar.js → src/untar.js} +0 -0
package/docs/design.md
CHANGED
|
@@ -663,7 +663,7 @@ The `M2B-REARM` branch (§23.6.1 step 7 — child un-greened while parent stays
|
|
|
663
663
|
- **Aggregation.** Child orders are concatenated onto the parent's; `reaped` sums; `dueAt` takes the minimum across the tree so the caller's next-wake is the earliest across all levels. Each folded `DeferredFiring` carries a `workflow` field naming the instance it belongs to — **absent means the ticked root, present means a descendant** — so a caller can still tell which instance a deferral came from. The single `now` is threaded through the whole descent, so a reap TTL that trips at the parent's clock trips consistently for children in the same sweep.
|
|
664
664
|
- **Opt-out.** `tick(parentWf, { deep: false })` (CLI `--shallow`) ticks only that one instance — no descent, orders all carry the root's `workflow`. Use it to drive a single instance deliberately (tests, targeted retries); the default deep tick is what production drivers want.
|
|
665
665
|
|
|
666
|
-
**Status child-summary.** `status(parentWf)` enriches each `calls:`-debt entry with a `child: ChildStatusSummary` (`{ workflow, def, done, stalled, debts }`) when a child has been spawned for that step. `stalled` is true when the child (or, recursively, a grandchild on an unpaid `calls:` path) has any stalled debt — a worker that hit `maxAttempts` with no green outcome. This lets a
|
|
666
|
+
**Status child-summary.** `status(parentWf)` enriches each `calls:`-debt entry with a `child: ChildStatusSummary` (`{ workflow, def, done, stalled, debts }`) when a child has been spawned for that step. `stalled` is true when the child (or, recursively, a grandchild on an unpaid `calls:` path) has any stalled debt — a worker that hit `maxAttempts` with no green outcome. This lets a Shift see, from the parent alone, that a `calls:` debt is blocked on a stuck child without separately walking into the child's own `status`. Like `failedRuns`/`attempts`, the field is engine-populated cross-instance state; `model.ts`'s pure single-instance `workflowStatus` never sets it.
|
|
667
667
|
|
|
668
668
|
**Discovering children directly.** A driver can still enumerate children itself — `store.listChildrenByParent`/`findChildByParent` give the reverse index from a parent id — and a propagated reject remains visible via the CHILD's own `status(childWf).debts` (the rejected outcome artifact appears there with `acceptance: 'rejected'`). But with deep tick as the default, a driver that sweeps only roots already reaches all live descendants; explicit child enumeration is for inspection and for the `--shallow` single-instance path, not a requirement for liveness.
|
|
669
669
|
|
|
@@ -875,7 +875,7 @@ steps:
|
|
|
875
875
|
```
|
|
876
876
|
|
|
877
877
|
- `name:` — required; keys the sign-off ledger and the audit trail.
|
|
878
|
-
- `body:` / `bodyFile:` — the judge
|
|
878
|
+
- `body:` / `bodyFile:` — the judge Step Agent's prompt (exactly one required,
|
|
879
879
|
mutually exclusive, same rule as step bodies). `bodyFile` is resolved
|
|
880
880
|
against the workflow's base directory and read eagerly at def-load.
|
|
881
881
|
- `model:` — optional model override for that judge's order. Opaque to the
|
|
@@ -919,12 +919,12 @@ left as a known, accepted limitation — see the doc comment on `reject()` in
|
|
|
919
919
|
`src/engine.ts`.
|
|
920
920
|
|
|
921
921
|
**Mitigations, for operators running judges with slow or expensive verdict
|
|
922
|
-
|
|
922
|
+
Step Agents:**
|
|
923
923
|
|
|
924
924
|
- Keep `judges: <judgedStem>` steps at `parallel: 1` (the default) so there
|
|
925
925
|
is only ever one live run of a given judge step at a time. This alone
|
|
926
926
|
removes the "two different runs" precondition for the race.
|
|
927
|
-
- Set a generous `reapTtl:` on judge steps whose verdict
|
|
927
|
+
- Set a generous `reapTtl:` on judge steps whose verdict Step Agent is slow —
|
|
928
928
|
reaping is what creates the zombie in the first place (§24.5); a judge
|
|
929
929
|
that is legitimately still working should not be reaped out from under
|
|
930
930
|
itself. A TTL sized to the judge's real worst-case latency, rather than
|
|
@@ -1317,39 +1317,39 @@ prefixing untouched (there are no stems inside `x:` to rewrite — it's
|
|
|
1317
1317
|
opaque); a child definition's own top-level `x:` stays on the child def and
|
|
1318
1318
|
is not merged into the parent's.
|
|
1319
1319
|
|
|
1320
|
-
### §27.4 `
|
|
1320
|
+
### §27.4 `executor:`/`command:`/`spec:` — declaring the executor
|
|
1321
1321
|
|
|
1322
1322
|
`x:` (§27.3) is a namespaced escape hatch for arbitrary external vocabulary.
|
|
1323
|
-
`
|
|
1323
|
+
`executor:` is a narrower, purpose-built field for one specific job: telling
|
|
1324
1324
|
whatever dispatches orders *which kind* of executor a step's order is for. It
|
|
1325
1325
|
follows the same opaque-passthrough contract as `model` — the engine never
|
|
1326
1326
|
interprets it, only carries it — but unlike `model` (a free-form quality
|
|
1327
|
-
hint) and unlike `x:` (fully unvalidated contents), `
|
|
1328
|
-
hard-coded shape rules, because the two most common
|
|
1327
|
+
hint) and unlike `x:` (fully unvalidated contents), `executor:` gets two narrow,
|
|
1328
|
+
hard-coded shape rules, because the two most common executor types have a
|
|
1329
1329
|
structural precondition the engine can cheaply catch at load time instead of
|
|
1330
1330
|
letting it surface as a confusing runtime stall.
|
|
1331
1331
|
|
|
1332
1332
|
**The contract, four clauses:**
|
|
1333
1333
|
|
|
1334
1334
|
1. **Default is `'agent'`, and that default is silent.** A step (or judge)
|
|
1335
|
-
that omits `
|
|
1336
|
-
feature existed — every def in this repo predating `
|
|
1335
|
+
that omits `executor:` entirely behaves exactly as it did before this
|
|
1336
|
+
feature existed — every def in this repo predating `executor:` is
|
|
1337
1337
|
unaffected, byte for byte. The default is applied at validation and
|
|
1338
1338
|
engine-order-building time, never written back into the parsed def.
|
|
1339
|
-
2. **`
|
|
1340
|
-
effective
|
|
1341
|
-
`DefError`: `` step '<name>' has
|
|
1342
|
-
other
|
|
1343
|
-
validated when the
|
|
1344
|
-
3. **`
|
|
1345
|
-
deliberately scoped to an *explicit* `
|
|
1346
|
-
value — i.e. `validateDef` checks `l.
|
|
1347
|
-
`(l.
|
|
1339
|
+
2. **`executor: command` requires `command:`.** A step (or judge) whose
|
|
1340
|
+
effective executor is `'command'` and carries no `command:` is a load-time
|
|
1341
|
+
`DefError`: `` step '<name>' has executor 'command' but no command: ``. Any
|
|
1342
|
+
other executor string has no such requirement — `command:` is only ever
|
|
1343
|
+
validated when the executor is literally `'command'`.
|
|
1344
|
+
3. **`executor: agent` (explicit) requires a non-empty `body:`.** This check is
|
|
1345
|
+
deliberately scoped to an *explicit* `executor: agent`, not the *defaulted*
|
|
1346
|
+
value — i.e. `validateDef` checks `l.executor === 'agent'`, never
|
|
1347
|
+
`(l.executor ?? 'agent') === 'agent'`. That distinction matters: plenty of
|
|
1348
1348
|
existing fixtures and generator-only steps rely on `buildStep`'s
|
|
1349
|
-
empty-body default and never write `
|
|
1349
|
+
empty-body default and never write `executor:` at all. Checking the
|
|
1350
1350
|
defaulted value would retroactively break every one of them. Checking
|
|
1351
1351
|
only the explicit form catches the actual mistake this rule exists for —
|
|
1352
|
-
someone opts into `
|
|
1352
|
+
someone opts into `executor: agent` on purpose and forgets the prompt —
|
|
1353
1353
|
without touching a single pre-existing def.
|
|
1354
1354
|
4. **`command:` and `spec:` are otherwise opaque.** `command` is
|
|
1355
1355
|
shape-checked as a string (`asString`); `spec` is shape-checked as a plain
|
|
@@ -1361,37 +1361,37 @@ letting it surface as a confusing runtime stall.
|
|
|
1361
1361
|
contents" philosophy as `x:`, just scoped to one step instead of the
|
|
1362
1362
|
whole def.
|
|
1363
1363
|
|
|
1364
|
-
**The optional `
|
|
1364
|
+
**The optional `executors:` allow-list.** A definition can declare `executors:
|
|
1365
1365
|
[agent, command, …]` at the top level — a typo guard, nothing more. When
|
|
1366
|
-
present, `validateDef` rejects any step or judge whose *effective*
|
|
1366
|
+
present, `validateDef` rejects any step or judge whose *effective* executor
|
|
1367
1367
|
(after the `?? 'agent'` default is applied) isn't in the list. This runs
|
|
1368
|
-
**after** the default, deliberately: a def that declares `
|
|
1369
|
-
(excluding `'agent'` on purpose) still fails a step that omits `
|
|
1370
|
-
entirely, because that step's effective
|
|
1368
|
+
**after** the default, deliberately: a def that declares `executors: [command]`
|
|
1369
|
+
(excluding `'agent'` on purpose) still fails a step that omits `executor:`
|
|
1370
|
+
entirely, because that step's effective executor is `'agent'` and `'agent'`
|
|
1371
1371
|
isn't in the list. This is the intended behavior — once a def opts into the
|
|
1372
1372
|
allow-list, it's exhaustive, and a step relying on the silent default doesn't
|
|
1373
|
-
get a free pass around it. A def with no `
|
|
1374
|
-
string; there is no engine-wide registry of valid
|
|
1373
|
+
get a free pass around it. A def with no `executors:` key accepts any executor
|
|
1374
|
+
string; there is no engine-wide registry of valid executor types to check
|
|
1375
1375
|
against.
|
|
1376
1376
|
|
|
1377
|
-
**Pass-through.** `
|
|
1378
|
-
the emitted `Order` untouched — `Order.
|
|
1377
|
+
**Pass-through.** `executor`, `command`, and `spec` all ride `buildOrder` onto
|
|
1378
|
+
the emitted `Order` untouched — `Order.executor`, `Order.command`, `Order.spec`
|
|
1379
1379
|
— the same pass-through contract as `Order.model` and `Order.x`. A step that
|
|
1380
1380
|
never sets them emits an order with all three fields absent, identical to
|
|
1381
1381
|
before this feature existed.
|
|
1382
1382
|
|
|
1383
1383
|
**Judges get the same fields, for free.** §24's `synthesizeJudgeSteps` turns
|
|
1384
1384
|
each `judges:` entry into an ordinary `StepDef` — so a judge entry accepting
|
|
1385
|
-
`
|
|
1385
|
+
`executor:`/`command:`/`spec:` and having the exact same `validateDef` rules
|
|
1386
1386
|
apply to it isn't a separate code path, it's the same rules running against
|
|
1387
1387
|
an already-existing synthesized step. A judge can therefore be a
|
|
1388
1388
|
deterministic check (a script's exit code) instead of an LLM verdict, without
|
|
1389
1389
|
any new validation logic. Note the pre-existing, orthogonal judge
|
|
1390
1390
|
requirement — every judge needs `body:` or `bodyFile:` regardless of
|
|
1391
|
-
`
|
|
1391
|
+
`executor:` — still applies; a `executor: command` judge still declares a
|
|
1392
1392
|
`body:`, it's simply unread by a non-agent dispatcher.
|
|
1393
1393
|
|
|
1394
|
-
**Scope notes**, mirroring §27.3's: `
|
|
1394
|
+
**Scope notes**, mirroring §27.3's: `executor`/`command`/`spec` are additive
|
|
1395
1395
|
and inert — a definition that never sets any of the three is unchanged in
|
|
1396
1396
|
behavior and in `hashDef` terms. They live on the same two authored,
|
|
1397
1397
|
engine-fired shapes as `x:` (a normal step, and — new here — a judge entry),
|
package/docs/embedding.md
CHANGED
|
@@ -6,8 +6,9 @@ on an `Engine` and prints the results as JSON. Everything it does, a host
|
|
|
6
6
|
process can do **in-process** — and get the lifecycle back as typed objects
|
|
7
7
|
rather than JSON on stdout.
|
|
8
8
|
|
|
9
|
-
This document covers the in-process API: the one-call factory, the worker step
|
|
10
|
-
|
|
9
|
+
This document covers the in-process API: the one-call factory, the worker step
|
|
10
|
+
(the loop a Step Agent — or your own host code — runs), in-memory definitions,
|
|
11
|
+
lifecycle/concurrency, and **push-style events** so a host
|
|
11
12
|
can react the instant the graph advances instead of polling.
|
|
12
13
|
|
|
13
14
|
## The one-call factory
|
|
@@ -83,7 +84,7 @@ const status = engine.status(wf); // { done, debts, eligible, blocked, inFligh
|
|
|
83
84
|
Each `order` is self-contained: `workflow` (the instance it belongs to — see
|
|
84
85
|
deep tick below), `prompt`, `consumes` (the captured green inputs), `owes` (the
|
|
85
86
|
owed outputs + their accumulated reason threads), plus
|
|
86
|
-
`inputs`/`outputs`/`model`/`
|
|
87
|
+
`inputs`/`outputs`/`model`/`executor`/`command`/`spec`. A consumer rejecting an
|
|
87
88
|
upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
|
|
88
89
|
cascade and stall liveness behave exactly as they do under the CLI, because
|
|
89
90
|
it's the same engine.
|
|
@@ -110,28 +111,28 @@ one `TickResult` belongs to the instance you ticked; each order carries its own
|
|
|
110
111
|
(CLI `--shallow`) stays the deliberate single-instance escape hatch when you
|
|
111
112
|
want exactly the old behavior.
|
|
112
113
|
|
|
113
|
-
`order.
|
|
114
|
+
`order.executor` is where dispatch-by-executor-type earns its keep in an
|
|
114
115
|
embedder: rather than every order going to the same LLM-driving `runYourWorker`,
|
|
115
116
|
branch on it before deciding how to run the order.
|
|
116
117
|
|
|
117
118
|
```ts
|
|
118
119
|
for (const order of orders) {
|
|
119
120
|
const result =
|
|
120
|
-
order.
|
|
121
|
+
order.executor === 'command'
|
|
121
122
|
? await runCommand(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
|
|
122
|
-
: await runYourAgent(order); // default /
|
|
123
|
+
: await runYourAgent(order); // default / executor: 'agent' / anything else you handle the same way
|
|
123
124
|
|
|
124
125
|
const commit = engine.green(wf, order.run, order.outputs[0], result);
|
|
125
126
|
engine.close(wf, order.run);
|
|
126
127
|
}
|
|
127
128
|
```
|
|
128
129
|
|
|
129
|
-
`
|
|
130
|
+
`executor`/`command`/`spec` are all optional and opaque — the engine only
|
|
130
131
|
shape-checks them at load time (`command` a string, `spec` a plain map) and
|
|
131
|
-
never reads their contents itself. `order.
|
|
132
|
+
never reads their contents itself. `order.executor` is `undefined` when the
|
|
132
133
|
step never set it (today's default, unaffected by this feature). See
|
|
133
134
|
[`docs/design.md` §27.4](design.md) for the full contract and
|
|
134
|
-
[`docs/authoring.md`](authoring.md#
|
|
135
|
+
[`docs/authoring.md`](authoring.md#executor--declaring-the-executor) for how to
|
|
135
136
|
declare it on a step.
|
|
136
137
|
|
|
137
138
|
A runnable version of this lives at [`examples/embed.ts`](../examples/embed.ts):
|
|
@@ -1,27 +1,27 @@
|
|
|
1
|
-
# Declarative executor dispatch — demonstrates `
|
|
1
|
+
# Declarative executor dispatch — demonstrates `executor:`/`command:`/`spec:`
|
|
2
2
|
# (§27.4 of docs/design.md).
|
|
3
3
|
#
|
|
4
|
-
# The engine never executes anything; `
|
|
4
|
+
# The engine never executes anything; `executor:` declares which kind of
|
|
5
5
|
# executor a step's order is for, so the same def can mix an LLM-driven step
|
|
6
|
-
# with a deterministic, non-LLM one. `planner` omits `
|
|
6
|
+
# with a deterministic, non-LLM one. `planner` omits `executor:` entirely (the
|
|
7
7
|
# default, unaffected `'agent'` path — every existing def in this repo stays
|
|
8
|
-
# exactly like this). `tester` declares `
|
|
9
|
-
# `command:` — a
|
|
8
|
+
# exactly like this). `tester` declares `executor: command` with a real
|
|
9
|
+
# `command:` — a Worker dispatching this order runs the command instead of an
|
|
10
10
|
# agent, no judgment involved. `tester`'s `result` produce is gated by a
|
|
11
11
|
# command judge (`ci-gate`): judges can be deterministic too, not just
|
|
12
12
|
# LLM-based — this one runs a check script and approves/rejects on exit status.
|
|
13
13
|
#
|
|
14
14
|
# Drive it:
|
|
15
|
-
# wf=$(owenloop create command-
|
|
16
|
-
# owenloop tick $wf # -> order for `planner` (
|
|
15
|
+
# wf=$(owenloop create command-executor --provide plan='{"text":"add a cache layer"}' | jq -r .workflow)
|
|
16
|
+
# owenloop tick $wf # -> order for `planner` (executor: agent, default)
|
|
17
17
|
# owenloop green $wf <run> reviewed_plan --value '{"approved":true}'
|
|
18
|
-
# owenloop tick $wf # -> order for `tester` (
|
|
18
|
+
# owenloop tick $wf # -> order for `tester` (executor: command)
|
|
19
19
|
# owenloop green $wf <run> result --value '{"exitCode":0}'
|
|
20
|
-
# owenloop tick $wf # -> order for the `ci-gate` judge (
|
|
20
|
+
# owenloop tick $wf # -> order for the `ci-gate` judge (executor: command)
|
|
21
21
|
# owenloop green $wf <judge-run> result --value '{}' # judge approves -> result goes green
|
|
22
22
|
|
|
23
|
-
name: command-
|
|
24
|
-
title: Command-dispatched
|
|
23
|
+
name: command-executor
|
|
24
|
+
title: Command-dispatched executor step
|
|
25
25
|
description: Mixes an agent step with a deterministic command step and a command judge.
|
|
26
26
|
|
|
27
27
|
inputs:
|
|
@@ -32,7 +32,7 @@ steps:
|
|
|
32
32
|
- name: planner
|
|
33
33
|
consumes: [plan]
|
|
34
34
|
produces: [reviewed_plan]
|
|
35
|
-
#
|
|
35
|
+
# executor: omitted here on purpose — the default/common case, completely
|
|
36
36
|
# unaffected by this feature. This step dispatches to an agent exactly
|
|
37
37
|
# like every step in every other bundled example.
|
|
38
38
|
body: |
|
|
@@ -46,11 +46,11 @@ steps:
|
|
|
46
46
|
judges:
|
|
47
47
|
- name: ci-gate
|
|
48
48
|
body: "unused by a command judge, but still a required field (§24)" # not read; a command judge acts on exit status, not a prompt
|
|
49
|
-
|
|
49
|
+
executor: command # deterministic — no judgment, just run the script
|
|
50
50
|
command: scripts/ci-gate.sh # exit 0 approves, non-zero rejects with its output
|
|
51
|
-
|
|
51
|
+
executor: command # deterministic — no judgment, just run the script
|
|
52
52
|
command: npm test # opaque to the engine; the dispatcher runs this
|
|
53
53
|
spec: # opaque config for the dispatcher; engine never reads it
|
|
54
54
|
timeout: 300
|
|
55
55
|
workdir: .
|
|
56
|
-
body: "" # not required for
|
|
56
|
+
body: "" # not required for executor: command (no agent prompt)
|
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
# compile-dev-playbook — the playbook compiler, developer-task edition.
|
|
2
|
+
#
|
|
3
|
+
# Compiles playbooks for repeatable DEVELOPMENT tasks — SDK integrations,
|
|
4
|
+
# service setup, infra additions — from live vendor documentation. The
|
|
5
|
+
# research sources (official docs, changelogs), the verification vocabulary
|
|
6
|
+
# (test suites, exit codes, lint gates), and the judge criteria are all
|
|
7
|
+
# dev-flavored on purpose; a different domain (business SOPs, compliance
|
|
8
|
+
# processes) deserves its own variant with equally sharp domain judges, not
|
|
9
|
+
# a genericized version of this one. The spine (scout -> distill invariants
|
|
10
|
+
# vs ephemera -> compile -> gate -> test-drive -> human-gated publish) is
|
|
11
|
+
# domain-invariant and is the part to extract via include: when a second
|
|
12
|
+
# domain variant exists.
|
|
13
|
+
#
|
|
14
|
+
# Treats documentation as source code and a workflow def as the compiled
|
|
15
|
+
# artifact: research a repeatable task across live docs, distill the knowledge
|
|
16
|
+
# into invariants (what must always be true) vs ephemera (what changes with
|
|
17
|
+
# versions), compile that into a new owenloop def, and refuse to publish it
|
|
18
|
+
# until it lints clean, survives an adversarial gate-sharpness review, and has
|
|
19
|
+
# actually been test-driven against the engine. Staleness becomes a rebuild:
|
|
20
|
+
# re-run this workflow on the same brief and diff the output.
|
|
21
|
+
#
|
|
22
|
+
# Workspace contract (for whatever conducts this):
|
|
23
|
+
# - Conduct from a scratch workspace dir. The `draft` step writes the
|
|
24
|
+
# generated def to ./build/<name>.yaml in that workspace.
|
|
25
|
+
# - `npx owenloop` must resolve (the lint judge and the test drive shell out
|
|
26
|
+
# to it).
|
|
27
|
+
# - Agent workers need file read/write and web access; the def_draft judges
|
|
28
|
+
# read the drafted YAML from disk at the path carried in the artifact.
|
|
29
|
+
#
|
|
30
|
+
# Drive it:
|
|
31
|
+
# wf=$(owenloop create compile-dev-playbook \
|
|
32
|
+
# --provide brief='{"task":"add Stripe subscription billing to a Node/TypeScript app","category":"billing"}' \
|
|
33
|
+
# | jq -r .workflow)
|
|
34
|
+
# owenloop tick $wf # ... conduct to done (e.g. with the owenloop-conduct skill)
|
|
35
|
+
# # `approval` is a human gate before publish. Flying solo? Pre-approve at create:
|
|
36
|
+
# # --provide approval='{"approved_by":"alex"}'
|
|
37
|
+
# # Otherwise the instance parks blocked on it — durably, in SQLite — until:
|
|
38
|
+
# # owenloop provide $wf approval --value '{"approved_by":"alex"}'
|
|
39
|
+
|
|
40
|
+
name: compile-dev-playbook
|
|
41
|
+
title: Playbook compiler (developer tasks)
|
|
42
|
+
description: >
|
|
43
|
+
Research a repeatable development task (SDK integration, service setup,
|
|
44
|
+
infra addition) across live documentation and compile the knowledge into a
|
|
45
|
+
validated, gate-checked, test-driven owenloop workflow def ("playbook"),
|
|
46
|
+
publishable to a library or hub.
|
|
47
|
+
|
|
48
|
+
executors: [agent, command] # typo guard: any other executor value is a load error
|
|
49
|
+
|
|
50
|
+
x:
|
|
51
|
+
category: meta
|
|
52
|
+
motto: docs are source; the def is the compiled artifact
|
|
53
|
+
|
|
54
|
+
inputs:
|
|
55
|
+
- name: brief
|
|
56
|
+
seedOwed: true
|
|
57
|
+
schema:
|
|
58
|
+
type: object
|
|
59
|
+
required: [task]
|
|
60
|
+
properties:
|
|
61
|
+
task: { type: string, description: "What the playbook automates, e.g. 'add Stripe subscription billing to a Node/TypeScript app'" }
|
|
62
|
+
stack: { type: string, description: "Target stack/context assumptions, if any" }
|
|
63
|
+
category: { type: string, description: "Hub category, e.g. billing | auth | infra | ops" }
|
|
64
|
+
notes: { type: string, description: "Anything else: scope cuts, org conventions, publish destination" }
|
|
65
|
+
|
|
66
|
+
- name: approval
|
|
67
|
+
seedOwed: true
|
|
68
|
+
producer: human
|
|
69
|
+
schema:
|
|
70
|
+
type: object
|
|
71
|
+
required: [approved_by]
|
|
72
|
+
properties:
|
|
73
|
+
approved_by: { type: string }
|
|
74
|
+
notes: { type: string }
|
|
75
|
+
|
|
76
|
+
outputs:
|
|
77
|
+
- playbook
|
|
78
|
+
|
|
79
|
+
steps:
|
|
80
|
+
# ── Research ────────────────────────────────────────────────────────────
|
|
81
|
+
- name: scout
|
|
82
|
+
consumes: [brief]
|
|
83
|
+
produces: ["scout.source[]"]
|
|
84
|
+
model: standard
|
|
85
|
+
body: |
|
|
86
|
+
Workflow ${WORKFLOW}, run ${RUN}.
|
|
87
|
+
Find the authoritative sources for the task in `brief`. Prefer, in order:
|
|
88
|
+
official docs (setup/integration guides, API references), official
|
|
89
|
+
changelogs or release notes (to see what moved recently), then credible
|
|
90
|
+
community material only where official docs are thin.
|
|
91
|
+
`emit` each source as {url, title, kind, why} where kind is one of
|
|
92
|
+
official | changelog | community and `why` says what this source is
|
|
93
|
+
expected to contribute. `seal` once official docs cover the core flow
|
|
94
|
+
AND at least one source speaks to recency (changelog/release notes).
|
|
95
|
+
Do not emit more than ~10 sources — this is a scout, not a crawl.
|
|
96
|
+
|
|
97
|
+
- name: read
|
|
98
|
+
consumes: ["scout.source[$i]"]
|
|
99
|
+
produces: ["scout.source[$i].extract"]
|
|
100
|
+
parallel: 6
|
|
101
|
+
model: fast
|
|
102
|
+
body: |
|
|
103
|
+
Workflow ${WORKFLOW}, run ${RUN}, element ${INDEX}.
|
|
104
|
+
Fetch and read this ONE source. Extract, grounded strictly in what the
|
|
105
|
+
page actually says (no memory, no invention):
|
|
106
|
+
- steps: the procedure the source prescribes, in order
|
|
107
|
+
- invariant_candidates: things that must be TRUE for the integration
|
|
108
|
+
to be correct/safe, regardless of SDK version (e.g. "webhook
|
|
109
|
+
signatures must be verified")
|
|
110
|
+
- pitfalls: warnings, deprecations, common mistakes the source calls out
|
|
111
|
+
- versioning: API/SDK versions, dates, anything that smells ephemeral
|
|
112
|
+
- verifications: anything checkable by a command or test (exit codes,
|
|
113
|
+
CLI verbs, test recipes, dashboard states)
|
|
114
|
+
- human_actions: anything only a human can do (create an account,
|
|
115
|
+
approve a dashboard setting, supply a credential)
|
|
116
|
+
Green `.extract` with those fields plus the source url. If the source is
|
|
117
|
+
dead, paywalled, or off-topic, `retract scout.source[${INDEX}]` instead —
|
|
118
|
+
it drops out of the distillation entirely.
|
|
119
|
+
|
|
120
|
+
# ── Distill: invariants vs ephemera ─────────────────────────────────────
|
|
121
|
+
- name: distill
|
|
122
|
+
consumes: [brief, "scout.source[*].extract"]
|
|
123
|
+
produces:
|
|
124
|
+
- name: knowledge
|
|
125
|
+
schema:
|
|
126
|
+
type: object
|
|
127
|
+
required: [invariants, ephemera, human_inputs, verifications, sources]
|
|
128
|
+
properties:
|
|
129
|
+
invariants:
|
|
130
|
+
type: array
|
|
131
|
+
minItems: 3
|
|
132
|
+
items:
|
|
133
|
+
type: object
|
|
134
|
+
required: [claim, verify_by, sources]
|
|
135
|
+
properties:
|
|
136
|
+
claim: { type: string }
|
|
137
|
+
why: { type: string }
|
|
138
|
+
verify_by: { type: string, description: "How a workflow gate could check this: a command, a judge criterion, a schema" }
|
|
139
|
+
sources: { type: array, items: { type: string }, minItems: 1 }
|
|
140
|
+
ephemera:
|
|
141
|
+
type: array
|
|
142
|
+
items:
|
|
143
|
+
type: object
|
|
144
|
+
required: [detail, source]
|
|
145
|
+
properties:
|
|
146
|
+
detail: { type: string, description: "Version-bound specifics: SDK calls, current API versions, exact snippets" }
|
|
147
|
+
source: { type: string }
|
|
148
|
+
human_inputs:
|
|
149
|
+
type: array
|
|
150
|
+
items:
|
|
151
|
+
type: object
|
|
152
|
+
required: [name, what]
|
|
153
|
+
properties:
|
|
154
|
+
name: { type: string }
|
|
155
|
+
what: { type: string }
|
|
156
|
+
verifications:
|
|
157
|
+
type: array
|
|
158
|
+
minItems: 2
|
|
159
|
+
items:
|
|
160
|
+
type: object
|
|
161
|
+
required: [what, how]
|
|
162
|
+
properties:
|
|
163
|
+
what: { type: string }
|
|
164
|
+
how: { type: string, description: "command | judge | schema — and the concrete check" }
|
|
165
|
+
sources:
|
|
166
|
+
type: array
|
|
167
|
+
items: { type: string }
|
|
168
|
+
judges:
|
|
169
|
+
- name: altitude
|
|
170
|
+
model: strong
|
|
171
|
+
body: |
|
|
172
|
+
Judge `knowledge` for altitude discipline — the one rule that
|
|
173
|
+
keeps compiled playbooks from going stale:
|
|
174
|
+
- Every invariant must be a WHAT-MUST-BE-TRUE claim, durable
|
|
175
|
+
across SDK versions. Reject if any invariant is code-level
|
|
176
|
+
how-to (exact function names, snippets, current API
|
|
177
|
+
versions) — that material belongs in `ephemera`.
|
|
178
|
+
- Every invariant must carry a usable `verify_by` — something
|
|
179
|
+
a workflow gate could actually check. "Be careful" is not a
|
|
180
|
+
verification. Reject vague ones, naming them.
|
|
181
|
+
- Reject if `human_inputs` is empty but any extract mentioned
|
|
182
|
+
accounts, credentials, or dashboard actions.
|
|
183
|
+
Otherwise approve. Rejections must name the offending entries.
|
|
184
|
+
- name: grounding
|
|
185
|
+
inputs: true
|
|
186
|
+
body: |
|
|
187
|
+
You can see the source extracts `knowledge` was distilled from.
|
|
188
|
+
Cross-check: every invariant's `sources` must point at extracts
|
|
189
|
+
that actually support the claim. Reject any invariant that is
|
|
190
|
+
unsupported by, or contradicts, the extracts — cite which.
|
|
191
|
+
Otherwise approve.
|
|
192
|
+
maxAttempts: 3
|
|
193
|
+
model: strong
|
|
194
|
+
body: |
|
|
195
|
+
Workflow ${WORKFLOW}, run ${RUN}.
|
|
196
|
+
Distill every surviving source extract into `knowledge` — the invariant
|
|
197
|
+
model of this task, per the schema. The discipline that matters:
|
|
198
|
+
invariants are what must be true in ANY correct implementation
|
|
199
|
+
(durable); ephemera are today's specifics (SDK calls, versions) and are
|
|
200
|
+
recorded only as pointers back to sources — the compiled playbook will
|
|
201
|
+
cite them, never hardcode them. Merge duplicates across sources; where
|
|
202
|
+
sources conflict, prefer official and newer, and note the conflict.
|
|
203
|
+
|
|
204
|
+
# ── Compile ──────────────────────────────────────────────────────────────
|
|
205
|
+
- name: draft
|
|
206
|
+
consumes: [brief, knowledge]
|
|
207
|
+
produces:
|
|
208
|
+
- name: def_draft
|
|
209
|
+
schema:
|
|
210
|
+
type: object
|
|
211
|
+
required: [name, path, summary, gates]
|
|
212
|
+
properties:
|
|
213
|
+
name: { type: string, description: "the generated def's name:" }
|
|
214
|
+
path: { type: string, description: "where the YAML was written, e.g. build/<name>.yaml" }
|
|
215
|
+
summary: { type: string }
|
|
216
|
+
gates: { type: array, minItems: 2, items: { type: string }, description: "the enforced gates the def carries, one line each" }
|
|
217
|
+
judges:
|
|
218
|
+
- name: lints-clean
|
|
219
|
+
executor: command
|
|
220
|
+
command: npx owenloop lint --defs build
|
|
221
|
+
spec: { workdir: "." }
|
|
222
|
+
body: unused by a command judge; exit 0 approves, non-zero rejects with the lint output
|
|
223
|
+
- name: gate-sharpness
|
|
224
|
+
bodyFile: judges/gate-sharpness.md
|
|
225
|
+
model: strong
|
|
226
|
+
- name: security
|
|
227
|
+
bodyFile: judges/security.md
|
|
228
|
+
model: strong
|
|
229
|
+
maxAttempts: 4
|
|
230
|
+
model: strong
|
|
231
|
+
body: |
|
|
232
|
+
Workflow ${WORKFLOW}, run ${RUN}.
|
|
233
|
+
Compile `knowledge` into a complete owenloop workflow def for the task
|
|
234
|
+
in `brief`. Write the YAML to build/<name>.yaml (create build/ if
|
|
235
|
+
needed), then green `def_draft` with {name, path, summary, gates} — the
|
|
236
|
+
YAML itself lives on disk, not in the artifact.
|
|
237
|
+
|
|
238
|
+
Compilation rules — each is checked by a judge, so cutting corners just
|
|
239
|
+
buys you a rejection:
|
|
240
|
+
1. FRESHNESS: the generated def's FIRST step must consume the def's
|
|
241
|
+
seeded task input and produce a plan grounded in reading the current
|
|
242
|
+
official docs (cite the source URLs from `knowledge` in its body).
|
|
243
|
+
The playbook forces doc-reading; it never substitutes for it.
|
|
244
|
+
2. INVARIANTS → STRUCTURE: every invariant in `knowledge` must be
|
|
245
|
+
carried by the def's structure — a step with a schema'd produce, a
|
|
246
|
+
judge, or a command gate. An invariant that survives only as prose
|
|
247
|
+
in a body is a compile error.
|
|
248
|
+
3. GATES: every entry in `knowledge.verifications` becomes an enforced
|
|
249
|
+
gate — `executor: command` with the check command where deterministic
|
|
250
|
+
(tests run and pass = exit code), a judge otherwise. List each in
|
|
251
|
+
`def_draft.gates`.
|
|
252
|
+
4. HUMAN MOMENTS: every entry in `knowledge.human_inputs` becomes a
|
|
253
|
+
seedOwed input with a schema — the instance parks until a human
|
|
254
|
+
provides it. Never model these as agent steps. Secrets are
|
|
255
|
+
referenced by name (secret-manager key, env var name), never carried
|
|
256
|
+
as values.
|
|
257
|
+
5. EPHEMERA: never hardcode version-bound specifics. Where the
|
|
258
|
+
implementer needs them, the step body says "consult <source URL>".
|
|
259
|
+
6. SIDE EFFECTS: any step with an irreversible external effect declares
|
|
260
|
+
effect: { idempotent: false, onInvalidate: escalate } (or a named
|
|
261
|
+
compensator).
|
|
262
|
+
7. PROVENANCE: the def carries an x: block — compiled_from (source
|
|
263
|
+
URLs), compiled_for (brief.task), category, compiled_at (today's
|
|
264
|
+
date) — so staleness is visible and a recompile is diffable.
|
|
265
|
+
8. HOUSE RULES: model tiers by intent (fast/standard/strong), sensible
|
|
266
|
+
maxAttempts, a header comment with drive instructions, and
|
|
267
|
+
`executors:` listing every executor value used.
|
|
268
|
+
|
|
269
|
+
# ── Test drive: a def that has never been driven is a hypothesis ────────
|
|
270
|
+
- name: testdrive
|
|
271
|
+
consumes: [def_draft]
|
|
272
|
+
invalidates: [def_draft]
|
|
273
|
+
produces:
|
|
274
|
+
- name: drive_report
|
|
275
|
+
schema:
|
|
276
|
+
type: object
|
|
277
|
+
required: [verdict, evidence, issues]
|
|
278
|
+
properties:
|
|
279
|
+
verdict: { type: string, enum: [pass] }
|
|
280
|
+
evidence: { type: array, minItems: 2, items: { type: string }, description: "commands run and what they returned" }
|
|
281
|
+
issues: { type: array, items: { type: string } }
|
|
282
|
+
judges:
|
|
283
|
+
- name: honest-drive
|
|
284
|
+
inputs: true
|
|
285
|
+
body: |
|
|
286
|
+
Judge `drive_report` against the def it claims to have driven.
|
|
287
|
+
Reject if: `evidence` does not show BOTH a reachability check
|
|
288
|
+
and a real instance being ticked; the claimed refusal probe is
|
|
289
|
+
missing; or `issues` lists anything that should have been a
|
|
290
|
+
rejection of `def_draft` instead of a pass. A pass without
|
|
291
|
+
evidence is a lie — reject it. Otherwise approve.
|
|
292
|
+
maxAttempts: 3
|
|
293
|
+
model: standard
|
|
294
|
+
body: |
|
|
295
|
+
Workflow ${WORKFLOW}, run ${RUN}.
|
|
296
|
+
Test-drive the def at `def_draft.path` against the real engine. At
|
|
297
|
+
minimum, run and capture:
|
|
298
|
+
1. npx owenloop check <name> --defs build --assume-provided
|
|
299
|
+
(bounded reachability: deadlocks, stuck steps, dead branches)
|
|
300
|
+
2. A dry instantiation against a SCRATCH db (never the real one):
|
|
301
|
+
npx owenloop create <name> --defs build --db build/testdrive.db \
|
|
302
|
+
--provide <seed inputs with plausible sample values>
|
|
303
|
+
then tick it and confirm the first order(s) are the doc-reading
|
|
304
|
+
step, not something deeper in the graph.
|
|
305
|
+
3. A refusal probe: green one schema'd artifact with a deliberately
|
|
306
|
+
malformed value and confirm the engine refuses it
|
|
307
|
+
(schema-rejected), then a valid value and confirm it lands.
|
|
308
|
+
Then EITHER green `drive_report` with verdict "pass" and the evidence
|
|
309
|
+
(commands + observed output), OR — if anything is wrong with the def —
|
|
310
|
+
reject `def_draft` with the concrete failures (this re-arms `draft`
|
|
311
|
+
with your reasons attached) and close this run without greening. Never
|
|
312
|
+
both; never a pass on faith. Clean up the scratch db.
|
|
313
|
+
|
|
314
|
+
# ── Publish (human-gated, irreversible) ─────────────────────────────────
|
|
315
|
+
- name: publish
|
|
316
|
+
consumes: [def_draft, drive_report, approval]
|
|
317
|
+
produces:
|
|
318
|
+
- name: playbook
|
|
319
|
+
schema:
|
|
320
|
+
type: object
|
|
321
|
+
required: [name, path, sources, compiled_at]
|
|
322
|
+
properties:
|
|
323
|
+
name: { type: string }
|
|
324
|
+
path: { type: string, description: "where the published def landed" }
|
|
325
|
+
sources: { type: array, items: { type: string } }
|
|
326
|
+
compiled_at: { type: string }
|
|
327
|
+
effect:
|
|
328
|
+
idempotent: false # publishing is an external write —
|
|
329
|
+
onInvalidate: escalate # if upstream moves later, hold for a human, don't re-publish
|
|
330
|
+
model: fast
|
|
331
|
+
body: |
|
|
332
|
+
Workflow ${WORKFLOW}, run ${RUN}.
|
|
333
|
+
Publish the approved def: copy `def_draft.path` into the playbook
|
|
334
|
+
library (brief.notes may name a destination; default ./playbooks/).
|
|
335
|
+
Verify the copy is byte-identical and its x: provenance block is
|
|
336
|
+
complete. Green `playbook` with {name, path, sources, compiled_at}
|
|
337
|
+
taken from the def's own provenance. Do not edit the def here — publish
|
|
338
|
+
exactly what was judged and driven.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# gate-sharpness — reject skills wearing workflow costumes
|
|
2
|
+
|
|
3
|
+
You are judging `def_draft` — a freshly compiled owenloop workflow def. The
|
|
4
|
+
artifact value carries `{name, path, summary, gates}`; read the actual YAML
|
|
5
|
+
from disk at `path`. Your one question: **does this def ENFORCE its playbook,
|
|
6
|
+
or merely describe it?** A def whose guarantees live in prose is a skill
|
|
7
|
+
wearing a workflow costume, and it does not ship.
|
|
8
|
+
|
|
9
|
+
Reject `def_draft` (with the concrete, fixable gaps) if ANY of these hold:
|
|
10
|
+
|
|
11
|
+
1. **Weak gates.** Fewer than two non-trivial enforced gates across the def —
|
|
12
|
+
where a gate is an `executor: command` step/judge whose exit status decides,
|
|
13
|
+
a judge with a sharp rejection criterion, or a schema on an artifact whose
|
|
14
|
+
shape matters. "The agent will make sure tests pass" in a body is not a
|
|
15
|
+
gate.
|
|
16
|
+
2. **Prose invariants.** Any must-be-true claim (verify signatures, run the
|
|
17
|
+
tests, don't commit keys) that appears only inside a `body:` with no
|
|
18
|
+
judge, schema, or command backing it.
|
|
19
|
+
3. **No freshness step.** The first real step does not force reading the
|
|
20
|
+
current official docs (with cited URLs) before any implementation step can
|
|
21
|
+
fire.
|
|
22
|
+
4. **Hardcoded ephemera.** Bodies that bake in version-bound specifics —
|
|
23
|
+
exact SDK call sequences, current API version strings, copy-paste
|
|
24
|
+
snippets — instead of pointing the implementer at a cited source.
|
|
25
|
+
5. **Faked human moments.** Account creation, credential provisioning, or
|
|
26
|
+
dashboard approvals modeled as agent steps instead of `seedOwed` inputs.
|
|
27
|
+
6. **Unmarked side effects.** A step that deploys, publishes, or writes to an
|
|
28
|
+
external system without `effect: { idempotent: false, ... }`.
|
|
29
|
+
7. **Missing provenance.** No `x:` block with compiled_from / compiled_for /
|
|
30
|
+
compiled_at — an unstamped def is invisible staleness.
|
|
31
|
+
8. **Self-approval.** Any step that both produces an artifact and is its own
|
|
32
|
+
quality check — the point of this whole system is that the fox does not
|
|
33
|
+
audit the henhouse.
|
|
34
|
+
|
|
35
|
+
Also sanity-check that `def_draft.gates` honestly lists the gates the YAML
|
|
36
|
+
actually declares — an inflated gates list is itself grounds for rejection.
|
|
37
|
+
|
|
38
|
+
If none of the above hold, approve. Do not reject for style, verbosity, or
|
|
39
|
+
choices you would merely have made differently — sharpness, not taste.
|