devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/prompts/integration/README.md

@@ -0,0 +1,185 @@
+# Integration prompt assembly: concrete runtime shape
+
+This directory contains two different kinds of prompt artifacts, and they do **not** play the same role.
+
+## 1) Stable node doctrine (`node_config/prompt.md`)
+
+For each integration node, `node_config/prompt.md` is loaded by:
+
+- `src/devflow_engine/integration/prompts.py` → `load_integration_node_instruction(node)`
+- consumed in `src/devflow_engine/integration/dag.py` via `get_agent_config()`
+
+Example:
+
+- `ResolveSideEffectsAndImplicatedUsersNode.get_agent_config()` loads `prompts/integration/resolve/node_config/prompt.md`
+- `ValidateEnrichGateNode.get_agent_config()` loads `prompts/integration/validate/node_config/prompt.md`
+
+**Current code-grounded reality:** this node doctrine is stored on `AgentConfig.instructions`, but the current integration runtime path does **not** inject that string into the JSON prompt envelope built by `run_agent_step(...)`.
+
+The vendored `AgentNode`/`AgentConfig` surface is currently a compatibility stub in:
+
+- `src/devflow_engine/vendor/datalumina_genai/core/nodes/agent.py`
+
+So `node_config/prompt.md` is best understood as **stable node doctrine / node contract documentation**, not as the literal prompt body the model sees.
+
+## 2) Stable stage prompt bullets (`<stage>/<prompt.md>`)
+
+These files *do* feed the assembled model payload.
+
+They are loaded by:
+
+- `src/devflow_engine/integration/prompts.py` → `load_integration_stage_guidance(stage_name)`
+- called from `src/devflow_engine/integration/agentic.py` → `run_integration_agent_step(...)`
+- passed into `src/devflow_engine/agentic_runtime.py` → `run_agent_step(...)`
+- serialized into the prompt envelope as `instructions`
+
+Examples:
+
+- `prompts/integration/resolve/resolve_side_effects/prompt.md`
+- `prompts/integration/validate/validate_enrich_gate/prompt.md`
+- `prompts/integration/red/red/prompt.md`
+- `prompts/integration/red/code_repair/prompt.md`
+
+## 3) Runtime-built context (`context_payload`)
+
+This is the largest injected component, and it is built in `src/devflow_engine/integration/dag.py` immediately before each agent call.
+
+Concrete examples:
+
+- Resolve node injects:
+  - `idea_id`
+  - `implemented_idea`
+  - `implemented_stories`
+  - `code_evidence`
+  - `source_docs`
+  - `canonical_actor_allowed_combinations`
+- Write Workflows injects:
+  - `idea_id`
+  - `side_effects_artifact`
+  - `implicated_users_artifact`
+  - `implemented_stories`
+  - `code_evidence`
+  - `source_docs`
+- Validate enrich injects:
+  - `idea_id`
+  - `side_effects_artifact`
+  - `implicated_users_artifact`
+  - `workflows`
+  - `implemented_stories`
+  - `code_evidence`
+  - `source_docs`
+- Validate code repair injects:
+  - `failing_workflows`
+  - `validation_errors`
+  - `code_evidence_files`
+  - `side_effects_artifact`
+  - `implicated_users_artifact`
+  - `implemented_stories`
+- Red injects:
+  - `idea_id`
+  - `validated_workflows`
+  - `validation_report`
+  - `side_effects_artifact`
+  - `implicated_users_artifact`
+  - `code_evidence`
+- Red code repair injects:
+  - `failing_packages`
+  - `validation_errors`
+  - `failing_workflows`
+  - `side_effects_artifact`
+  - `implicated_users_artifact`
+  - `code_evidence`
+- Red review injects:
+  - `idea_id`
+  - `validated_workflows`
+  - `red_artifact`
+  - `validation_report`
+- Green injects:
+  - `idea_id`
+  - `validated_workflows`
+  - `red_review_artifact`
+  - `code_evidence`
+  - `implemented_stories`
+- Green enrich injects:
+  - `idea_id`
+  - `validated_workflows`
+  - `green_artifact`
+  - `red_review_artifact`
+
+Those fields are sourced from a mix of:
+
+- the incoming integration event (`event.idea_id`, `event.implemented_idea`, `event.implemented_stories`, `event.code_evidence`, `event.source_docs`)
+- prior node outputs stored in `task_context.metadata`
+- repo files loaded earlier in the pipeline (for example via prepared integration payloads and written artifacts)
+- repair-time file reads such as `_load_code_evidence_for_workflows(...)`
+
+## 4) Output schema contract
+
+`run_agent_step(...)` always injects the expected output schema as:
+
+- `output_schema = output_model.model_json_schema()`
+
+For integration, the concrete model classes live in `src/devflow_engine/integration/dag.py`:
+
+- `SideEffectsArtifact`
+- `ImplicatedUsersArtifact`
+- `WorkflowSetArtifact`
+- `ValidateEnrichArtifact`
+- `CodeRepairArtifact`
+- `RedArtifact`
+- `RedReviewArtifact`
+- `GreenArtifact`
+- `GreenEnrichArtifact`
+
+## 5) Return-format contract
+
+`src/devflow_engine/agentic_runtime.py` injects:
+
+- `return_format: "json_only"`
+
+and calls `invoke_llm(...)` with:
+
+- `response_contract="json_only"`
+- `interaction_model="agentic"`
+- `delivery_model="streaming"`
+
+## 6) Tools / skills / runtime config: what actually applies here
+
+For the **current integration runtime path**:
+
+- No integration-specific skill bundle is injected into the prompt payload.
+- No tool list is assembled by `integration/agentic.py` or `agentic_runtime.py`.
+- If the provider path is Anthropic API, `src/devflow_engine/llm/invoke.py` calls `anthropic_messages_create(...)` with:
+  - `system_prompt=""`
+  - `messages=[{"role": "user", "content": <assembled JSON prompt>}]`
+  - `tools=[]`
+- Model/provider/base command selection is runtime config, not prompt doctrine. It is resolved in `src/devflow_engine/llm/invoke.py` from `LlmInvocationRequest(...)` plus global LLM config/tier config.
+
+So for integration, the useful separation is:
+
+- **Stable node doctrine:** `node_config/prompt.md`
+- **Stable prompt text that actually reaches the model:** stage `prompt.md` bullet lines
+- **Runtime-built context:** `context_payload` from `integration/dag.py`
+- **Runtime config:** provider/model/CLI/API transport chosen by `invoke_llm(...)`
+- **Tools/skills:** none currently injected by the integration path
+
+## 7) Size-management behavior
+
+If the prompt envelope is too large, `src/devflow_engine/agentic_runtime.py` may:
+
+1. compact large strings/lists/dicts in `context`, or
+2. persist the full context to `.devflow/agent_debug/context_artifacts/<stage>_context.json`
+   and replace inline `context` with:
+   - `context_artifact_path`
+   - `context_artifact_note`
+
+## 8) Example files
+
+Each integration node directory includes an `example.md` showing the **assembled payload shape** the model actually receives for that node.
+
+Each example explicitly labels:
+
+- what came from stable stage prompt markdown
+- what came from runtime-built context
+- what schema/model contract was injected
+- what was reconstructed from code rather than copied from a captured past run

