75%

Engine extension contract — platform spec for future workflow migrations

Goal

  • Deliver the machine-validated extension specification future plans follow to migrate /tpr-review, /tp-help, /create-plan, and every remaining public skill/command onto the engine through a stateful workflow, one-shot service, or context/reference capability.
  • Prove the contract against the workflows this plan ships.

Implementation sketch

  • Author spec/extension-contract.md: the smallest artifact set for each target shape; the paired closed domain_artifact | virtual_root | protocol_root authority set; initial/reachable reconcile and settled-effect returns where applicable; nodes, gates, actions, receipt-bound cursors, invoke/capability/return contracts, finalizers, gate classes; LogicGate/Action/Banner metadata and registration; all ContextAssembly catalog rows and typed read-only lookup services; declarative capability requests; sanctioned domain-writer ownership; and explicit rejection of fabricated state/authority.
  • Codify the extension gate: a new primitive KIND reopens the sec-10.1 vocabulary go/no-go enumeration BEFORE the extension lands (wire to the vocabulary-go-no-go verifier).
  • BANNED for extensions (mirrors mission.md §Extension contract): parallel selectors, engine-core edits for workflow-specific behavior, client-side routing or lifecycle decisions, any goal/loop operation beyond exact ContinueRuntimeAPI.read plus unchanged current/next delivery, client/goal/loop state as domain truth, model-authored control prompts, predicate logic in JSON, a second reminder/prompt-assembly path, bespoke run_sub_sm-style invocation, or any completion report other than the engine’s sealed TerminalReceipt.
  • Implement verify_extension: machine-check a candidate extension (only the workflow/components/catalog/service artifacts its shape needs) — schema-validate the paired closed authority set; require reconcile/settlement and sanctioned semantic writers where applicable; enforce protocol_root’s one-shot/no-domain-state restrictions; reject successor Action args, incomplete invokes, fabricated artifacts/state, unresolved catalog/reminder references, virtual-root plan writes, unbound cursors, undeclared keys, or missing registry/vocabulary coverage.
  • Prove every workflow this plan ships (work_item, section, plan, plan_start, ledger_grind, bug, tooling, review, virtual_batch, root_closeout) passes verify_extension.
  • Record the exhaustive live skill/command inventory with one classified target shape per public name, plus detailed targets for /tpr-review, /tp-help, and /create-plan; NO migration executes from that pointer document.

Spec references

  • plans/workflow-engine-rework/spec/workflow-state-machines.md sec 10.1 (vocabulary go/no-go), sec 10.2 (pluggable component architecture, ComponentMetadata, workflow.schema.json), sec 11.2 (component metadata contract + boundary I/O validation).
  • plans/workflow-engine-rework/mission.md §Extension contract.

Test strategy / acceptance

Acceptance: verify_extension rejects every banned shape including fabricated state/authority, proves the paired protocol_root reopen across schema/root/vocabulary/verifier/spec coverage, passes every shipped workflow, validates catalog-only/read-only service extensions without demanding workflow JSON, and the inventory verifier reconciles every live skill/command name in both directions.

Gates: sc-e0c0a001 verifies extension shape and shipped workflows; sc-bd576701 verifies new-KIND vocabulary reopening; sc-e7e30c01 verifies durable always-loaded discoverability.

Work Items

  • Author spec/extension-contract.md covering all three target shapes, paired state authorities including protocol_root, reconcile/settlement and semantic-writer rules, receipt-bound cursors, declarations/interfaces/registration, service/result and ContextAssembly catalogs, capability requests, and banned fabricated-state/parallel-owner shapes
  • Implement verify_extension by GENERALIZING the engine’s existing closed-contract verifier family (verify_vocabulary_manifest.verify, verify_scenario_inventory.verify, verify_bug_fold_manifest.verify, contract_validation.validate_engine_contract) — reuse their load-closed-sets -> schema/shape-validate -> reconcile-declared-vs-registered -> fail-closed skeleton (mirrored on intel_repo/scripts/verify_graph_contract.py’s CONTRACT/SCHEMA_PATH/verify_snapshot/_mismatch shape) instead of authoring a parallel verifier. Consume workflow.schema.json as the schema layer and registry-resolve READ-ONLY against ComponentRegistry/discover_components and the sibling closed constant sets (REGISTRABLE_KINDS, VOCABULARY_KINDS, STATE_AUTHORITIES) — never mutate them, they are self-hosting this plan’s own execution. Layer the cross-field checks over workflow JSON + components + mappings: initial/reachable reconcile plus reconcile return targets and sanctioned semantic-result writers for domain workflows; reject successor-state Action args and incomplete invoke contracts; resolve every Reminder activation against the correct condition/fact/state/action class; require a VirtualBatchDescriptor and prohibit plan writes for virtual-root workflows; reject any unbound durable cursor/state; registry-resolve every referenced name, ComponentMetadata shape, capability declarations, no undeclared node keys, vocabulary-manifest coverage row present.
  • Prove every shipped workflow passes verify_extension and add one negative pin per banned extension shape
  • Record and machine-reconcile the exhaustive live skill/command inventory, classify every public surface, and provide detailed /tpr-review, /tp-help, and /create-plan target pointers (no migration execution here)
  • Wire the new-KIND extension gate to CALL verify_vocabulary_manifest’s existing go/no-go reopen contract (sibling section s-6c1f9f03: GO_NO_GO_VERDICTS, GO_NO_GO_REOPEN_TRIGGER_COUNT, _validate_go_no_go_verdict — requires recorded_by + recorded_date + reopen_contract + exactly 3 non-empty reopen_triggers) rather than re-encoding the enumeration or trigger count locally — a candidate extension declaring a primitive KIND outside the closed LogicGate/Action/Banner set flips the sec-10.1 vocabulary go/no-go verdict to reopened BEFORE the extension is admitted.
  • Publish durable discoverability pointers so future migration plans find the engine from always-loaded surfaces: missions.md engine mission entry, a CLAUDE.md/.claude/rules pointer naming spec/extension-contract.md + verify_extension + the generated —docs command, and sync of each migrated workflow’s skill/rule surface to consume the engine dispatch path (a future /tpr-review, /tp-help, or /create-plan migration plan must discover the extension contract without reading this plan’s directory)

