agentic-orchestrator 0.1.28 → 0.2.1

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

@@ -301,6 +301,72 @@
           "items": {
             "type": "string"
           }
+        },
+        "human_input": {
+          "type": "object",
+          "description": "Policy for deterministic human-input question handling and resume context.",
+          "required": [
+            "enabled",
+            "timeout_ms",
+            "on_timeout",
+            "max_open_questions_per_feature",
+            "context_answer_history_limit"
+          ],
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "timeout_ms": {
+              "type": "number",
+              "minimum": 1
+            },
+            "on_timeout": {
+              "type": "string",
+              "enum": ["block_feature", "fail_feature"]
+            },
+            "max_open_questions_per_feature": {
+              "type": "number",
+              "minimum": 1
+            },
+            "context_answer_history_limit": {
+              "type": "number",
+              "minimum": 1
+            }
+          }
+        }
+      }
+    },
+    "planning": {
+      "type": "object",
+      "description": "Planning and intake gating policy.",
+      "additionalProperties": false,
+      "properties": {
+        "intake": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "require_verified_manifest_before_planning": {
+              "type": "boolean"
+            },
+            "allow_auto_promotion": {
+              "type": "boolean"
+            },
+            "auto_promotion_min_confidence": {
+              "type": "string",
+              "enum": ["high", "medium", "low"]
+            },
+            "max_intake_question_rounds": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "on_unresolved_ambiguity": {
+              "type": "string",
+              "enum": ["awaiting_input", "blocked", "fail_feature"]
+            }
+          }
         }
       }
     },
@@ -389,6 +455,11 @@
             "type": "string",
             "enum": ["merge_commit", "squash", "rebase"]
           }
+        },
+        "merge_target": {
+          "type": "string",
+          "enum": ["base_branch", "feature_branch"],
+          "description": "Where to land the merge. 'base_branch' merges directly to the base branch. 'feature_branch' creates an aop/<feature-id> branch off the base branch and merges there."
         }
       }
     },
@@ -468,24 +539,92 @@
         }
       }
     },
-    "cleanup": {
+    "reconciliation": {
       "type": "object",
-      "description": "Controls automatic cleanup of merged feature worktrees and branches.",
+      "description": "Controls automatic git reconciliation (rebase/fast-forward) of feature branches against mainline.",
+      "additionalProperties": false,
       "properties": {
-        "auto_after_merge": {
+        "enabled": {
           "type": "boolean",
-          "description": "When true, the feature worktree and branch are automatically removed after a successful merge."
+          "default": false,
+          "description": "When true, the reconciler is active and will check for divergence before specified phases."
         },
-        "grace_period_seconds": {
-          "type": "number",
-          "minimum": 0,
-          "description": "Delay in seconds before automatic post-merge cleanup runs, allowing time for CI or post-merge hooks to reference the worktree."
+        "check_before_phases": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of phase names before which the reconciler will check and attempt to reconcile the feature branch."
+        },
+        "auto_merge_non_conflicting": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, the reconciler will automatically rebase non-conflicting divergences without requiring human approval."
+        },
+        "reconciler_max_iterations": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 3,
+          "description": "Maximum number of reconciliation attempts before the feature is blocked and escalated."
+        },
+        "reconciler_timeout_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 600,
+          "description": "Timeout in seconds for a single reconciliation operation before it is abandoned."
+        }
+      }
+    },
+    "cleanup": {
+      "type": "object",
+      "description": "Controls automatic cleanup of merged feature worktrees/branches and AOP feature artifacts.",
+      "additionalProperties": false,
+      "properties": {
+        "auto_after_merge": {
+          "type": "object",
+          "description": "Per-surface cleanup settings that run after a successful merge.",
+          "additionalProperties": false,
+          "properties": {
+            "worktree": {
+              "type": "object",
+              "description": "Controls git worktree + branch cleanup.",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "When true, the feature worktree and branch are automatically removed after a successful merge."
+                },
+                "grace_period_seconds": {
+                  "type": "number",
+                  "minimum": 0,
+                  "description": "Delay in seconds before automatic post-merge worktree cleanup runs, allowing time for CI or post-merge hooks to reference the worktree."
+                }
+              },
+              "required": ["enabled", "grace_period_seconds"]
+            },
+            "aop": {
+              "type": "object",
+              "description": "Controls cleanup of `.aop/features/<id>` artifacts after merge.",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "When true, the feature's `.aop` artifacts are removed after a successful merge."
+                },
+                "grace_period_seconds": {
+                  "type": "number",
+                  "minimum": 0,
+                  "description": "Delay in seconds before automatic post-merge AOP artifact cleanup runs."
+                }
+              },
+              "required": ["enabled", "grace_period_seconds"]
+            }
+          },
+          "required": ["worktree", "aop"]
         }
       }
     },
     "observability": {
       "type": "object",
-      "description": "Controls persistence and retention of sensitive raw worker provider output logs.",
+      "description": "Controls persistence, retention, and replay of observability artifacts.",
       "additionalProperties": false,
       "properties": {
         "raw_agent_logs_enabled": {
@@ -496,6 +635,58 @@
           "type": "integer",
           "minimum": 1,
           "description": "Maximum age in days for persisted raw provider log files before best-effort cleanup removes them."
+        },
+        "replay": {
+          "type": "object",
+          "description": "Deterministic replay timeline settings.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "When true, tool call events are appended to the replay timeline."
+            },
+            "write_mode": {
+              "type": "string",
+              "enum": ["best_effort", "required"],
+              "description": "best_effort: write failures are logged but do not fail the tool call. required: write failures propagate as replay_timeline_write_failed."
+            },
+            "retention": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "max_runs": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Maximum number of run timelines retained in .aop/runtime/replay/. Oldest runs are pruned."
+                },
+                "max_entries_per_run": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Maximum number of timeline entries per run. Entries beyond this limit are skipped."
+                }
+              }
+            }
+          }
+        },
+        "evidence_integrity": {
+          "type": "object",
+          "description": "Tamper-evident evidence chain settings (companion spec OID2).",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "When true, evidence artifacts are written with hash chain entries."
+            },
+            "verify_on_read": {
+              "type": "boolean",
+              "description": "When true, chain integrity is verified each time evidence is read."
+            },
+            "algorithm_version": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Hash algorithm version used for chain entries."
+            }
+          }
         }
       }
     },