devflow_engine/prompts/integration/green/example.md

@@ -0,0 +1,67 @@
+# Green node assembled payload
+
+## Provenance
+
+Reconstructed from:
+
+- `prompts/integration/green/green/prompt.md`
+- `src/devflow_engine/integration/dag.py` green agent call
+- `src/devflow_engine/agentic_runtime.py`
+- `GreenArtifact` in `src/devflow_engine/integration/dag.py`
+
+Not copied from a persisted past-run integration prompt.
+
+## Stable doctrine vs actual payload
+
+- Stable node doctrine file: `prompts/integration/green/node_config/prompt.md`
+- Actual `instructions` come from `green/green/prompt.md`
+- Actual `context` comes from `task_context.metadata` + `event.*`
+- No skills or tools are injected here
+
+```json
+{
+  "task": "integration_green",
+  "instructions": [
+    "Produce exactly one green package per reviewed workflow package.",
+    "Distinguish implementation changes, harness support changes, passing strategy, and proof artifacts.",
+    "Keep proposed changes aligned to the validated workflow, red review, and available evidence.",
+    "If a required seam or observable is missing, say so explicitly.",
+    "Do not fake passability.",
+    "Return JSON only."
+  ],
+  "context": {
+    "idea_id": "idea_checkout_recovery_v1",
+    "validated_workflows": [
+      {
+        "workflow_id": "wf_recovery_email_sent",
+        "side_effect": { "id": "se_recovery_email_sent", "name": "Recovery email sent" },
+        "interaction_points": [
+          { "kind": "endpoint", "name": "POST /api/carts/{cart_id}/recover", "implemented": true }
+        ]
+      }
+    ],
+    "red_review_artifact": {
+      "idea_id": "idea_checkout_recovery_v1",
+      "summary": "One package needs stronger observability.",
+      "reviewed_packages": [],
+      "findings": [
+        {
+          "workflow_id": "wf_recovery_email_sent",
+          "verdict": "needs_repair",
+          "findings": ["Current proof does not observe durable email-delivery completion."],
+          "repair_directions": ["Add a delivery-status artifact or background observer seam."]
+        }
+      ]
+    },
+    "code_evidence": [
+      { "path": "src/jobs/recovery_email_job.py", "side_effect_ids": [], "interaction_points": [] },
+      { "path": "src/notifications/email_delivery.py", "side_effect_ids": [], "interaction_points": [] }
+    ],
+    "implemented_stories": [
+      { "story_id": "STORY-recovery-email-send", "title": "Send recovery reminder email", "side_effect_ids": ["se_recovery_email_sent"], "required_planes": [] }
+    ]
+  },
+  "output_schema": "GreenArtifact.model_json_schema()",
+  "return_format": "json_only"
+}
+```