Fresh intel (regenerated)

verify_extension is NOT a new verifier shape — it is the fifth member of an in-house verifier family the engine already ships four times (verify_vocabulary_manifest.verify, verify_scenario_inventory.verify, verify_bug_fold_manifest.verify, and the mega-hub contract_validation.validate_engine_contract), all confirmed live in the ori-platform graph, and it is the per-extension generalization of the exact “declare a closed contract, schema-validate a candidate, reconcile declared-vs-registered, report every mismatch, fail closed” shape that intel_repo/scripts/verify_graph_contract.py (CONTRACT + SCHEMA_PATH + verify_snapshot + _mismatch) and scripts/plan_corpus/{schema,validate,route_check}.py already prove. The section’s job is UNIFICATION, not invention — exactly as its own thesis states.

The single most important [JOIN]: callable-risk ranks the three sibling verify() entry points + validate_engine_contract as the top-fanout, top-betweenness callables in the terrain (validate_engine_contract hs=4674 / betweenness=1184; verify_vocabulary_manifest.verify hs=2918 / fanout=14 / betweenness=1222), AND call-neighborhood shows those same hubs are consumed read-only by dozens of engine sites (from_dict, build_section_registry, build_plan_registry, canonical_digest) — so every registry verify_extension reconciles against is self-hosting this very run and MUST stay read-only.

Decisions this package forces before any code is written:

  1. Model verify_extension on the sibling-verifier + verify_graph_contract shape (schema-validate + cross-field reconcile + report + fail-closed) — a parallel verifier is LEAK:algorithmic-duplication (SS 3H). The four siblings are all live in-graph; consume workflow.schema.json as the schema layer and layer cross-field reconcile on top, mirroring engine_validation.py’s _validate_choice/_validate_task/_validate_terminal split.
  2. Every registry verify_extension reconciles against is READ-ONLY and self-hosting (SS 3.1 / SS 3.3): ComponentRegistry / discover_components (registry.py), the closed constant sets in contract_validation.py + registry.py (REGISTRABLE_KINDS, VOCABULARY_KINDS, STATE_AUTHORITIES), and the plan_orchestrator / commit_push locked registries. registry-resolve against them; NEVER mutate.
  3. The banned-shape rejections are the deliverable, on an INVERTED-TDD-sensitive surface (SS 3H): each banned extension shape needs a negative pin that FAILS pre-implementation, and the positive pins (every shipped workflows/*.json passes) MUST NOT be weakened to green the gate. verify_extension has ZERO acceptance test today (only test_extension_contract_doc.py, the doc-coherence pin, exists) — greenfield TDD surface.
  4. The new-KIND gate CALLS the sibling _validate_go_no_go_verdict, it does not re-encode it (SS 4). verify_vocabulary_manifest.py owns the reopen contract (GO_NO_GO_VERDICTS = {"bounded-closed","reopened"}, GO_NO_GO_REOPEN_TRIGGER_COUNT = 3); re-encoding the enumeration is LEAK:scattered-knowledge.
  5. w-7e30c808 durable-discoverability touches always-loaded governance surfaces (missions.md, CLAUDE.md/.claude/rules) under NO PROSE + proposal-governance discipline; normal bug and tooling routing applies.
["validate_engine_contract", "discover_components", "ComponentRegistry", "_validate_go_no_go_verdict", "GO_NO_GO_VERDICTS", "GO_NO_GO_REOPEN_TRIGGER_COUNT", "REGISTRABLE_KINDS", "VOCABULARY_KINDS", "DEFAULT_BANNED_ACTIONS", "REGISTERED_HALT_STATES", "EXIT_REASON_ROUTING"]

DIG DEEPER

python -m scripts.plan_corpus.read --summary plans/workflow-engine-rework
./scripts/intel-query.sh plan-status workflow-engine-rework

(full dossier: engine-extension-contract-platform-spec-for-future-workflow—s-dac3b97f.intel.md)