owenloop 0.5.9 → 0.5.11
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 +51 -0
- package/README.md +77 -37
- package/bin/owenloop.mjs +16 -1
- package/dist/packages/work/src/agent/loop.js +7 -0
- package/dist/packages/work/src/bundle/pull.d.ts +21 -0
- package/dist/packages/work/src/bundle/pull.js +118 -0
- package/dist/packages/work/src/exec/instructions.d.ts +4 -1
- package/dist/packages/work/src/exec/instructions.js +3 -0
- package/dist/packages/work/src/exec/loop.d.ts +1 -1
- package/dist/packages/work/src/exec/loop.js +92 -14
- package/dist/packages/work/src/harness/claude.js +16 -0
- package/dist/packages/work/src/harness/codex.d.ts +8 -0
- package/dist/packages/work/src/harness/codex.js +27 -1
- package/dist/packages/work/src/harness/contract.d.ts +9 -0
- package/dist/packages/work/src/roles/agent-run.js +38 -10
- package/dist/packages/work/src/roles/exec.js +25 -8
- package/dist/packages/work/src/shift/loop.js +118 -4
- package/dist/packages/work/src/shift/runtime.d.ts +3 -0
- package/dist/packages/work/src/shift/runtime.js +10 -1
- package/dist/packages/work/src/submit-proof.d.ts +11 -8
- package/dist/packages/work/src/submit-proof.js +11 -8
- package/dist/src/capabilities.d.ts +70 -6
- package/dist/src/capabilities.js +49 -6
- package/dist/src/capability-mapping-client.d.ts +29 -0
- package/dist/src/capability-mapping-client.js +160 -0
- package/dist/src/cli.d.ts +2 -2
- package/dist/src/cli.js +1200 -166
- package/dist/src/defs.d.ts +41 -1
- package/dist/src/defs.js +461 -92
- package/dist/src/engine.d.ts +108 -22
- package/dist/src/engine.js +573 -85
- package/dist/src/factory.js +5 -3
- package/dist/src/hub.d.ts +77 -0
- package/dist/src/hub.js +162 -0
- package/dist/src/implements.d.ts +37 -0
- package/dist/src/implements.js +790 -0
- package/dist/src/index.d.ts +12 -10
- package/dist/src/index.js +7 -6
- package/dist/src/mcp/serve.js +254 -45
- package/dist/src/mcp/server.d.ts +10 -7
- package/dist/src/mcp/server.js +53 -8
- package/dist/src/model.d.ts +46 -10
- package/dist/src/model.js +224 -78
- package/dist/src/order-resolver.js +1 -0
- package/dist/src/store/def-source.d.ts +19 -0
- package/dist/src/store/def-source.js +87 -17
- package/dist/src/store/gc-recovery.d.ts +46 -0
- package/dist/src/store/gc-recovery.js +258 -0
- package/dist/src/store/gc.d.ts +94 -0
- package/dist/src/store/gc.js +563 -0
- package/dist/src/store/index.d.ts +3 -1
- package/dist/src/store/index.js +2 -0
- package/dist/src/store/install.d.ts +34 -5
- package/dist/src/store/install.js +73 -11
- package/dist/src/store/pre-commit-verifier.js +42 -2
- package/dist/src/store/snapshot-guard.d.ts +18 -0
- package/dist/src/store/snapshot-guard.js +94 -0
- package/dist/src/store.d.ts +66 -4
- package/dist/src/store.js +333 -12
- package/dist/src/types.d.ts +97 -17
- package/dist/src/types.js +4 -0
- package/dist/src/util.js +4 -1
- package/docs/authoring.md +214 -9
- package/docs/bundles.md +19 -0
- package/docs/cli.md +270 -30
- package/docs/crypto.md +13 -7
- package/docs/design.md +107 -46
- package/docs/evals/mcp-charter-baseline.json +428 -0
- package/docs/mcp-charter-eval.md +124 -0
- package/docs/shift-logs.md +18 -0
- package/docs/wire-contracts.md +28 -7
- package/examples/workflows/compile-dev-playbook.yaml +1 -1
- package/examples/workflows/ship.yaml +28 -2
- package/package.json +2 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
- package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
- package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
- package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
- package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
- package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
- package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ephemeral
|
|
3
|
+
description: Create, self-drive, and retire a collision-safe hub ephemeral workflow for your own complex one-off work. Use when rework, fan-out, quality gates, session survival, or unattended brakes make a todo list insufficient.
|
|
4
|
+
allowed-tools: mcp__plugin_owenloop_owenloop__list_workflows, mcp__plugin_owenloop_owenloop__create_workflow, mcp__plugin_owenloop_owenloop__get_workflow, mcp__plugin_owenloop_owenloop__start_run, mcp__plugin_owenloop_owenloop__whats_next, mcp__plugin_owenloop_owenloop__heartbeat, mcp__plugin_owenloop_owenloop__get_order, mcp__plugin_owenloop_owenloop__submit, mcp__plugin_owenloop_owenloop__reject_artifact, mcp__plugin_owenloop_owenloop__get_status, mcp__plugin_owenloop_owenloop__delete_workflow, mcp__owenloop__list_workflows, mcp__owenloop__create_workflow, mcp__owenloop__get_workflow, mcp__owenloop__start_run, mcp__owenloop__whats_next, mcp__owenloop__heartbeat, mcp__owenloop__get_order, mcp__owenloop__submit, mcp__owenloop__reject_artifact, mcp__owenloop__get_status, mcp__owenloop__delete_workflow
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# ephemeral
|
|
8
|
+
|
|
9
|
+
Use this only for a caller-owned, one-off workflow on the hub. You author it,
|
|
10
|
+
perform its real served work, and retire its live name when it is complete.
|
|
11
|
+
This is the explicit exception to the ordinary chief-of-staff posture: never
|
|
12
|
+
use it to fabricate progress for an unrelated crew run.
|
|
13
|
+
|
|
14
|
+
## Decision gate
|
|
15
|
+
|
|
16
|
+
A todo list is free. An ephemeral workflow costs authoring and lifecycle
|
|
17
|
+
overhead. Use it only when **at least two** signals apply:
|
|
18
|
+
|
|
19
|
+
| # | Signal | Concrete test |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| R1 | Rework loop | A verify or review step will plausibly send work back with reasons at least once. |
|
|
22
|
+
| R2 | Fan-out | The same operation runs over N items discovered at runtime, where N > 3. |
|
|
23
|
+
| R3 | Quality gate | Downstream work must not proceed until an artifact clears a bar you can state as a judge prompt. |
|
|
24
|
+
| R4 | Survival | The work must outlive this context window or session, or be resumable by another session. |
|
|
25
|
+
| R5 | Upstream volatility | An early artifact such as a plan, scout list, or diagnosis will plausibly be revised after downstream work exists. |
|
|
26
|
+
| R6 | Unattended brakes | Parts run with no human watching; repeated failure must stall rather than loop. |
|
|
27
|
+
|
|
28
|
+
Never use it when any of these hold:
|
|
29
|
+
|
|
30
|
+
- Straight line of at most about five steps with no plausible rework: use a todo list.
|
|
31
|
+
- Steps are smaller than one coherent agent turn; lifecycle overhead dominates.
|
|
32
|
+
- You cannot yet name each step as “consumes X, produces Y” in one sitting. Explore inline first; runtime item discovery is fine after the graph is nameable.
|
|
33
|
+
- Everything fits comfortably in the current context and nothing will be rejected. The value here is memory and honesty across boundaries.
|
|
34
|
+
|
|
35
|
+
## Capability preflight
|
|
36
|
+
|
|
37
|
+
Before drafting YAML, call `list_workflows` with `include_ephemeral: true` for
|
|
38
|
+
the later collision check. A 200 inclusive listing is **not** a capability
|
|
39
|
+
attestation: the mounted CLI proxy can advertise new fields while an older
|
|
40
|
+
selected hub silently ignores them.
|
|
41
|
+
|
|
42
|
+
The `create_workflow` call with `ephemeral: true` must first perform the
|
|
43
|
+
remote MCP capability preflight, before it sends any create request. It must
|
|
44
|
+
attest that the selected hub's own `tools/list` exposes
|
|
45
|
+
`create_workflow.ephemeral`, `list_workflows.include_ephemeral`, and
|
|
46
|
+
`delete_workflow`. If that preflight returns an error, stop and report its
|
|
47
|
+
exact response. Never fall back to a durable definition or infer support from
|
|
48
|
+
the proxy's local tool surface.
|
|
49
|
+
|
|
50
|
+
## Publish a unique ephemeral definition
|
|
51
|
+
|
|
52
|
+
1. Generate a legal lowercase per-run name such as
|
|
53
|
+
`eph-<short-task-slug>-<unix-ms>-<random-hex>`. Friendly or reusable names
|
|
54
|
+
are forbidden.
|
|
55
|
+
2. Use the inclusive listing and refuse to create if that exact name already
|
|
56
|
+
exists.
|
|
57
|
+
3. Draft the small workflow YAML in memory, then call `create_workflow` with
|
|
58
|
+
the YAML and `ephemeral: true`.
|
|
59
|
+
4. Immediately call `get_workflow` for the generated name. Require read-back
|
|
60
|
+
proof that `ephemeral: true`; a successful create response is insufficient
|
|
61
|
+
because an unknown body key can be ignored. Record the returned live name,
|
|
62
|
+
version, and hash.
|
|
63
|
+
|
|
64
|
+
## Self-drive honestly
|
|
65
|
+
|
|
66
|
+
Call `start_run` for the generated definition. Loop with `whats_next` for
|
|
67
|
+
that workflow. For every served order, make first contact with `heartbeat`
|
|
68
|
+
or `get_order`, perform the order's actual work, and `submit` every owed
|
|
69
|
+
value from the held run. Use `reject_artifact` only for a real upstream
|
|
70
|
+
defect with a concrete reason.
|
|
71
|
+
|
|
72
|
+
When no order is returned, use `get_status`. Stop only after terminal
|
|
73
|
+
completion. Do not use conduct or shift, and do not wait for an ordinary crew:
|
|
74
|
+
this deliberately ephemeral, caller-owned run is yours to execute. Do not
|
|
75
|
+
submit invented artifacts.
|
|
76
|
+
|
|
77
|
+
## Retire safely
|
|
78
|
+
|
|
79
|
+
After terminal status, call `get_workflow` again and compare its name,
|
|
80
|
+
version, and hash with the values recorded after publication. If any differ,
|
|
81
|
+
do not delete: a concurrent publisher owns the live pointer. If they match,
|
|
82
|
+
call `delete_workflow` exactly once.
|
|
83
|
+
|
|
84
|
+
Retirement removes only the live catalog pointer. Historical pinned definition
|
|
85
|
+
versions remain reachable and are never deleted.
|
|
86
|
+
|
|
87
|
+
Classify a `workflow_delete_refused` response by its message, never its HTTP
|
|
88
|
+
status alone. “Active root references” is potentially retryable only after
|
|
89
|
+
rechecking terminal status. “No live definition” and “not ephemeral” are
|
|
90
|
+
permanent refusals. Do not blindly loop on every 409 or every
|
|
91
|
+
`workflow_delete_refused`.
|
|
92
|
+
|
|
93
|
+
If preflight fails, read-back does not prove `ephemeral: true`, the live
|
|
94
|
+
version or hash changed, or retirement is permanently refused, stop and
|
|
95
|
+
surface the exact response. Do not claim cleanup succeeded.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: graduate
|
|
3
|
+
description: Promote evidence from a successful completed ephemeral composite into a reusable library candidate and admission-evidence record. Use when a plan-compiled ephemeral workflow has finished done and a target library needs a policy-conformant candidate definition.
|
|
4
|
+
allowed-tools: mcp__plugin_owenloop_owenloop__get_workflow, mcp__plugin_owenloop_owenloop__get_status, mcp__owenloop__get_workflow, mcp__owenloop__get_status, Write, Bash(mktemp:*), Bash(owenloop:*), Bash(rm:*)
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# graduate
|
|
8
|
+
|
|
9
|
+
`graduate` prepares a reusable library candidate from one successful,
|
|
10
|
+
completed plan-compiled ephemeral composite. It produces a candidate YAML/path
|
|
11
|
+
and an admission-evidence record for the receiving library's policy gate. It
|
|
12
|
+
does not publish a bundle, pack a repository, assign stability, or say that a
|
|
13
|
+
graduation succeeded. The receiving library's clean-export/vendor/pack policy
|
|
14
|
+
remains the publication boundary.
|
|
15
|
+
|
|
16
|
+
This is deliberately a narrow, mixed permission surface. MCP supplies the
|
|
17
|
+
immutable source facts and terminal proof. `Write`, `Bash(mktemp:*)`,
|
|
18
|
+
`Bash(owenloop:*)`, and `Bash(rm:*)` exist only to stage and model-check one
|
|
19
|
+
exact temporary definition universe. Do not use `Edit`, a bare shell,
|
|
20
|
+
authoring or run-lifecycle tools, deletion verbs, or worker verbs.
|
|
21
|
+
|
|
22
|
+
## Required evidence and ordering
|
|
23
|
+
|
|
24
|
+
Require all of the following before proposing a candidate:
|
|
25
|
+
|
|
26
|
+
- the originating ephemeral definition name, version, and content hash;
|
|
27
|
+
- the originating workflow instance ID;
|
|
28
|
+
- the plan skill's preserved evidence: the exact `compiledPlan` with its
|
|
29
|
+
candidate and selection rationale, exact composite YAML, full clean check
|
|
30
|
+
JSON, read-back Mermaid, parked gate proof, approval/release proof, and final
|
|
31
|
+
run ID/status.
|
|
32
|
+
|
|
33
|
+
Retirement closes the live-name window. Follow this order:
|
|
34
|
+
|
|
35
|
+
1. Call `get_workflow(<ephemeral-name>)` **before retirement** and capture its
|
|
36
|
+
complete bundle. Require `ephemeral: true` and exact agreement with the
|
|
37
|
+
preserved name, version, and content hash. Its declared inputs, full step
|
|
38
|
+
bodies and schemas, `pins`, and hash-keyed frozen `children` closure are
|
|
39
|
+
the source definition.
|
|
40
|
+
2. If the live pointer was already retired, proceed only when the exact
|
|
41
|
+
publication-time full bundle was preserved. Otherwise stop rather than
|
|
42
|
+
reconstructing it.
|
|
43
|
+
3. Call `get_status(<workflow-id>)`. Require `terminal === true` and
|
|
44
|
+
`instanceStatus === "done"`. Failed or cancelled terminal runs are not
|
|
45
|
+
graduation evidence.
|
|
46
|
+
4. Take the selection rationale from the preserved `compiledPlan`.
|
|
47
|
+
`get_status` does not return artifact payloads; never use it to read
|
|
48
|
+
`compiledPlan` back.
|
|
49
|
+
5. Cite the originating workflow ID. Do not attempt a receipt read: receipt
|
|
50
|
+
bodies are unavailable on the agent-facing MCP and CLI surface, and the
|
|
51
|
+
receiving policy expressly allows a workflow ID instead.
|
|
52
|
+
|
|
53
|
+
After `delete_workflow` removes an ephemeral live pointer,
|
|
54
|
+
`get_workflow` by that name returns an unknown-definition error. Historical
|
|
55
|
+
definition rows and pins can remain, and a still-live parent can still expose a
|
|
56
|
+
frozen child, but that is not name resolution. Graduation must therefore happen
|
|
57
|
+
before retirement or use the exact full bundle captured at publication.
|
|
58
|
+
|
|
59
|
+
## Generalize the captured composite
|
|
60
|
+
|
|
61
|
+
Rebuild the candidate from the captured root and frozen `calls:` closure
|
|
62
|
+
without inventing workflow content. Preserve reusable behavior and exact
|
|
63
|
+
compatible child coordinates, but remove one-run compiler scaffolding and
|
|
64
|
+
parameterize task-specific literals.
|
|
65
|
+
|
|
66
|
+
Treat each root seed explicitly:
|
|
67
|
+
|
|
68
|
+
- `task`: replace the one-off value with the concrete reusable domain inputs
|
|
69
|
+
the composite actually consumed. Give every resulting top-level input a
|
|
70
|
+
descriptive name and explicit JSON Schema. Retain a generic `task` input
|
|
71
|
+
only when it is deliberately the reusable public contract, never as a
|
|
72
|
+
shortcut.
|
|
73
|
+
- `compiledPlan`: remove it from candidate runtime inputs and every runtime
|
|
74
|
+
consume. Preserve its `candidates`, `selectedTargets`, and reasons in the
|
|
75
|
+
admission-evidence record, where the one-run compiler rationale belongs.
|
|
76
|
+
- `planApproval`: remove the ephemeral compiler-release gate. If the reusable
|
|
77
|
+
workflow genuinely needs human authorization on every run, design a newly
|
|
78
|
+
named, domain-specific, schema-bearing human input/gate and wire all
|
|
79
|
+
applicable effects behind it; do not carry `planApproval` forward by
|
|
80
|
+
inertia.
|
|
81
|
+
|
|
82
|
+
Replace embedded one-run values in step bodies and mappings with references to
|
|
83
|
+
the new declared inputs. Require an explicit schema on every top-level input
|
|
84
|
+
and every authored `produces`/`generates` artifact, including internal
|
|
85
|
+
artifacts. Require every top-level output name to resolve to a schema-bearing
|
|
86
|
+
declaration. Preserve the complete exact `calls:` closure needed for local
|
|
87
|
+
checking.
|
|
88
|
+
|
|
89
|
+
Before proposing the candidate, compare every candidate step name with every
|
|
90
|
+
step name across the target library's complete clean-export workflow set.
|
|
91
|
+
Rename collisions coherently, update references, and re-run every check. A
|
|
92
|
+
per-definition lint or check is not sufficient for this archive-wide
|
|
93
|
+
invariant.
|
|
94
|
+
|
|
95
|
+
## Discovery metadata and local model check
|
|
96
|
+
|
|
97
|
+
Give the candidate an `x.discovery` object containing exactly
|
|
98
|
+
`description`, non-empty `whenToUse`, non-empty `notFor`, and
|
|
99
|
+
`interface`. `interface.inputs` and `interface.outputs` must cover every
|
|
100
|
+
declared input and public output exactly once, with no unknown or duplicate
|
|
101
|
+
names. Each entry must contain exactly a non-empty `name`, non-empty
|
|
102
|
+
`summary`, and `schemaRef`. Every `schemaRef` must be a local JSON Pointer
|
|
103
|
+
beginning `#/` and resolve to that declaration's existing schema, for example
|
|
104
|
+
`#/inputs/0/schema` or `#/steps/2/produces/0/schema`; never copy a schema
|
|
105
|
+
into discovery metadata.
|
|
106
|
+
|
|
107
|
+
Stage the candidate and every exact `calls:` target in one unique
|
|
108
|
+
`mktemp` directory outside the repository. Run:
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
owenloop lint --defs <staging-dir>
|
|
112
|
+
owenloop check <candidate-name> --defs <staging-dir> --format json
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Require lint to have zero errors and zero warnings. Parse the check JSON and
|
|
116
|
+
require `completable === true`, `bounded === false`, and empty
|
|
117
|
+
`deadlocks`, `stallStates`, `stuck`, `structurallyDeadSteps`,
|
|
118
|
+
`unreachedSteps`, and `invariantViolations`. Revise and repeat on any
|
|
119
|
+
failure, then remove only that exact temporary directory. Do not pack.
|
|
120
|
+
|
|
121
|
+
Hand the candidate to the target library's W2.1 clean-export/vendor/pack policy
|
|
122
|
+
gate. Those repository-owned rules remain the publication boundary.
|
|
123
|
+
|
|
124
|
+
## Deliver the candidate and evidence record
|
|
125
|
+
|
|
126
|
+
Deliver two explicit results:
|
|
127
|
+
|
|
128
|
+
1. The candidate YAML and its intended target path.
|
|
129
|
+
2. An evidence record retaining the source ephemeral name/version/hash and
|
|
130
|
+
workflow ID; terminal `done` proof; preserved `compiledPlan` selection
|
|
131
|
+
rationale and selected target coordinates; generalized-input mapping; final
|
|
132
|
+
lint/check evidence; archive-wide step-name comparison; and ready-to-use
|
|
133
|
+
version-bump narration.
|
|
134
|
+
|
|
135
|
+
The narration must expose these policy fields separately:
|
|
136
|
+
|
|
137
|
+
- `workflowCoordinate` — target package/workflow coordinate;
|
|
138
|
+
- `workflowVersion` — candidate receiving-bundle version;
|
|
139
|
+
- `originatingWorkflowId`;
|
|
140
|
+
- `completionResult` — `done`;
|
|
141
|
+
- `date` — `YYYY-MM-DD`.
|
|
142
|
+
|
|
143
|
+
If the preserved evidence lacks an actual completion timestamp, use the UTC
|
|
144
|
+
date on which `get_status` was re-verified and label it the verification date;
|
|
145
|
+
do not invent a completion time.
|
|
146
|
+
|
|
147
|
+
Prepare, but do not edit, the receiving repository's house-form comment
|
|
148
|
+
immediately above `package.version`:
|
|
149
|
+
|
|
150
|
+
```yaml
|
|
151
|
+
# <bundle-version>: graduated <workflow-coordinate>@<workflow-version>; originating workflow <wf_...>; completion result done; verified YYYY-MM-DD.
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Do not edit `owenloop-playbooks/bundle.yaml`, assign stability, pack a bundle,
|
|
155
|
+
or claim publication or graduation completed. The receiving policy gate decides
|
|
156
|
+
those outcomes.
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: plan
|
|
3
|
+
description: Compile a novel multi-domain task into a checked, approval-gated ephemeral composite that delegates selected library playbooks. Use when no single catalog workflow covers the task and composition has real value.
|
|
4
|
+
allowed-tools: mcp__plugin_owenloop_owenloop__list_workflows, mcp__plugin_owenloop_owenloop__search_workflows, mcp__plugin_owenloop_owenloop__get_workflow, mcp__plugin_owenloop_owenloop__create_workflow, mcp__plugin_owenloop_owenloop__start_run, mcp__plugin_owenloop_owenloop__pending_gates, mcp__plugin_owenloop_owenloop__provide_input, mcp__plugin_owenloop_owenloop__get_status, mcp__plugin_owenloop_owenloop__delete_workflow, mcp__owenloop__list_workflows, mcp__owenloop__search_workflows, mcp__owenloop__get_workflow, mcp__owenloop__create_workflow, mcp__owenloop__start_run, mcp__owenloop__pending_gates, mcp__owenloop__provide_input, mcp__owenloop__get_status, mcp__owenloop__delete_workflow, Write, Bash(mktemp:*), Bash(owenloop:*), Bash(rm:*)
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# plan
|
|
8
|
+
|
|
9
|
+
`plan` is a compiler, not a worker. It turns a novel, multi-domain task into
|
|
10
|
+
one checked, ephemeral composite workflow, obtains an explicit human decision
|
|
11
|
+
from that composite's parked gate, and then hands the released run to the
|
|
12
|
+
selected crews. It never performs composite step work inline and never submits
|
|
13
|
+
artifacts for a composite run. After approval, execution belongs to the crews
|
|
14
|
+
and supervision belongs to `conduct` or `shift`.
|
|
15
|
+
|
|
16
|
+
This is deliberately a mixed MCP-plus-CLI permission surface: MCP discovers,
|
|
17
|
+
publishes, reads back, parks, and releases live definitions; the narrowly
|
|
18
|
+
scoped `owenloop` CLI performs the local full-closure model check. `Write` and
|
|
19
|
+
the three scoped shell prefixes are only for staging that checked closure. Do
|
|
20
|
+
not use an unscoped shell, `Edit`, worker lifecycle tools, or a conversational
|
|
21
|
+
substitute for the durable gate.
|
|
22
|
+
|
|
23
|
+
## Decision gate
|
|
24
|
+
|
|
25
|
+
Use this compiler only when **no single catalog definition covers the task**
|
|
26
|
+
and composition has meaningful value: normally at least two inspected library
|
|
27
|
+
playbooks plus one coherent bespoke gap. If one existing playbook fits, use it
|
|
28
|
+
directly. If the work cannot be expressed as one coherent composite, explain
|
|
29
|
+
that limitation rather than forcing a graph.
|
|
30
|
+
|
|
31
|
+
Never invent rejected candidates. A definition may appear in the plan only
|
|
32
|
+
after it was returned by discovery and inspected with `get_workflow`.
|
|
33
|
+
|
|
34
|
+
## Discover and select real library definitions
|
|
35
|
+
|
|
36
|
+
1. Call `list_workflows` first. This is the catalog baseline and, with
|
|
37
|
+
`include_ephemeral: true`, is also the later collision check.
|
|
38
|
+
2. Call `search_workflows` to narrow the catalog by the task's domains and
|
|
39
|
+
likely interfaces. Search results are leads, not proof of compatibility.
|
|
40
|
+
3. Call `get_workflow` for every promising candidate before selecting it.
|
|
41
|
+
Read each declared input, single public output, version, content hash,
|
|
42
|
+
Mermaid, and whether it is a usable live definition.
|
|
43
|
+
4. Select only compatible targets whose declared child input can be produced
|
|
44
|
+
after approval. Record every considered definition, selected or not.
|
|
45
|
+
|
|
46
|
+
Generate a legal lowercase collision-safe root name, for example
|
|
47
|
+
`eph-plan-<short-task-slug>-<unix-ms>-<random-hex>`. Refuse an exact-name
|
|
48
|
+
collision from the inclusive listing. A successful inclusive listing is **not**
|
|
49
|
+
remote capability attestation: `create_workflow({ yaml, ephemeral: true })`
|
|
50
|
+
performs the remote ephemeral preflight. Do not infer support merely because a
|
|
51
|
+
local tool lists a field.
|
|
52
|
+
|
|
53
|
+
## Compile one canonical `compiledPlan` artifact
|
|
54
|
+
|
|
55
|
+
Make the root declare `task`, `compiledPlan`, and `planApproval` as inputs.
|
|
56
|
+
`compiledPlan` is a schema-bearing `seedOwed` input supplied at start; it is
|
|
57
|
+
the single authoritative plan artifact, not an adjacent prose rationale. Its
|
|
58
|
+
schema must be closed wherever its fields are known and require at least the
|
|
59
|
+
following shape (add task-specific schema detail without weakening it):
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
name: compiledPlan
|
|
63
|
+
seedOwed: true
|
|
64
|
+
producer: plan-compiler
|
|
65
|
+
schema:
|
|
66
|
+
type: object
|
|
67
|
+
required: [brief, launchInputs, candidates, selectedTargets, rootYaml, checkJson, checkSummary, mermaid, publishedRoot]
|
|
68
|
+
properties:
|
|
69
|
+
brief: { type: string, minLength: 1 }
|
|
70
|
+
launchInputs: { type: object, minProperties: 1 }
|
|
71
|
+
candidates:
|
|
72
|
+
type: array
|
|
73
|
+
minItems: 2
|
|
74
|
+
items:
|
|
75
|
+
type: object
|
|
76
|
+
required: [coordinate, selected, reason]
|
|
77
|
+
properties:
|
|
78
|
+
coordinate: { type: string, minLength: 1 }
|
|
79
|
+
selected: { type: boolean }
|
|
80
|
+
reason: { type: string, minLength: 1 }
|
|
81
|
+
additionalProperties: false
|
|
82
|
+
selectedTargets:
|
|
83
|
+
type: array
|
|
84
|
+
minItems: 2
|
|
85
|
+
items:
|
|
86
|
+
type: object
|
|
87
|
+
required: [coordinate, name, version, contentHash]
|
|
88
|
+
properties:
|
|
89
|
+
coordinate: { type: string, minLength: 1 }
|
|
90
|
+
name: { type: string, minLength: 1 }
|
|
91
|
+
version: { type: integer, minimum: 1 }
|
|
92
|
+
contentHash: { type: string, minLength: 1 }
|
|
93
|
+
additionalProperties: false
|
|
94
|
+
rootYaml: { type: string, minLength: 1 }
|
|
95
|
+
checkJson: { type: string, minLength: 1 }
|
|
96
|
+
checkSummary:
|
|
97
|
+
type: object
|
|
98
|
+
required: [completable, bounded, deadlocks, stallStates, stuck, structurallyDeadSteps, unreachedSteps, invariantViolations]
|
|
99
|
+
properties:
|
|
100
|
+
completable: { const: true }
|
|
101
|
+
bounded: { const: false }
|
|
102
|
+
deadlocks: { type: array, maxItems: 0 }
|
|
103
|
+
stallStates: { type: array, maxItems: 0 }
|
|
104
|
+
stuck: { type: array, maxItems: 0 }
|
|
105
|
+
structurallyDeadSteps: { type: array, maxItems: 0 }
|
|
106
|
+
unreachedSteps: { type: array, maxItems: 0 }
|
|
107
|
+
invariantViolations: { type: array, maxItems: 0 }
|
|
108
|
+
additionalProperties: false
|
|
109
|
+
mermaid: { type: string, minLength: 1 }
|
|
110
|
+
publishedRoot:
|
|
111
|
+
type: object
|
|
112
|
+
required: [name, version, contentHash]
|
|
113
|
+
properties:
|
|
114
|
+
name: { type: string, minLength: 1 }
|
|
115
|
+
version: { type: integer, minimum: 1 }
|
|
116
|
+
contentHash: { type: string, minLength: 1 }
|
|
117
|
+
additionalProperties: false
|
|
118
|
+
additionalProperties: false
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`candidates` contains exactly the definitions actually considered. An item can
|
|
122
|
+
be `selected: false` only when that candidate was returned and inspected; its
|
|
123
|
+
non-empty `reason` explains the compatibility, coverage, or selection choice.
|
|
124
|
+
The read-back name, version, and content hash in `selectedTargets` pin the
|
|
125
|
+
called definitions, while `publishedRoot` pins the resulting composite.
|
|
126
|
+
|
|
127
|
+
The separate human input must remain owed at launch and be an object, never a
|
|
128
|
+
bare boolean:
|
|
129
|
+
|
|
130
|
+
```yaml
|
|
131
|
+
- name: planApproval
|
|
132
|
+
seedOwed: true
|
|
133
|
+
producer: human
|
|
134
|
+
schema:
|
|
135
|
+
type: object
|
|
136
|
+
required: [approved]
|
|
137
|
+
properties:
|
|
138
|
+
approved: { const: true }
|
|
139
|
+
notes: { type: string }
|
|
140
|
+
additionalProperties: false
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Every execution path must stay downstream of this debt. The first executable
|
|
144
|
+
bespoke step consumes `task`, `compiledPlan`, and `planApproval`; it performs
|
|
145
|
+
real task decomposition and produces the typed inputs used by every selected
|
|
146
|
+
`calls:` step. No other step may consume a separately seeded input that makes
|
|
147
|
+
it eligible before approval. Each `calls:` entry maps a declared child input
|
|
148
|
+
to one of those post-approval artifacts and exposes that child's single
|
|
149
|
+
declared output. Fan the called results into a bespoke synthesis/final step.
|
|
150
|
+
|
|
151
|
+
For a canned proof, re-read the live catalog before choosing them; current
|
|
152
|
+
`research` and `investigate` are likely candidates because each accepts one
|
|
153
|
+
`request` input and exposes one `report` output. A suitable root has an
|
|
154
|
+
approval-gated bespoke `decompose` step, both library `calls:`, and a bespoke
|
|
155
|
+
`synthesize` step. Do not pretend a no-op gate is the bespoke work.
|
|
156
|
+
|
|
157
|
+
If the composite allocates a workspace, account, deployment, or other
|
|
158
|
+
resource, include an appropriate deprovision/cleanup step and an `onCancel:`
|
|
159
|
+
declaration with the exact artifacts it needs. A declined plan is cancelled;
|
|
160
|
+
its declared cleanup/deprovision path must be allowed to run before retirement.
|
|
161
|
+
|
|
162
|
+
## Model-check the complete exact calls closure
|
|
163
|
+
|
|
164
|
+
`create_workflow` is a parse-and-load gate, not a model check. Before
|
|
165
|
+
publication, create one unique temporary definitions directory **outside the
|
|
166
|
+
repository** with `mktemp`. Write the exact proposed root YAML and every exact
|
|
167
|
+
selected `calls:` target into that staging universe, preserving the qualified
|
|
168
|
+
or versioned identifiers actually used by the root. Do not silently rewrite a
|
|
169
|
+
target to a bare name merely to make validation pass. If the exact catalog
|
|
170
|
+
closure cannot be represented locally, stop and report that model-checking is
|
|
171
|
+
blocked.
|
|
172
|
+
|
|
173
|
+
Run both commands against the complete staged closure:
|
|
174
|
+
|
|
175
|
+
```sh
|
|
176
|
+
owenloop lint --defs <staging-dir>
|
|
177
|
+
owenloop check <composite-name> --defs <staging-dir> --format json
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Parse and retain the full check JSON; exit zero alone is not success. Require
|
|
181
|
+
`completable === true`, `bounded === false`, and empty `deadlocks`,
|
|
182
|
+
`stallStates`, `stuck`, `structurallyDeadSteps`, `unreachedSteps`, and
|
|
183
|
+
`invariantViolations`. Revise the exact YAML and rerun the full closure on any
|
|
184
|
+
validation error or non-clean field. `owenloop graph <composite-name> --defs
|
|
185
|
+
<staging-dir> --format mermaid` may help diagnose local wiring, but the
|
|
186
|
+
human-facing Mermaid must come from the later `get_workflow` read-back. Remove
|
|
187
|
+
only that exact temporary directory with `rm` after capturing the clean JSON.
|
|
188
|
+
|
|
189
|
+
## Publish, park, present, and release
|
|
190
|
+
|
|
191
|
+
Follow this order exactly:
|
|
192
|
+
|
|
193
|
+
1. Call `create_workflow` with the clean exact root YAML and `ephemeral: true`.
|
|
194
|
+
2. Call `get_workflow` for the generated name. Require `ephemeral: true` and
|
|
195
|
+
the expected name, version, and content hash. A create success alone is not
|
|
196
|
+
enough. Take the human-facing Mermaid from this read-back.
|
|
197
|
+
3. Finalize `compiledPlan` with the root YAML, full clean check JSON and
|
|
198
|
+
summary, structured candidates, selected-target identities, Mermaid, and
|
|
199
|
+
published-root identity.
|
|
200
|
+
4. Call `start_run` with `task`, `compiledPlan`, and every other required
|
|
201
|
+
seeded launch value, but deliberately omit `planApproval`.
|
|
202
|
+
5. Immediately call `get_status`. Require `eligible: []`; then call
|
|
203
|
+
`pending_gates` and require an owed `planApproval` gate for this exact
|
|
204
|
+
workflow. If a step is eligible or that gate is absent, do not claim
|
|
205
|
+
approval safety or proceed.
|
|
206
|
+
6. Present the exact `compiledPlan`, read-back Mermaid, candidate rationale,
|
|
207
|
+
and parked workflow identity to the human. Gate visibility is evidence that
|
|
208
|
+
the run is parked, not approval.
|
|
209
|
+
7. On explicit approval, call `provide_input` for `planApproval` exactly once
|
|
210
|
+
with the schema-valid affirmative object. Call `get_status` again and
|
|
211
|
+
require the intended first step to be eligible or already claimed, proving
|
|
212
|
+
release.
|
|
213
|
+
8. On decline, do not provide the input. Run `owenloop cancel <workflow>
|
|
214
|
+
--reason "compiled plan declined"`, report cancellation and cleanup state,
|
|
215
|
+
and retire only after terminal cleanup.
|
|
216
|
+
9. On approval, hand the live run to selected crews and `conduct`/`shift`.
|
|
217
|
+
|
|
218
|
+
The parked instance intentionally occupies an inbox/quota slot before
|
|
219
|
+
approval. Do not create a pre-run approval workflow to avoid that consequence.
|
|
220
|
+
|
|
221
|
+
## Retire the ephemeral definition safely
|
|
222
|
+
|
|
223
|
+
Only after a terminal run, call `get_workflow` again and compare its name,
|
|
224
|
+
version, and content hash with the values recorded at publication. If any
|
|
225
|
+
differ, do not delete: a concurrent publisher owns the live pointer. If they
|
|
226
|
+
match, call `delete_workflow` once. Historical pinned definition versions are
|
|
227
|
+
not retired. Report exact preflight, read-back, check, cancellation, or delete
|
|
228
|
+
refusals rather than guessing that cleanup succeeded.
|
|
229
|
+
|
|
230
|
+
## Evidence to preserve
|
|
231
|
+
|
|
232
|
+
For a canned multi-domain execution, preserve the exact composite YAML, full
|
|
233
|
+
check JSON, read-back Mermaid, parked `eligible: []` status, matching pending
|
|
234
|
+
gate, one approval/release status, and final run id/status. If the live hub,
|
|
235
|
+
library definitions, routes, or crews prevent execution, preserve the exact
|
|
236
|
+
blocker; do not replace it with a smaller claim.
|