IMPORTED_PATTERNS.md

Imported workflow patterns and execution contracts

Issue #105 requires the workflow patterns from WRKFLW, workflows, and this executor to be consolidated. The original four catalog entries did not meet that requirement. The canonical engine now includes the original BuildPlan/type contracts and the construction lifecycle adapters below, alongside those entries. This is a pattern and runnable-example migration; it does not recreate the archived web/mobile applications or claim that live services have been deployed.

The archived source is the authority for the patterns. Source provenance records the observed tree/blob hashes; all 18 inspected source files matched those tree entries. workflows/source_types.ts preserves its complete type definitions. ported/ retains the original API/schema/PRD snapshots for comparison. The original Next.js route imports are historical; the runnable canonical equivalents are workflows/imported.py, backed by the modules listed here. There are no missing alias imports in this Python execution path. Upstream graph execution, PDF extraction, general transcription and protocol clients contained simulated/placeholder outputs; those outputs are not treated as working integrations.

Coverage and trace

Source pattern	Original source	Canonical execution and evidence
Project, roles, 48-hour team invite/acceptance	WRKFLW PRD, flow “Create Project & Invite Team”; GraphQL Project/members	ConstructionLifecycle.create_project, invite, accept_invitation; accepted roles and token expiry tested
Timezone/time lookup	WRKFLW backend /api/timezones, /api/time	Real zoneinfo conversion, one aware UTC instant, explicit invalid-zone rejection
Offline daily log, media upload, sync, PM notification	WRKFLW PRD, “Capture Daily Log”	Actual bytes in durable SQLite queue; configured validation/signed upload/receipt; resumable sync and notification outbox
Task assignment, progress, comments/photo links, audit	WRKFLW PRD, “Receive & Update Task”; GraphQL createTask	Explicit membership/assignee checks, ordered states, actor/time history and completion event; tests execute all states
RFI draft/pending approval/open/closed and requested changes	WRKFLW PRD, “RFI Draft & Send”	Selected approver, independent approval, versioned history, revise/resubmit; notification recovery does not repeat transition
Daily retrieval, embeddings/index/search, cited summary draft, PM review/PDF	WRKFLW PRD, “AI Daily Summary Agent” and detailed AI section	Configured actual service adapters, explicit 24-72 hour retrieval window and scope/embedding/retrieval/citation validation; draft stored with provenance; PM review digest binds publication; real PDF bytes and storage receipts required
URL/video/PDF/Google Docs intake	workflows ingest route, fetcher/transcriber/pdf/doc helpers	Ingestor: bounded host-approved HTTP origins, HTML cleaning, pypdf extraction, Google caption/export OAuth contracts, direct media OpenAI ASR; no placeholder fallback
Executive summary and BuildPlan generation	workflows summarizer/planner services	WorkflowPlanner: real configured OpenAI request, original field schemas, no truncation fallback, strict graph checks; controlled transport tests retain source constraints and hash
Five agent kinds	workflows AgentKind/planner definitions	BuildPlanExecutor: sequential/parallel/loop child execution, actual LLM/registered custom handlers; explicit child membership and loop bound/condition where source omitted controls
Agent/task graph and dependency ordering	workflows WorkflowCompiler	Original round-robin assignment retained; unordered dependencies handled, cycles/missing IDs rejected; actual handler outputs flow to downstream tasks
MCP/A2A/AP2 contracts	workflows protocol clients and flags	MCP calls actual FastMCP; A2A calls the existing registered local agent; AP2 requires caller mandate, validating client, exact currency/vendor/limit and idempotency key. No demo mandate/payment/provider endpoint is invented
Plan-based scaffold, types, agents, protocols, Docker/config	workflows code-generator/utilities	generate_plan_scaffold: complete plan plus executable typed graph library, host bindings, strict config, portable library Dockerfile. Real compiler/Node tests execute generated dependency and correction code
Run/status/trajectory/tool calls/artifacts	workflows types, API routes/SQL contracts	WorkflowStore: explicit private SQLite file, status events, all attempts/tool calls, source/summary/plan links and complete saved artifact content; reopen/readback tests
Native orchestration and self-correction wrapper	executor orchestrator/executor/mutator	Shared bounded run_correcting, host-registered real Repair, built-in atomic approved-JSON-snapshot repair; every imported agent kind and native dispatch tested through failure → correction → successful retry; failure and opt-out tests
Repository archival	issue #105	Both source repositories were observed archived; fresh provider receipts are retained in the PR review packet