@@ -765,6 +956,44 @@
           }
         }
       }
+    },
+    "innovation": {
+      "type": "object",
+      "description": "Feature flags for experimental and preview capabilities.",
+      "additionalProperties": false,
+      "properties": {
+        "replay_debugger": {
+          "type": "boolean",
+          "description": "Master toggle for the replay timeline debugger. Must be true AND observability.replay.enabled must be true for timeline writes to occur."
+        },
+        "tamper_evident_evidence": {
+          "type": "boolean",
+          "description": "Master toggle for tamper-evident evidence chains. Must be true AND observability.evidence_integrity.enabled must be true for chain writes to occur."
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "object",
+      "description": "Diagnostic tools configuration.",
+      "additionalProperties": false,
+      "properties": {
+        "doctor": {
+          "type": "object",
+          "description": "Doctor diagnostic command settings.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "When false, doctor.run returns a report with a doctor_disabled info finding instead of running checks."
+            },
+            "strict_fails_on": {
+              "type": "string",
+              "enum": ["critical", "warning"],
+              "description": "Severity level at which the doctor report is considered a failure."
+            }
+          }
+        }
+      }
     }
   }
 }

package/agentic/orchestrator/schemas/policy.user.schema.json

@@ -57,6 +57,46 @@
         }
       }
     },
+    "cleanup": {
+      "type": "object",
+      "description": "Cleanup settings for merged features.",
+      "additionalProperties": false,
+      "properties": {
+        "auto_after_merge": {
+          "type": "object",
+          "description": "Per-surface cleanup settings that run after a successful merge.",
+          "additionalProperties": false,
+          "properties": {
+            "worktree": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "grace_period_seconds": {
+                  "type": "number",
+                  "minimum": 0
+                }
+              }
+            },
+            "aop": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "grace_period_seconds": {
+                  "type": "number",
+                  "minimum": 0
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "dashboard": {
       "type": "object",
       "description": "Dashboard HTTP server settings.",
@@ -80,7 +120,7 @@
     },
     "observability": {
       "type": "object",
-      "description": "Raw worker output observability controls.",
+      "description": "Raw worker output observability controls and replay timeline settings.",
       "additionalProperties": false,
       "properties": {
         "raw_agent_logs_enabled": {
@@ -91,6 +131,53 @@
           "type": "integer",
           "minimum": 1,
           "description": "Number of days raw agent log files are retained before cleanup."
+        },
+        "replay": {
+          "type": "object",
+          "description": "Replay timeline settings.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Enable replay timeline writes."
+            },
+            "write_mode": {
+              "type": "string",
+              "enum": ["best_effort", "required"],
+              "description": "best_effort (default): write failures are silent. required: write failures surface as tool errors."
+            },
+            "retention": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "max_runs": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "max_entries_per_run": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              }
+            }
+          }
+        },
+        "evidence_integrity": {
+          "type": "object",
+          "description": "Tamper-evident evidence chain settings.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "verify_on_read": {
+              "type": "boolean"
+            },
+            "algorithm_version": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
         }
       }
     },
@@ -110,6 +197,11 @@
             "type": "string",
             "enum": ["merge_commit", "squash", "rebase"]
           }
