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.
Files changed (86) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1200 -166
  28. package/dist/src/defs.d.ts +41 -1
  29. package/dist/src/defs.js +461 -92
  30. package/dist/src/engine.d.ts +108 -22
  31. package/dist/src/engine.js +573 -85
  32. package/dist/src/factory.js +5 -3
  33. package/dist/src/hub.d.ts +77 -0
  34. package/dist/src/hub.js +162 -0
  35. package/dist/src/implements.d.ts +37 -0
  36. package/dist/src/implements.js +790 -0
  37. package/dist/src/index.d.ts +12 -10
  38. package/dist/src/index.js +7 -6
  39. package/dist/src/mcp/serve.js +254 -45
  40. package/dist/src/mcp/server.d.ts +10 -7
  41. package/dist/src/mcp/server.js +53 -8
  42. package/dist/src/model.d.ts +46 -10
  43. package/dist/src/model.js +224 -78
  44. package/dist/src/order-resolver.js +1 -0
  45. package/dist/src/store/def-source.d.ts +19 -0
  46. package/dist/src/store/def-source.js +87 -17
  47. package/dist/src/store/gc-recovery.d.ts +46 -0
  48. package/dist/src/store/gc-recovery.js +258 -0
  49. package/dist/src/store/gc.d.ts +94 -0
  50. package/dist/src/store/gc.js +563 -0
  51. package/dist/src/store/index.d.ts +3 -1
  52. package/dist/src/store/index.js +2 -0
  53. package/dist/src/store/install.d.ts +34 -5
  54. package/dist/src/store/install.js +73 -11
  55. package/dist/src/store/pre-commit-verifier.js +42 -2
  56. package/dist/src/store/snapshot-guard.d.ts +18 -0
  57. package/dist/src/store/snapshot-guard.js +94 -0
  58. package/dist/src/store.d.ts +66 -4
  59. package/dist/src/store.js +333 -12
  60. package/dist/src/types.d.ts +97 -17
  61. package/dist/src/types.js +4 -0
  62. package/dist/src/util.js +4 -1
  63. package/docs/authoring.md +214 -9
  64. package/docs/bundles.md +19 -0
  65. package/docs/cli.md +270 -30
  66. package/docs/crypto.md +13 -7
  67. package/docs/design.md +107 -46
  68. package/docs/evals/mcp-charter-baseline.json +428 -0
  69. package/docs/mcp-charter-eval.md +124 -0
  70. package/docs/shift-logs.md +18 -0
  71. package/docs/wire-contracts.md +28 -7
  72. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  73. package/examples/workflows/ship.yaml +28 -2
  74. package/package.json +2 -1
  75. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  76. package/plugins/claude-code/plugin/.mcp.json +1 -1
  77. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  78. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  79. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  80. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  81. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  82. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  83. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  84. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  85. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  86. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
@@ -31,7 +31,7 @@
31
31
  # wf=$(owenloop create compile-dev-playbook \
32
32
  # --provide brief='{"task":"add Stripe subscription billing to a Node/TypeScript app","category":"billing"}' \
33
33
  # | jq -r .workflow)
34
- # owenloop tick $wf # ... conduct to done (e.g. with the owenloop-conduct skill)
34
+ # owenloop tick $wf # ... conduct to done (e.g. with the conduct plugin skill)
35
35
  # # `approval` is a human gate before publish. Flying solo? Pre-approve at create:
36
36
  # # --provide approval='{"approved_by":"alex"}'
37
37
  # # Otherwise the instance parks blocked on it — durably, in SQLite — until:
@@ -33,8 +33,9 @@
33
33
  # ...
34
34
  # owenloop reject $wf pr --by reviewer --text "error path untested; add the 429 case"
35
35
  #
36
- # Or hand it to an agent: the owenloop-conduct skill (skills/owenloop-conduct)
37
- # drives an instance to done, one fresh subagent per order.
36
+ # Or hand it to the `conduct` plugin skill, which supervises this workflow through a
37
+ # scoped Shift, checks status, and relays human gates. The Shift starts `agent-run`
38
+ # workers for agent orders.
38
39
  #
39
40
  # Scaffolding hygiene: if the db (.owenloop/) and this defs dir live inside
40
41
  # the repo the workflow ships changes to, gitignore them first — a builder
@@ -49,6 +50,31 @@ title: Ship — the software production line
49
50
  description: Plan + provision → build → review → document → check → merge → clean up. Lifecycle bracketed as owned artifacts; reviewer knock-backs; terminal merge.
50
51
  outputs: [merge]
51
52
 
53
+ x:
54
+ discovery:
55
+ description: >-
56
+ Ship an approved repository change through planning, provisioning, building,
57
+ review, documentation, checks, merge, and cleanup on the production line.
58
+ whenToUse:
59
+ - Ship an approved software change through the full repository production line.
60
+ - Need a branch, review, verification, and a merge for a repository change.
61
+ notFor:
62
+ - Unapproved ideation or work that still needs a plan or approval.
63
+ - Non-software workflows that do not change a repository.
64
+ - Work that must not be merged.
65
+ interface:
66
+ inputs:
67
+ - name: proposal
68
+ summary: The approved change brief that seeds planning and provisioning.
69
+ schemaRef: "#/inputs/0/schema"
70
+ - name: planSeed
71
+ summary: Optional existing-plan or branch-adoption information for continuing work.
72
+ schemaRef: "#/inputs/1/schema"
73
+ outputs:
74
+ - name: merge
75
+ summary: The terminal record that confirms the approved pull request was merged.
76
+ schemaRef: "#/steps/6/produces/0/schema"
77
+
52
78
  inputs:
