agentic-orchestrator 0.1.28 → 0.2.1

package/agentic/orchestrator/prompts/reconciler.system.md

@@ -0,0 +1,119 @@
+You are the reconciler role.
+
+The orchestrator is interactive-only.
+Work directly in the conflicted feature worktree and edit files on disk.
+Do **not** emit unified diffs or `PATCH` outputs.
+Return `NOTE` / `REQUEST` JSON outputs summarizing reconciliation progress directly.
+
+## Reconciler objective
+
+Resolve mainline divergence so the feature can continue on top of current mainline semantics without losing its intended behavior.
+
+Mainline is authoritative for current contracts, fixes, and shared abstractions.
+Your job is to adapt the feature to mainline, not to revert mainline to the feature.
+
+If `approved_collision_context` is present, treat it as authoritative merge guidance:
+
+1. the listed overlapping paths were intentionally shared
+2. both feature intents are expected to survive unless technically impossible
+3. the operator rationale is a required design constraint
+4. do not drop an approved counterpart behavior without explicit justification
+
+## Resolution discipline
+
+Before editing:
+
+1. Read `spec.md`, `plan.json`, `state.md`, current conflicted files, and any approved collision context
+2. Determine what mainline changed, what the feature changed, and which behavior must survive
+3. Build a mental merge matrix for each conflicted file:
+   - keep from mainline
+   - keep from feature
+   - rewrite to combine both
+   - escalate because the intents are incompatible
+
+When resolving:
+
+1. Prefer manual semantic merges over blanket `ours` / `theirs` thinking
+2. If mainline renamed or reshaped an abstraction, migrate feature code to the new abstraction rather than resurrecting the old one
+3. Preserve stricter validation, typing, error handling, and tests from either side unless they are provably invalid
+4. Preserve approved overlap behavior where technically feasible
+5. Never claim success based only on marker removal when the merge could still be behaviorally broken
+
+When plan assumptions are impacted:
+
+1. Do not silently rewrite the requirements contract during reconciliation
+2. Capture the plan impact clearly in your final `NOTE`
+3. State what changed in mainline, what part of the accepted plan is no longer reliable, and what planner follow-up is likely required
+
+## Verification discipline
+
+After resolving conflicts:
+
+1. Verify no conflict markers remain
+2. Run proportionate local verification
+3. Use at least fast verification for non-trivial merges (`npm run typecheck` then `npm run lint`)
+4. If business logic, shared infrastructure, or broad behavior changed, also run the most relevant targeted tests and escalate to broader verification when needed
+
+Do not report reconciliation as complete while known merge-introduced defects, unresolved markers, or obvious contract mismatches remain.
+
+## Clarifying-question rule
+
+Use `REQUEST.action=ask_user_input` only when a true operator decision is required, for example:
+
+- mainline semantics and feature intent cannot both be preserved without a product choice
+- approved collision guidance is insufficient to choose the correct surviving behavior
+- a policy or risk acceptance decision is required before proceeding safely
+
+Do not ask the operator for routine merge mechanics, local code reading, or implementation choices you can resolve yourself.
+
+Use `REQUEST.action=more_context` only when the conflict snapshot, approved collision context, or surrounding repo state is stale or insufficient in a way that a same-iteration refresh could immediately unblock.
+
+## Output format
+
+Return exactly one JSON object. Do not wrap in markdown code fences.
+
+Allowed forms:
+
+```json
+{ "type": "NOTE", "content": "<message>" }
+```
+
+```json
+{ "type": "REQUEST", "request": { "action": "more_context" } }
+```
+
+```json
+{
+  "type": "REQUEST",
+  "request": {
+    "action": "ask_user_input",
+    "question_type": "clarification",
+    "prompt": "<question for the operator>",
+    "details": {},
+    "expected_answer": { "kind": "free_text" },
+    "blocking": true
+  }
+}
+```
+
+```json
+{"outputs": [<one or more of the above>]}
+```
+
+## NOTE quality
+
+When returning `NOTE`, include:
+
+- conflicts resolved
+- files modified
+- whether approved collision guidance was used
+- verification run
+- any plan impacts or residual risks
+
+Do not return a vague success note. Make the reconciliation outcome auditable.
+
+## Constraints
+
+- Never revert mainline changes wholesale
+- Never silently drop feature behavior or approved counterpart behavior without explicit justification
+- Do not claim completion if conflict markers remain or verification still indicates a likely broken merge

package/agentic/orchestrator/schemas/agents.schema.json

@@ -192,9 +192,69 @@
             "type": "object"
           }
         },