devflow_engine/prompts/integration/green/green/prompt.md

@@ -0,0 +1,10 @@
+# Green
+
+Specify the legitimate implementation and harness changes required to make reviewed red proofs pass.
+
+- Produce exactly one green package per reviewed workflow package.
+- Distinguish implementation changes, harness support changes, passing strategy, and proof artifacts.
+- Keep proposed changes aligned to the validated workflow, red review, and available evidence.
+- If a required seam or observable is missing, say so explicitly.
+- Do not fake passability.
+- Return JSON only.

devflow_engine/prompts/integration/green/node_config/prompt.md

@@ -0,0 +1,42 @@
+# Green Node Contract
+
+Specify the legitimate implementation and harness changes required to make reviewed red proofs pass.
+
+## What this file is
+
+Stable node doctrine loaded by:
+
+- `load_integration_node_instruction("green")`
+- `GreenNode.get_agent_config()`
+
+## What actually reaches the model
+
+The model-facing payload is assembled from:
+
+- stage bullets in `prompts/integration/green/green/prompt.md`
+- runtime `context_payload` from `src/devflow_engine/integration/dag.py`
+- `GreenArtifact.model_json_schema()`
+- `return_format: "json_only"`
+
+## Real injected runtime components
+
+`context_payload` fields:
+
+- `idea_id` ← `event.idea_id`
+- `validated_workflows` ← `task_context.metadata["workflows"]`
+- `red_review_artifact` ← `task_context.metadata["red_review_artifact"]`
+- `code_evidence` ← `event.code_evidence`
+- `implemented_stories` ← `event.implemented_stories`
+
+`instructions` source:
+
+- bullets parsed from `prompts/integration/green/green/prompt.md`
+
+`output_schema` source:
+
+- `GreenArtifact.model_json_schema()`
+
+## Tools / skills / config
+
+- No integration-specific skills are injected.
+- No tool definitions are injected.

devflow_engine/prompts/integration/green/past_prompts/20260417T212300/green/prompt.md

@@ -0,0 +1,15 @@
+# Green
+
+Green is a real GenAI node: specify the implementation and harness changes required for the reviewed red integration proofs to pass legitimately.
+
+- This is a real GenAI DAG. Return JSON only.
+- Node 1 and Node 2 must be genuinely model-backed; do not simulate agentic behavior with deterministic shortcuts.
+- Workflows are anchored to side effects, not users.
+- Attach implicated users to workflows using the canonical actor model: kind x scope x authority.
+- Reject denied canonical actor combinations by listing them under denied_candidates with explicit reasons.
+- Treat interaction points as first-class. Reference implemented seams when they exist; mark needed interaction points when required but missing.
+- Preserve alignment to implemented stories, implementation evidence, and source docs.
+- Do not overclaim unsupported implementation. Keep rationale explicit.
+- Produce one green package per reviewed workflow package.
+- Describe legitimate implementation changes, harness support changes, and proof artifacts needed to make red pass.
+- Do not fake passability; if a seam must be added, say so explicitly.

devflow_engine/prompts/integration/green/past_prompts/20260417T212300/node_config/prompt.md