Running the examples

Use the repository's Python dependencies and Node 22 TypeScript compiler setup:

pip install -r requirements-ci.txt
npm ci --ignore-scripts --prefix tools/typescript-validation
python -m examples.build_plan_workflow --demo --database /tmp/workflow-example.sqlite3
python -m examples.construction_lifecycle --help

The demo performs a real local two-task calculation and saves its generated code artifacts. It is explicitly supplied example data, not a claimed AI-generated plan. For source intake, examples.build_plan_workflow --url ... --database ... --bindings your_app.bindings imports a trusted application module with configure(store). It supplies Ingestor, provider/client settings and task/composite bindings to ImportedWorkflows. No function name or Python import is taken from an ingested document. The external YAML definitions are auto-loaded as before.

To use the native engine, register engine.agents['imported_workflows'] = ImportedWorkflows(...) and select build_plan_pipeline. Its six steps retain intake, summary, plan, compilation, actual execution and saved scaffold generation. For WRKFLW, register ConstructionWorkflowAgent(lifecycle, authenticated_credentials, confirm=host_confirmation) as construction_lifecycle; select construction_action with an explicit operation/parameters or construction_project_onboarding. Invitation acceptance, summary review and publication remain separate authenticated operations. The host must authorize actions and supply real recipient identities; a source document cannot replace the authenticated principal or provide its own confirmation. The host confirmation callback must affirm the exact operation/parameters before the AI-facing adapter mutates server state.

Configuration and limits

• WorkflowPlanner reuses the repository's OPENAI_API_KEY connector setting; WORKFLOW_MODEL selects its model (source default gpt-4o-mini). Other providers can implement the planner interface. No paid call was made during automated checks. Provider response schemas and failure paths were tested with controlled HTTP transports.
• Source HTTP requires host-approved origins. Redirects are rejected. Private Google Docs/captions require an authorized OAuth token; direct media transcription requires a real audio/video resource. Vimeo/other webpage extraction needs a host-approved media extractor. Image-only PDFs require explicit OCR; empty text is an error. Resource limits are enforced, but this library is not a hardened multi-tenant document sandbox.
• The upstream BuildPlan lacks composite child membership and loop termination controls. The host supplies composites explicitly; missing controls fail. Agent handler names are a local registry, not arbitrary imports. A protocol flag describes a requirement; it grants no tool authority or payment permission. AP2's upstream client did not define a real endpoint/SDK, so the adapter calls a host-configured validating payment client and never invents a wire protocol.
• Construction auth, email/notification delivery, signed object storage, embeddings/vector service, LLM generation and PDF rendering/storage are host-owned adapters. Tests exercise real controlled local bytes, signing, vector indexing/search, delivery receipts and PDF files. They do not prove live S3/email/model delivery, mobile UI parity, or a deployed SaaS. The generate adapter must be backed by an actual provider; deterministic fixture summaries are confined to tests.
• The durable notification outbox preserves the exact authorized message for an explicit retry_notification; pending listings omit content. Its private database can contain invitation links and project data and must be protected by the host. Only token hashes are used as invitation IDs. SQLite is a local engine store, not a multi-worker hosted transaction service.
• Repair callbacks may change a failed operation's technical inputs or restore a host-approved snapshot. They cannot fabricate successful outputs. Construction adapter repair preserves every field of the original authenticated payload, including notification bodies and storage object keys; it may add technical settings without replacing source or destination fields. No-op repairs fail, unchanged invalid operations remain failed, and prior failed attempts remain visible. Completed child outputs are checkpointed within one execution, keyed by composite path and loop iteration; parallel children settle before failed children retry. A changed retry input that would invalidate a completed checkpoint fails for reconciliation. These in-memory checkpoints are not a cross-process resume promise. Observer/persistence and output-binding errors after successful work never trigger replay. Loop termination callbacks must be pure predicates. External service retries must honor idempotency keys. Native steps that create/approve records are not blindly replayed as whole actions; adapter correction and the outbox own recovery.
• A generated Dockerfile is a library packaging artifact. It does not select a deployment target, provide application-specific business handlers, or deploy a service. deployment_status=scaffold_only remains explicit even when artifact generation finishes.

Run pytest (with PYTHONPATH unset) for the actual source/graph/correction/provider/TypeScript/lifecycle checks. Hosted PR validation and any live provider acceptance remain separate from local code validation.