53
79
  - name: proposal # the approved brief, seeded at create
54
80
  seedOwed: true
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.9",
3
+ "version": "0.5.11",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",
@@ -55,6 +55,7 @@
55
55
  "owenloop": "node bin/owenloop.mjs",
56
56
  "test": "node --test --test-reporter=spec test/*.test.ts packages/work/test/*.test.ts",
57
57
  "test:quiet": "node --test test/*.test.ts packages/work/test/*.test.ts",
58
+ "eval:mcp-charter": "node test/mcp-charter-eval.ts",
58
59
  "test:crypto": "node --test test/crypto-dsse.test.ts test/crypto-allowed-signers.test.ts test/crypto-ssh.test.ts test/crypto-keys.test.ts",
59
60
  "typecheck": "tsc --noEmit",
60
61
  "lint": "eslint src packages/work/src",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.9",
3
+ "version": "0.5.11",
4
4
  "description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
5
5
  "author": {
6
6
  "name": "Typical Day"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.9"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.11"
11
11
  }
12
12
  }
13
13
  }
@@ -41,6 +41,28 @@ run `claude mcp list` to confirm the real names before proceeding.
41
41
  7. **Offer `start_run`** once approved and free of lint errors, with any inputs
42
42
  the human already knows they want to seed.
43
43
 
44
+ ## Interview, compile, and approve the process
45
+
46
+ Keep the interview conversational and just detailed enough to name the graph. Ask
47
+ for the end result, starting input, the work and artifact each step creates,
48
+ quality or rejection gates, work repeated per item, possible forks, and each human
49
+ decision. Do not over-interview: once the graph is nameable, draft it and let the
50
+ human correct the draft.
51
+
52
+ Compile answers into one coherent job per step. Name steps as roles or verbs and
53
+ artifacts as nouns; wire steps through the data they actually produce and consume,
54
+ not a hand-sequenced list. Each produced artifact should be consumed, declared as a
55
+ workflow output, or intentionally recorded as a generated sink. A straight process
56
+ with a quality loop is linear plus rejection; repeated item work is collection
57
+ map/reduce; an either/or decision is route/skip; reusable process pieces are
58
+ `include:` or `calls:`.
59
+
60
+ For approval, present a numbered process in the human's domain language rather than
61
+ YAML. Explicitly confirm the start, end, gates, forks, and human touchpoints. Revise
62
+ the draft, call `create_workflow` again, and re-present until it is approved. Probe
63
+ concrete failure cases (for example, a bad input or repeated rejection) so approval
64
+ is informed rather than polite.
65
+
44
66
  ## Step Agent dispatch and `x.harness`
45
67
 
46
68
  `owenloop work agent-run` is the only supported dispatcher for workflow Step
@@ -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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.9",
3
+ "version": "0.5.11",
4
4
  "description": "Codex plugin for the owenloop workflow engine.",
5
5
  "skills": "./skills/",
6
6
  "mcpServers": "./.mcp.json"
@@ -6,7 +6,7 @@
6
6
  "mcp"
7
7
  ],
8
8
  "env": {
9
- "OWENLOOP_PLUGIN_VERSION": "0.5.9"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.11"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",
@@ -41,6 +41,28 @@ run `claude mcp list` to confirm the real names before proceeding.
41
41
  7. **Offer `start_run`** once approved and free of lint errors, with any inputs
42
42
  the human already knows they want to seed.
43
43
 
44
+ ## Interview, compile, and approve the process
45
+
46
+ Keep the interview conversational and just detailed enough to name the graph. Ask
47
+ for the end result, starting input, the work and artifact each step creates,
48
+ quality or rejection gates, work repeated per item, possible forks, and each human
49
+ decision. Do not over-interview: once the graph is nameable, draft it and let the
50
+ human correct the draft.
51
+
52
+ Compile answers into one coherent job per step. Name steps as roles or verbs and
53
+ artifacts as nouns; wire steps through the data they actually produce and consume,
54
+ not a hand-sequenced list. Each produced artifact should be consumed, declared as a
55
+ workflow output, or intentionally recorded as a generated sink. A straight process
56
+ with a quality loop is linear plus rejection; repeated item work is collection
57
+ map/reduce; an either/or decision is route/skip; reusable process pieces are
58
+ `include:` or `calls:`.
59
+
60
+ For approval, present a numbered process in the human's domain language rather than
61
+ YAML. Explicitly confirm the start, end, gates, forks, and human touchpoints. Revise
62
+ the draft, call `create_workflow` again, and re-present until it is approved. Probe
63
+ concrete failure cases (for example, a bad input or repeated rejection) so approval
64
+ is informed rather than polite.
65
+
44
66
  ## Step Agent dispatch and `x.harness`
45
67
 
46
68
  `owenloop work agent-run` is the only supported dispatcher for workflow Step