@@ -0,0 +1,42 @@
+# Green Node Contract
+
+Green is a real GenAI node: specify the implementation and harness changes required for the reviewed red integration proofs to pass legitimately.
+
+## What this file is
+
+Stable node doctrine loaded by:
+
+- `load_integration_node_instruction("green")`
+- `GreenNode.get_agent_config()`
+
+## What actually reaches the model
+
+The model-facing payload is assembled from:
+
+- stage bullets in `prompts/integration/green/green/prompt.md`
+- runtime `context_payload` from `src/devflow_engine/integration/dag.py`
+- `GreenArtifact.model_json_schema()`
+- `return_format: "json_only"`
+
+## Real injected runtime components
+
+`context_payload` fields:
+
+- `idea_id` ← `event.idea_id`
+- `validated_workflows` ← `task_context.metadata["workflows"]`
+- `red_review_artifact` ← `task_context.metadata["red_review_artifact"]`
+- `code_evidence` ← `event.code_evidence`
+- `implemented_stories` ← `event.implemented_stories`
+
+`instructions` source:
+
+- bullets parsed from `prompts/integration/green/green/prompt.md`
+
+`output_schema` source:
+
+- `GreenArtifact.model_json_schema()`
+
+## Tools / skills / config
+
+- No integration-specific skills are injected.
+- No tool definitions are injected.

devflow_engine/prompts/integration/green_enrich/example.md

@@ -0,0 +1,79 @@
+# Green Enrich node assembled payload
+
+## Provenance
+
+Reconstructed from:
+
+- `prompts/integration/green_enrich/green_enrich/prompt.md`
+- `src/devflow_engine/integration/dag.py` green-enrich agent call
+- `src/devflow_engine/agentic_runtime.py`
+- `GreenEnrichArtifact` in `src/devflow_engine/integration/dag.py`
+
+Not copied from a persisted past-run integration prompt.
+
+## Stable doctrine vs actual payload
+
+- Stable node doctrine file: `prompts/integration/green_enrich/node_config/prompt.md`
+- Actual `instructions` come from `green_enrich/green_enrich/prompt.md`
+- Actual `context` comes from `task_context.metadata` + `event.idea_id`
+- No skills or tools are injected here
+
+```json
+{
+  "task": "integration_green_enrich",
+  "instructions": [
+    "Strengthen each workflow package using the validated workflows, green artifact, and red review artifact.",
+    "Improve assertions, anchors, and observability only where the evidence supports it.",
+    "Reduce brittleness explicitly.",
+    "Do not merely restate the green package or invent unsupported seams.",
+    "Return JSON only."
+  ],
+  "context": {
+    "idea_id": "idea_checkout_recovery_v1",
+    "validated_workflows": [
+      {
+        "workflow_id": "wf_recovery_email_sent",
+        "side_effect": { "id": "se_recovery_email_sent", "name": "Recovery email sent" },
+        "interaction_points": [
+          { "kind": "endpoint", "name": "POST /api/carts/{cart_id}/recover", "implemented": true }
+        ]
+      }
+    ],
+    "green_artifact": {
+      "idea_id": "idea_checkout_recovery_v1",
+      "summary": "Green package proposes observability improvements.",
+      "packages": [
+        {
+          "workflow_id": "wf_recovery_email_sent",
+          "side_effect_id": "se_recovery_email_sent",
+          "implementation_changes": [
+            { "path": "src/notifications/email_delivery.py", "change": "persist delivery status by cart_id" }
+          ],
+          "harness_support_changes": [
+            { "kind": "background_observer", "change": "observe durable delivery completion event" }
+          ],
+          "passing_strategy": ["assert endpoint acceptance", "assert durable delivery artifact"],
+          "proof_artifacts": [
+            { "kind": "artifact_probe", "name": "delivery_status.json" }
+          ]
+        }
+      ]
+    },
+    "red_review_artifact": {
+      "idea_id": "idea_checkout_recovery_v1",
+      "summary": "One package needs stronger observability.",
+      "reviewed_packages": [],
+      "findings": [
+        {
+          "workflow_id": "wf_recovery_email_sent",
+          "verdict": "needs_repair",
+          "findings": ["Current proof relies on brittle log inspection."],
+          "repair_directions": ["Replace log-only proof with durable observable artifact."]
+        }
+      ]
+    }
+  },
+  "output_schema": "GreenEnrichArtifact.model_json_schema()",
+  "return_format": "json_only"
+}
+```

devflow_engine/prompts/integration/green_enrich/green_enrich/prompt.md

@@ -0,0 +1,9 @@
+# Green Enrich
+
+Strengthen the green proof plan with sharper assertions and less brittle observability.
+
+- Strengthen each workflow package using the validated workflows, green artifact, and red review artifact.
+- Improve assertions, anchors, and observability only where the evidence supports it.
+- Reduce brittleness explicitly.
+- Do not merely restate the green package or invent unsupported seams.
+- Return JSON only.

devflow_engine/prompts/integration/green_enrich/node_config/prompt.md