+        "prompt_overlay_dir": {
+          "type": "string",
+          "description": "Directory (relative to repo root) containing provider-specific prompt overlay files. Files are named <role>.<provider>.md (e.g. builder.claude.md). When present, the overlay is appended to the base role prompt. Defaults to config/agentic/orchestrator/prompts/overrides.",
+          "default": "config/agentic/orchestrator/prompts/overrides"
+        },
+        "provider_cli_config": {
+          "type": "object",
+          "description": "Per-provider CLI flag configuration for user-profile-specific flags (e.g. disabling MCP servers). Keyed by provider name.",
+          "additionalProperties": false,
+          "properties": {
+            "codex": {
+              "type": "object",
+              "description": "CLI flag configuration for the codex provider.",
+              "additionalProperties": false,
+              "properties": {
+                "disable_mcp_servers": {
+                  "type": "array",
+                  "description": "MCP server names to disable via -c mcp_servers.<name>.enabled=false. Use this to prevent user-profile MCPs from being invoked during worker execution.",
+                  "items": { "type": "string" },
+                  "default": []
+                }
+              }
+            },
+            "claude": {
+              "type": "object",
+              "description": "CLI flag configuration for the claude provider.",
+              "additionalProperties": false,
+              "properties": {
+                "no_mcp": {
+                  "type": "boolean",
+                  "description": "When true, passes --no-mcp to disable all MCP servers during worker execution. Prevents user-profile MCPs from being invoked.",
+                  "default": false
+                }
+              }
+            }
+          }
+        },
         "role_provider_overrides": {
           "type": "object",
-          "description": "Reserved for future per-role provider overrides. Parsed but not yet consumed by the supervisor."
+          "description": "Optional per-role provider/model overrides used to tune model selection by phase (planner/builder/qa). CLI/env overrides still take precedence.",
+          "additionalProperties": false,
+          "properties": {
+            "planner": {
+              "$ref": "#/$defs/roleProviderOverride",
+              "description": "Overrides for the planner role."
+            },
+            "builder": {
+              "$ref": "#/$defs/roleProviderOverride",
+              "description": "Overrides for the builder role."
+            },
+            "qa": {
+              "$ref": "#/$defs/roleProviderOverride",
+              "description": "Overrides for the QA role."
+            },
+            "reconciler": {
+              "$ref": "#/$defs/roleProviderOverride",
+              "description": "Overrides for the reconciler role."
+            },
+            "organizer": {
+              "$ref": "#/$defs/roleProviderOverride",
+              "description": "Overrides for the organizer role."
+            }
+          }
         }
       }
     }
@@ -208,6 +268,34 @@
         "system_prompt_path": {
           "type": "string",
           "description": "Repo-relative path to the system prompt file loaded by the supervisor for this role. If missing, behaviour is controlled by missing_prompt_behavior."
+        },
+        "intake_system_prompt_path": {
+          "type": "string",
+          "description": "Optional repo-relative path to a dedicated intake-phase system prompt for the planner role. When present, intake features use this prompt instead of the normal planner prompt."
+        }
+      }
+    },
+    "roleProviderOverride": {
+      "type": "object",
+      "description": "Per-role provider/model override block used to tune LLM selection per phase.",
+      "additionalProperties": false,
+      "properties": {
+        "provider": {
+          "type": "string",
+          "description": "Override provider name for this role (must be a supported provider).",
+          "enum": ["codex", "claude", "gemini", "custom", "kiro-cli", "copilot"]
+        },
+        "model": {
+          "type": "string",
+          "description": "Override model name for this role."
+        },
+        "provider_config_env": {
+          "type": "string",
+          "description": "Optional env var name for provider credentials/config used by this role."
+        },
+        "agent_config": {
+          "type": "object",
+          "description": "Optional per-role provider config object forwarded to the provider adapter."
         }
       }
     }

package/agentic/orchestrator/schemas/execution-control.schema.json

@@ -0,0 +1,242 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/execution-control.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "run_id", "owner_instance_id", "updated_at", "items"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "owner_instance_id": {
+      "type": "string"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "request_id",
+          "request_type",
+          "status",
+          "requested_at",
+          "processed_at",
+          "requested_by",
+          "operation_id",
+          "features",
+          "progress",
+          "outcome"
+        ],
+        "properties": {
+          "request_id": {
+            "type": "string"
+          },
+          "request_type": {
+            "type": "string",
+            "enum": ["add_features"]
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "applied", "rejected"]
+          },
+          "requested_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "processed_at": {
+            "type": ["string", "null"]
+          },
+          "requested_by": {
+            "type": "string"
+          },
+          "operation_id": {
+            "type": "string"
+          },
+          "features": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["feature_id", "spec_path"],
+              "properties": {
+                "feature_id": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9_][a-z0-9_-]*$"
+                },
+                "spec_path": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "progress": {
+            "anyOf": [
+              {
+                "type": "null"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["detected_at", "last_evaluated_at", "queued", "skipped", "deferred"],
+                "properties": {
+                  "detected_at": {
+                    "type": ["string", "null"],
+                    "format": "date-time"
+                  },
+                  "last_evaluated_at": {
+                    "type": ["string", "null"],
+                    "format": "date-time"
+                  },
+                  "queued": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "skipped": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["feature_id", "reason"],
+                      "properties": {
+                        "feature_id": {
+                          "type": "string",
+                          "pattern": "^[a-z0-9_][a-z0-9_-]*$"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  },
+                  "deferred": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["feature_id", "reason"],
+                      "properties": {
+                        "feature_id": {
+                          "type": "string",
+                          "pattern": "^[a-z0-9_][a-z0-9_-]*$"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            ]
+          },
+          "outcome": {
+            "anyOf": [
+              {
+                "type": "null"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["queued", "skipped"],
+                "properties": {
+                  "queued": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "skipped": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["feature_id", "reason"],
+                      "properties": {
+                        "feature_id": {
+                          "type": "string",
+                          "pattern": "^[a-z0-9_][a-z0-9_-]*$"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["code", "message"],
+                "properties": {
+                  "code": {
+                    "type": "string"
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "status": {
+                  "const": "pending"
+                }
+              }
+            },
+            "then": {
+              "properties": {
+                "processed_at": {
+                  "type": "null"
+                },
+                "outcome": {
+                  "type": "null"
+                }
+              }
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "status": {
+                  "enum": ["applied", "rejected"]
+                }
+              }
+            },
+            "then": {
+              "properties": {
+                "processed_at": {
+                  "type": "string",
+                  "format": "date-time"
+                }
+              },
+              "not": {
+                "properties": {
+                  "outcome": {
+                    "type": "null"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}