100%

Plan-start migration — sec 1.5 A-E bands into the engine

Goal

  • Migrate root-entry and child-entry paths into workflows/plan_start.json.
  • Original invocation creates/resumes RootClosure.
  • Nested entry validates a child capability and pushes a frame.
  • Route every handoff through ContextAssembler.

Self-hosting constraint

On the new engine. The A-E band primitives are the same vocabulary; this is wiring (workflows/plan_start.json) + porting the harvested plan-start scenarios, not new KINDs.

Implementation sketch

  • plan_start.json: after EntryEnvelope root-create/resume/child admission, enter a fixed reconcile node that reads current plan/tracker state and drives the A-E bands as guarded transitions; each settled Action/invoke/cancellation returns there; each box -> its sec-10.1 Action + guarding LogicGate (per the doc’s A-E overlay).
  • Zeroed scrutiny is per-section JIT: zeroed_section_review_required targets generic push_invocation for /review-section through review_as_phase; fold its typed return, then serve section work. No plan-wide hard block/fan-out.
  • Resolve detour/advisory/next-action guidance through Reminder mappings.
  • Use child push/pop with a typed ReturnContract for every related cross-plan/bug/review workflow that must fold and resume; reserve issue_pivot_token for root abandonment/replacement; use fire-and-forget dispatch only for effects with no workflow return.
  • Preserve the current root/frame capability and halt for clarification on ambiguous user direction.
  • Require EntryEnvelope on root/child/resume ingress; never discover an active root from ambient state.
  • Reject unrelated dirty-worktree/scratch plan identities and unauthorized --override targets.
  • Remove write-on-serve: no not-started->in-progress flip on serve; the work-item SM owns a reconcile-selected mark_in_progress Action before do-work dispatch.
  • Port the harvested plan-start scenarios; re-sync from main first (plan-start is heavily touched by ongoing tooling updates).

Spec references

  • plans/workflow-engine-rework/spec/workflow-state-machines.md sec 1.5 (plan-start A-E + write-on-serve change). Research anchors: route_walk serve path review_as_phase; drains fire when walk returns none.

Test strategy / acceptance

Matrix: root create/replay/resume/child entry x capability x direction x zeroed/normal x section review state. Pins: every admitted entry and settled effect reconciles from plan/tracker state; every returning workflow edge has invoke/capability/ReturnContract metadata and never uses dispatch; pivot uses typed abandonment/new-root authority; no ambient or unbound frame cursor selects a band; serve does not flip; zeroed review is per-section JIT; replay preserves root; unauthorized child/pivot rejects.

Work Items

  • Implement explicit EntryEnvelope routing for request-idempotent root create, exact closure resume, and parent-capability child entry
  • workflows/plan_start.json: fixed plan/tracker-derived reconcile entry, all settled effects returning through it, and A-E bands as guarded transitions over the sec-10.1 primitives; returning workflow edges use invoke/ReturnContract, no-return effects alone use dispatch
  • Map zeroed_section_review_required to generic review-section invocation, fold its review_as_phase return before section work, and prohibit plan-wide forensic hard-block/fan-out
  • Map bug-child detour as generic invocation with origin work item, child capability, local-acceptance ReturnContract, parent reconcile target, and root-owned tracker/archive closeout
  • Remove write-on-serve flip; in-progress is a reconcile-selected work-item Action before do-work dispatch
  • Port the harvested plan-start scenarios (re-sync from main first)
  • Route every A-E handoff and API response through the single ReminderResolver seam; remove hand-composed reminder text from plan-start wiring
  • Require child capabilities for related target changes and root-abandon authorization for pivots; ambiguous wording/worktree state cannot alter root or frame

Fresh intel (regenerated)

This is NOT new-primitive work — it is integration wiring that sits at the DELIVERY end of the engine build. Every primitive plan_start.json composes (EntryEnvelope, RootClosure, InvocationFrame, ContextAssembler, ReminderResolver, ReturnContract, the sec-10.1 Action/LogicGate vocabulary, push_invocation/invoke/dispatch) is BUILT by predecessor sections (walking-skeleton s-951de451, engine-core s-e585be74, work-item-slice s-051a0f91, section-gate-nesting-zero s-4575d22d, rails-components s-b6c8160c) — verified ZERO of them exist in scripts/ today. This section’s job is to express the CURRENT roadmap.py plan-start behavior (sec 1.5 A-E) as engine JSON, faithfully, minus one deliberate change (write-on-serve removal).

The single most important [JOIN]: the graph shows the sec-1.5 behavior is TODAY smeared across a monolithic roadmap.py (_enrich_route_envelope_for_execution at 937 is ~800 lines; the whole file co-changes as one unit, support 48) PLUS a heal-dispatch quadruplet of “identical shape” files (intel_heal_dispatch / coordinate_heal_dispatch / review_restale_dispatch + heal_sentinel). The migration’s leverage is exactly the collapse the graph nominates: serve-time heals + advisories + rails guidance route through ONE ReminderResolver seam (work item w-a3fa462f), and the write-on-serve flip (serve_next_v7 ~ peek_next_v7 at 0.913 — the write/read twin) becomes a reconcile-selected mark_in_progress Action (w-3912eb72).

Decisions this package forces before any work:

  1. Build OFF-PATH — do NOT edit the live serve path. Per the strangler-fig self-hosting constraint (mission.md §Self-hosting; walking-skeleton “keep live route_walk.py/review_phase.py untouched until reversible cutover”), serve_next_v7, roadmap._route_dispatch, _enrich_route_envelope_for_execution, verify_and_complete_v7 stay LIVE and UNTOUCHED. Cutover is sections 18-19 (reversible-cutover, hardening-retire), not this one. The write-on-serve removal is TARGET behavior expressed in workflows/plan_start.json, not a live-code edit here.
  2. Reuse the §07A.3 CAS status writer — never fork it. The new mark_in_progress Action MUST route through the existing flip_work_item_status CAS+flock path (route_walk.py:744 docstring: “the single status-transition entry point”). A parallel status writer is LEAK:algorithmic-duplication + a state-authority violation.
  3. Consume, don’t re-encode. plan_start.json reads plan/tracker state through scripts.plan_corpus.read (mission.md §rails ABSOLUTE) — never a shadow plan-status store. Every returning workflow edge carries invoke/capability/ReturnContract; dispatch is fire-and-forget ONLY.
  4. This section is reviewed: false — a JIT /review-section (forced mission-fit) fires at serve. Its dossier (this file) feeds the R2 binding-constraint route check; the constrained-symbols block below is the do-not-touch feed.
["serve_next_v7", "peek_next_v7", "_route_dispatch", "_enrich_route_envelope_for_execution", "flip_work_item_status", "verify_and_complete_v7", "complete_work_item_v7"]

DIG DEEPER

python -m scripts.plan_corpus.read --summary plans/workflow-engine-rework
scripts/intel-query.sh dag-ascii workflow-engine-rework
sed -n '171,293p' plans/workflow-engine-rework/spec/workflow-state-machines.md   # sec 1.5 A-E + target mapping

(full dossier: plan-start-migration—s-685c8e84.intel.md)