@@ -0,0 +1,41 @@
+# Green Enrich Node Contract
+
+Strengthen the green proof plan with sharper assertions and less brittle observability.
+
+## What this file is
+
+Stable node doctrine loaded by:
+
+- `load_integration_node_instruction("green_enrich")`
+- `GreenEnrichNode.get_agent_config()`
+
+## What actually reaches the model
+
+The model-facing payload is assembled from:
+
+- stage bullets in `prompts/integration/green_enrich/green_enrich/prompt.md`
+- runtime `context_payload` from `src/devflow_engine/integration/dag.py`
+- `GreenEnrichArtifact.model_json_schema()`
+- `return_format: "json_only"`
+
+## Real injected runtime components
+
+`context_payload` fields:
+
+- `idea_id` ← `event.idea_id`
+- `validated_workflows` ← `task_context.metadata["workflows"]`
+- `green_artifact` ← `task_context.metadata["green_artifact"]`
+- `red_review_artifact` ← `task_context.metadata["red_review_artifact"]`
+
+`instructions` source:
+
+- bullets parsed from `prompts/integration/green_enrich/green_enrich/prompt.md`
+
+`output_schema` source:
+
+- `GreenEnrichArtifact.model_json_schema()`
+
+## Tools / skills / config
+
+- No integration-specific skills are injected.
+- No tool definitions are injected.

devflow_engine/prompts/integration/green_enrich/past_prompts/20260417T212300/green_enrich/prompt.md

@@ -0,0 +1,14 @@
+# Green Enrich
+
+GreenEnrich is a real GenAI node: strengthen the integration proof, assertions, and observability while reducing brittleness.
+
+- This is a real GenAI DAG. Return JSON only.
+- Node 1 and Node 2 must be genuinely model-backed; do not simulate agentic behavior with deterministic shortcuts.
+- Workflows are anchored to side effects, not users.
+- Attach implicated users to workflows using the canonical actor model: kind x scope x authority.
+- Reject denied canonical actor combinations by listing them under denied_candidates with explicit reasons.
+- Treat interaction points as first-class. Reference implemented seams when they exist; mark needed interaction points when required but missing.
+- Preserve alignment to implemented stories, implementation evidence, and source docs.
+- Do not overclaim unsupported implementation. Keep rationale explicit.
+- Strengthen proof artifacts per workflow with better assertions, sharper anchors, and observability support.
+- Reduce brittleness explicitly; do not merely restate the green package.

devflow_engine/prompts/integration/green_enrich/past_prompts/20260417T212300/node_config/prompt.md

@@ -0,0 +1,41 @@
+# Green Enrich Node Contract
+
+GreenEnrich is a real GenAI node: strengthen the integration proof, assertions, and observability while reducing brittleness.
+
+## What this file is
+
+Stable node doctrine loaded by:
+
+- `load_integration_node_instruction("green_enrich")`
+- `GreenEnrichNode.get_agent_config()`
+
+## What actually reaches the model
+
+The model-facing payload is assembled from:
+
+- stage bullets in `prompts/integration/green_enrich/green_enrich/prompt.md`
+- runtime `context_payload` from `src/devflow_engine/integration/dag.py`
+- `GreenEnrichArtifact.model_json_schema()`
+- `return_format: "json_only"`
+
+## Real injected runtime components
+
+`context_payload` fields:
+
+- `idea_id` ← `event.idea_id`
+- `validated_workflows` ← `task_context.metadata["workflows"]`
+- `green_artifact` ← `task_context.metadata["green_artifact"]`
+- `red_review_artifact` ← `task_context.metadata["red_review_artifact"]`
+
+`instructions` source:
+
+- bullets parsed from `prompts/integration/green_enrich/green_enrich/prompt.md`
+
+`output_schema` source:
+
+- `GreenEnrichArtifact.model_json_schema()`
+
+## Tools / skills / config
+
+- No integration-specific skills are injected.
+- No tool definitions are injected.

devflow_engine/prompts/integration/red/code_repair/prompt.md

@@ -0,0 +1,12 @@
+# Red Code Repair
+
+Repair product code only when a red proof failure exposes a real code seam problem.
+
+- Patch the smallest real code change that fixes the current failing workflow surface.
+- Choose one primary failing seam from validation_errors, failing_packages, failing_workflows, and code_evidence; keep edits there unless the same failure forces one adjacent file.
+- Prefer files already named by the failing workflow, package interaction point, or code evidence.
+- Update updated_workflows only when the repaired code changes workflow truth.
+- Do not repair proof-package artifacts here. Do not edit engine, runtime, orchestration, or prompt-loading layers unless the failure explicitly originates there.
+- If the failure is artifact-only, harness-only, or runtime-only, leave code unchanged and explain it in unresolvable_failures.
+- Return only changed files with full contents, updated_workflows, and unresolvable_failures.
+- Return JSON only.