+        },
+        "merge_target": {
+          "type": "string",
+          "enum": ["base_branch", "feature_branch"],
+          "description": "Where to land the merge. 'base_branch' merges directly to main. 'feature_branch' creates an aop/<feature-id> branch."
         }
       }
     },
@@ -176,6 +268,42 @@
           "description": "When true, orphaned agent sessions are automatically cleaned up at startup."
         }
       }
+    },
+    "innovation": {
+      "type": "object",
+      "description": "Feature flags for experimental capabilities.",
+      "additionalProperties": false,
+      "properties": {
+        "replay_debugger": {
+          "type": "boolean",
+          "description": "Master toggle for replay timeline. Also requires observability.replay.enabled=true."
+        },
+        "tamper_evident_evidence": {
+          "type": "boolean",
+          "description": "Master toggle for tamper-evident evidence chains."
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "object",
+      "description": "Diagnostic tools configuration.",
+      "additionalProperties": false,
+      "properties": {
+        "doctor": {
+          "type": "object",
+          "description": "Doctor command settings.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "strict_fails_on": {
+              "type": "string",
+              "enum": ["critical", "warning"]
+            }
+          }
+        }
+      }
     }
   }
 }

package/agentic/orchestrator/schemas/spec.manifest.bootstrap.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/spec.manifest.bootstrap.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "feature_id",
+    "manifest_version",
+    "artifact_type",
+    "generation_mode",
+    "generated_at",
+    "source_hash",
+    "obligations",
+    "ambiguities"
+  ],
+  "properties": {
+    "feature_id": { "type": "string", "minLength": 1 },
+    "manifest_version": { "type": "integer", "minimum": 1 },
+    "artifact_type": { "const": "bootstrap" },
+    "generation_mode": { "const": "bootstrap" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "source_hash": { "type": "string", "minLength": 8 },
+    "obligations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/obligation" }
+    },
+    "ambiguities": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ambiguity" }
+    }
+  },
+  "$defs": {
+    "sourceRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["line_start", "line_end", "heading"],
+      "properties": {
+        "line_start": { "type": "integer", "minimum": 1 },
+        "line_end": { "type": "integer", "minimum": 1 },
+        "heading": { "type": ["string", "null"] }
+      }
+    },
+    "obligation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "obligation_id",
+        "kind",
+        "name",
+        "description",
+        "source_refs",
+        "verification_hint",
+        "confidence"
+      ],
+      "properties": {
+        "obligation_id": { "type": "string", "pattern": "^OBL-\\d{3,}$" },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "artifact",
+            "endpoint",
+            "workflow",
+            "behavior",
+            "integration",
+            "contract",
+            "verification"
+          ]
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "source_refs": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/sourceRef" }
+        },
+        "verification_hint": {
+          "type": "string",
+          "enum": ["required", "optional"]
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["high", "medium", "low"]
+        }
+      }
+    },
+    "ambiguity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "summary", "status"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^AMB-\\d{3,}$" },
+        "summary": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "enum": ["open", "resolved"] },
+        "obligation_ids": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^OBL-\\d{3,}$" }
+        }
+      }
+    }
+  }
+}

package/agentic/orchestrator/schemas/spec.manifest.verified.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/spec.manifest.verified.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "feature_id",
+    "manifest_version",
+    "artifact_type",
+    "verification_basis",
+    "verified_at",
+    "source_bootstrap_version",
+    "obligations"
+  ],
+  "properties": {
+    "feature_id": { "type": "string", "minLength": 1 },
+    "manifest_version": { "type": "integer", "minimum": 1 },
+    "artifact_type": { "const": "verified" },
+    "verification_basis": {
+      "type": "string",
+      "enum": [
+        "structured_spec",
+        "questions_resolved",
+        "policy_approved_auto_promotion",
+        "human_review_confirmed"
+      ]
+    },
+    "verified_at": { "type": "string", "format": "date-time" },
+    "source_bootstrap_version": { "type": ["integer", "null"], "minimum": 1 },
+    "obligations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/obligation" }
+    }
+  },
+  "$defs": {
+    "sourceRef": { "$ref": "spec.manifest.bootstrap.schema.json#/$defs/sourceRef" },
+    "obligation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "obligation_id",
+        "kind",
+        "name",
+        "description",
+        "source_refs",
+        "verification_hint",
+        "confidence"
+      ],
+      "properties": {
+        "obligation_id": { "type": "string", "pattern": "^OBL-\\d{3,}$" },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "artifact",
+            "endpoint",
+            "workflow",
+            "behavior",
+            "integration",
+            "contract",
+            "verification"
+          ]
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "source_refs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/sourceRef" }
+        },
+        "verification_hint": {
+          "type": "string",
+          "enum": ["required", "optional"]
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["high", "medium", "low"]
+        }
+      }
+    }
+  }
+}