agentic-orchestrator 0.1.4 → 0.1.6

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/policy.schema.json",
+  "description": "Merged (defaults + user overrides) policy controlling orchestrator behaviour, gates, locks, and merge rules.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -23,40 +24,48 @@
   ],
   "properties": {
     "version": {
-      "type": "number"
+      "type": "number",
+      "description": "Schema version number for the policy file."
     },
     "commit_policy": {
       "type": "object",
+      "description": "Controls whether the orchestrator may create commits or execute merges on behalf of agents.",
       "required": [
         "allow_commit",
         "allow_merge"
       ],
       "properties": {
         "allow_commit": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When false, agents are not permitted to stage and commit changes to the feature branch."
         },
         "allow_merge": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When false, merges are blocked even if all required gate modes have passed."
         }
       }
     },
     "patch_policy": {
       "type": "object",
+      "description": "Constraints applied to file patches before they are written to the feature worktree.",
       "required": [
         "enforce_plan",
         "enforce_allowed_areas"
       ],
       "properties": {
         "enforce_plan": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When true, repo_apply_patch requires an accepted plan to exist before any patch is applied. Throws PLAN_REQUIRED if no plan is found."
         },
         "enforce_allowed_areas": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When true, every file touched by a patch must match at least one path in the plan's allowed_areas. Violations throw PATCH_POLICY_VIOLATION."
         }
       }
     },
     "locks": {
       "type": "object",
+      "description": "Distributed lock configuration controlling concurrent feature access to shared contract resources.",
       "required": [
         "resources",
         "contract_to_resource",
@@ -68,6 +77,7 @@
       "properties": {
         "resources": {
           "type": "array",
+          "description": "Ordered list of lockable resource names (e.g. 'openapi', 'events', 'db'). Only names in this list are accepted by the lock service.",
           "items": {
             "type": "string",
             "minLength": 1
@@ -75,6 +85,7 @@
         },
         "contract_to_resource": {
           "type": "object",
+          "description": "Maps plan contract types to the lock resource name they require. Used by plan and patch services to determine which locks must be held.",
           "required": [
             "openapi",
             "events",
@@ -82,22 +93,27 @@
           ],
           "properties": {
             "openapi": {
-              "type": "string"
+              "type": "string",
+              "description": "Lock resource name required when a plan declares contracts.openapi = 'modify'."
             },
             "events": {
-              "type": "string"
+              "type": "string",
+              "description": "Lock resource name required when a plan declares contracts.events = 'modify'."
             },
             "db": {
-              "type": "string"
+              "type": "string",
+              "description": "Lock resource name required when a plan declares contracts.db = 'migration'."
             }
           }
         },
         "lease_ttl_seconds": {
           "type": "number",
-          "minimum": 1
+          "minimum": 1,
+          "description": "How long in seconds a lock lease remains valid before it can be reclaimed as stale by another feature."
         },
         "acquire_behavior": {
           "type": "string",
+          "description": "'wait' polls until the lock is freed or the timeout is reached; 'fail' returns LOCK_CONFLICT immediately if the lock is held.",
           "enum": [
             "wait",
             "fail"
@@ -105,10 +121,12 @@
         },
         "default_wait_timeout_seconds": {
           "type": "number",
-          "minimum": 1
+          "minimum": 1,
+          "description": "Maximum time in seconds to wait for a lock when acquire_behavior is 'wait'."
         },
         "acquire_backoff": {
           "type": "object",
+          "description": "Exponential backoff parameters used between lock polling attempts when acquire_behavior is 'wait'.",
           "required": [
             "initial_ms",
             "max_ms",
@@ -118,19 +136,23 @@
           "properties": {
             "initial_ms": {
               "type": "number",
-              "minimum": 1
+              "minimum": 1,
+              "description": "Initial delay in milliseconds before the first lock retry."
             },
             "max_ms": {
               "type": "number",
-              "minimum": 1
+              "minimum": 1,
+              "description": "Maximum delay in milliseconds; backoff is capped at this value."
             },
             "multiplier": {
               "type": "number",
-              "minimum": 1
+              "minimum": 1,
+              "description": "Factor by which the delay is multiplied after each failed lock attempt."
             },
             "jitter_ms": {
               "type": "number",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Maximum random jitter in milliseconds added to each backoff delay to spread out competing lock attempts."
             }
           }
         }
@@ -138,38 +160,45 @@
     },
     "protected_areas": {
       "type": "array",
+      "description": "Path prefixes or glob patterns that no agent patch may touch, regardless of the plan. Violations throw PATCH_POLICY_VIOLATION with reason 'in_protected_areas'.",
       "items": {
         "type": "string"
       }
     },
     "exclusive_areas": {
       "type": "array",
+      "description": "Path prefixes or glob patterns that trigger a plan collision when two concurrent plans both declare changes to the same exclusive area.",
       "items": {
         "type": "string"
       }
     },
     "required_modes": {
       "type": "array",
+      "description": "Gate modes that must all have passed (status 'pass' in state.gates) before a merge is allowed.",
       "items": {
         "type": "string"
       },
       "minItems": 1
     },
     "required_merge_mode": {
-      "type": "string"
+      "type": "string",
+      "description": "Additional gate mode that must have passed immediately before merge (typically 'merge'), on top of required_modes."
     },
     "collision_policy": {
       "type": "string",
+      "description": "'reject' immediately fails a colliding plan submission; 'block' queues the plan in index.blocked_queue until the conflicting feature merges.",
       "enum": [
         "reject",
         "block"
       ]
     },
     "config_precedence": {
-      "type": "object"
+      "type": "object",
+      "description": "Reserved for future layered-config precedence rules. Currently persisted but not evaluated by the runtime."
     },
     "path_rules": {
       "type": "object",
+      "description": "Controls how file paths are matched and normalised when validating patches against plans.",
       "required": [
         "matching",
         "normalize_paths",
@@ -178,6 +207,7 @@
       "properties": {
         "matching": {
           "type": "string",
+          "description": "'repo_prefix' uses a simple string-prefix check; 'glob' uses minimatch glob patterns for allowed_areas and forbidden_areas.",
           "enum": [
             "repo_prefix",
             "glob"
@@ -185,15 +215,18 @@
         },
         "normalize_paths": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Must be true. Ensures all patch paths are resolved to repo-relative form before comparison."
         },
         "allow_symlink_traversal": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When false, path normalisation rejects paths that would escape the repository root via symlinks."
         }
       }
     },
     "execution": {
       "type": "object",
+      "description": "Settings governing how gate step commands are executed and retried.",
       "required": [
         "default_step_timeout_seconds",
         "retry_policy",
@@ -202,10 +235,12 @@
       "properties": {
         "default_step_timeout_seconds": {
           "type": "number",
-          "minimum": 1
+          "minimum": 1,
+          "description": "Default execution timeout applied to each gate step that does not declare its own timeout_seconds."
         },
         "retry_policy": {
           "type": "object",
+          "description": "Governs automatic retries for transient gate execution failures.",
           "required": [
             "transient_max_retries",
             "transient_error_codes",
@@ -214,16 +249,19 @@
           "properties": {
             "transient_max_retries": {
               "type": "number",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Maximum number of retry attempts for errors whose exit code appears in transient_error_codes."
             },
             "transient_error_codes": {
               "type": "array",
+              "description": "Process exit codes considered transient and eligible for automatic retry.",
               "items": {
                 "type": "number"
               }
             },
             "non_retryable_error_codes": {
               "type": "array",
+              "description": "Process exit codes that immediately abort the gate run without any retry attempt.",
               "items": {
                 "type": "number"
               }
@@ -232,6 +270,7 @@
         },
         "env_allowlist": {
           "type": "array",
+          "description": "Environment variable names from the host process that are forwarded into gate step subprocesses. All other env vars are stripped.",
           "items": {
             "type": "string"
           }
@@ -240,18 +279,21 @@
     },
     "implementation": {
       "type": "object",
+      "description": "Monorepo tooling configuration used by the kernel when locating project files.",
       "required": [
         "workspace"
       ],
       "properties": {
         "workspace": {
           "type": "string",
-          "const": "nx"
+          "const": "nx",
+          "description": "Monorepo workspace tool. Must be 'nx'; the kernel uses this when resolving project paths."
         }
       }
     },
     "testing": {
       "type": "object",
+      "description": "Test framework and global coverage threshold configuration.",
       "required": [
         "framework",
         "coverage"
@@ -259,10 +301,12 @@
       "properties": {
         "framework": {
           "type": "string",
-          "const": "vitest"
+          "const": "vitest",
+          "description": "Test framework that gate steps use. Must be 'vitest'."
         },
         "coverage": {
           "type": "object",
+          "description": "Global coverage thresholds. Per-profile thresholds in gates.yaml override these when the profile value is higher.",
           "required": [
             "minimums",
             "targets"
@@ -270,6 +314,7 @@
           "properties": {
             "minimums": {
               "type": "object",
+              "description": "Minimum acceptable coverage fractions. A gate run fails if the measured coverage falls below these values.",
               "required": [
                 "line",
                 "branch"
@@ -278,17 +323,20 @@
                 "line": {
                   "type": "number",
                   "minimum": 0,
-                  "maximum": 1
+                  "maximum": 1,
+                  "description": "Minimum line coverage fraction (0\u20131)."
                 },
                 "branch": {
                   "type": "number",
                   "minimum": 0,
-                  "maximum": 1
+                  "maximum": 1,
+                  "description": "Minimum branch coverage fraction (0\u20131)."
                 }
               }
             },
             "targets": {
               "type": "object",
+              "description": "Target (aspirational) coverage fractions used for reporting. Not enforced by the gate runner.",
               "required": [
                 "line",
                 "branch"
@@ -297,12 +345,14 @@
                 "line": {
                   "type": "number",
                   "minimum": 0,
-                  "maximum": 1
+                  "maximum": 1,
+                  "description": "Target line coverage fraction (0\u20131)."
                 },
                 "branch": {
                   "type": "number",
                   "minimum": 0,
-                  "maximum": 1
+                  "maximum": 1,
+                  "description": "Target branch coverage fraction (0\u20131)."
                 }
               }
             }
@@ -312,16 +362,19 @@
     },
     "merge_policy": {
       "type": "object",
+      "description": "Controls when and how the orchestrator may merge a feature branch into the base branch.",
       "required": [
         "require_user_approval",
         "allowed_strategies"
       ],
       "properties": {
         "require_user_approval": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When true, a user-provided approval token must be supplied to the merge tool before the merge proceeds."
         },
         "allowed_strategies": {
           "type": "array",
+          "description": "Merge strategies available to the orchestrator. Requesting an unlisted strategy throws MERGE_DISABLED.",
           "items": {
             "type": "string",
             "enum": [
@@ -335,22 +388,26 @@
     },
     "worktree": {
       "type": "object",
+      "description": "Git worktree configuration controlling how feature branches and working directories are created.",
       "required": [
         "base_branch"
       ],
       "properties": {
         "base_branch": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "Git branch that feature branches are created from and merged into (e.g. 'main')."
         },
         "post_create": {
           "type": "array",
+          "description": "Shell commands run after a new worktree is created, e.g. to install dependencies.",
           "items": {
             "type": "string"
           }
         },
         "symlinks": {
           "type": "array",
+          "description": "Repo-relative paths to symlink into every new feature worktree, e.g. shared secrets or config files.",
           "items": {
             "type": "string"
           }
@@ -359,6 +416,7 @@
     },
     "rbac": {
       "type": "object",
+      "description": "Role-based access control map. Keys are role names (e.g. 'builder'); values are lists of MCP tool names that role is allowed to call.",
       "additionalProperties": {
         "type": "array",
         "items": {
@@ -368,101 +426,126 @@
     },
     "recovery": {
       "type": "object",
+      "description": "Settings for handling orphaned or stale orchestrator sessions at startup.",
       "properties": {
         "orchestrator_session_reattach_timeout_ms": {
           "type": "number",
-          "minimum": 0
+          "minimum": 0,
+          "description": "Milliseconds to wait for an existing orchestrator session to reattach before treating it as orphaned."
         },
         "orphan_session_cleanup_enabled": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When true, orphaned agent sessions detected at startup are automatically cleaned up."
         }
       }
     },
     "supervisor": {
       "type": "object",
+      "description": "Supervisor loop tuning parameters.",
       "additionalProperties": false,
       "properties": {
         "max_iterations_per_phase": {
           "type": "integer",
           "minimum": 0,
-          "default": 6
+          "default": 6,
+          "description": "Maximum agent iterations allowed per phase (planning, build, QA) before the supervisor escalates or fails the feature. Default 6."
         },
         "max_parallel_gate_runs": {
           "type": "integer",
           "minimum": 1,
-          "default": 2
+          "default": 2,
+          "description": "Maximum number of gate runs that may execute concurrently across all active features. Default 2."
         },
         "agent_idle_threshold_ms": {
           "type": "integer",
           "minimum": 0,
-          "default": 300000
+          "default": 300000,
+          "description": "Milliseconds of agent inactivity after which an agent is considered stuck and may trigger the agent_stuck reaction. Default 300000 (5 min)."
         }
       }
     },
     "cleanup": {
       "type": "object",
+      "description": "Controls automatic cleanup of merged feature worktrees and branches.",
       "properties": {
         "auto_after_merge": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "When true, the feature worktree and branch are automatically removed after a successful merge."
         },
         "grace_period_seconds": {
           "type": "number",
-          "minimum": 0
+          "minimum": 0,
+          "description": "Delay in seconds before automatic post-merge cleanup runs, allowing time for CI or post-merge hooks to reference the worktree."
         }
       }
     },
     "dashboard": {
       "type": "object",
+      "description": "Real-time status dashboard HTTP server settings.",
       "properties": {
         "enabled": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether the dashboard HTTP server is started alongside the orchestrator."
         },
         "port": {
           "type": "number",
           "minimum": 1,
-          "maximum": 65535
+          "maximum": 65535,
+          "description": "Port the dashboard HTTP server listens on."
         }
       }
     },
     "notifications": {
       "type": "object",
+      "description": "Notification delivery configuration for orchestrator events.",
       "properties": {
         "enabled": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Master switch for all notification channels."
         },
         "channels": {
           "type": "object",
+          "description": "Per-channel delivery configuration.",
           "properties": {
             "desktop": {
               "type": "object",
+              "description": "Desktop OS notification settings.",
               "properties": {
                 "enabled": {
-                  "type": "boolean"
+                  "type": "boolean",
+                  "description": "Whether desktop OS notifications are sent."
                 }
               }
             },
             "slack": {
               "type": "object",
+              "description": "Slack notification settings.",
               "properties": {
                 "enabled": {
-                  "type": "boolean"
+                  "type": "boolean",
+                  "description": "Whether Slack notifications are sent."
                 },
                 "webhook": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Incoming webhook URL for Slack notifications."
                 },
                 "channel": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Slack channel to post to when using the webhook."
                 }
               }
             },
             "webhook": {
               "type": "object",
+              "description": "Generic outbound HTTP webhook settings.",
               "properties": {
                 "enabled": {
-                  "type": "boolean"
+                  "type": "boolean",
+                  "description": "Whether the outbound HTTP webhook is called for notifications."
                 },
                 "url": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "URL of the outbound webhook endpoint."
                 }
               }
             }
@@ -470,36 +553,42 @@
         },
         "routing": {
           "type": "object",
+          "description": "Maps event severity levels to the channel names that should receive them.",
           "properties": {
             "critical": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "description": "Channel names that receive 'critical' severity events (e.g. budget exceeded, run failure)."
             },
             "urgent": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "description": "Channel names that receive 'urgent' severity events."
             },
             "action": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "description": "Channel names that receive 'action' severity events (e.g. merge ready, user approval needed)."
             },
             "warning": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "description": "Channel names that receive 'warning' severity events (e.g. budget alert, agent stuck)."
             },
             "info": {
               "type": "array",
               "items": {
                 "type": "string"
-              }
+              },
+              "description": "Channel names that receive 'info' severity events."
             }
           }
         }
@@ -507,19 +596,24 @@
     },
     "reactions": {
       "type": "object",
+      "description": "Automated reaction policies that trigger when specific orchestrator events occur.",
       "properties": {
         "gate_failed": {
           "type": "object",
+          "description": "Reaction triggered when a gate run fails.",
           "properties": {
             "enabled": {
-              "type": "boolean"
+              "type": "boolean",
+              "description": "Whether the gate_failed reaction is active."
             },
             "max_retries": {
               "type": "integer",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Maximum number of automatic agent repair attempts before escalating to a human."
             },
             "action": {
               "type": "string",
+              "description": "'retry_with_agent_repair' prompts the builder agent to fix the failure; 'notify_only' sends a notification without retrying.",
               "enum": [
                 "retry_with_agent_repair",
                 "notify_only"
@@ -527,67 +621,84 @@
             },
             "escalate_after": {
               "type": "integer",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Number of consecutive failed repair attempts after which the feature is escalated to a human."
             },
             "retry_delay_ms": {
               "type": "integer",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Milliseconds to wait between gate repair retry attempts."
             }
           }
         },
         "agent_stuck": {
           "type": "object",
+          "description": "Reaction triggered when an agent is detected as idle beyond the configured threshold.",
           "properties": {
             "enabled": {
-              "type": "boolean"
+              "type": "boolean",
+              "description": "Whether the agent_stuck reaction is active."
             },
             "action": {
-              "type": "string"
+              "type": "string",
+              "description": "Action to take when an agent is detected as stuck."
             },
             "idle_threshold_ms": {
               "type": "integer",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Milliseconds of agent inactivity before triggering the stuck reaction. Overrides supervisor.agent_idle_threshold_ms for reaction purposes."
             },
             "escalate_after": {
               "type": "integer",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Number of consecutive stuck detections after which the feature is escalated to a human."
             }
           }
         },
         "collision_detected": {
           "type": "object",
+          "description": "Reaction triggered when a plan collision is detected during plan submission.",
           "properties": {
             "enabled": {
-              "type": "boolean"
+              "type": "boolean",
+              "description": "Whether the collision_detected reaction fires."
             },
             "action": {
-              "type": "string"
+              "type": "string",
+              "description": "Action to take when a plan collision is detected."
             }
           }
         },
         "ready_to_merge": {
           "type": "object",
+          "description": "Reaction triggered when a feature reaches the ready_to_merge status.",
           "properties": {
             "enabled": {
-              "type": "boolean"
+              "type": "boolean",
+              "description": "Whether the ready_to_merge reaction fires."
             },
             "action": {
-              "type": "string"
+              "type": "string",
+              "description": "Action to take when a feature is ready to merge."
             }
           }
         },
         "changes_requested": {
           "type": "object",
+          "description": "Reaction triggered when a PR reviewer requests changes on a feature's pull request.",
           "properties": {
             "enabled": {
-              "type": "boolean"
+              "type": "boolean",
+              "description": "Whether the changes_requested reaction fires."
             },
             "action": {
-              "type": "string"
+              "type": "string",
+              "description": "Action to take when changes are requested on the PR."
             },
             "escalate_after": {
               "type": "integer",
-              "minimum": 0
+              "minimum": 0,
+              "description": "Number of change-request cycles before escalating to a human."
             }
           }
         }
@@ -595,28 +706,46 @@
     },
     "budget": {
       "type": "object",
+      "description": "Agent spend limits. When a feature exceeds per_feature_limit_usd, further agent waves are paused until a human intervenes.",
       "additionalProperties": false,
       "properties": {
         "per_feature_limit_usd": {
           "type": "number",
-          "minimum": 0
+          "minimum": 0,
+          "description": "Maximum estimated USD spend per feature. The supervisor checks this before each wave and blocks over-budget features."
         },
         "alert_threshold": {
           "type": "number",
           "minimum": 0,
-          "maximum": 1
+          "maximum": 1,
+          "description": "Fraction of per_feature_limit_usd (0\u20131) at which a budget_alert notification is sent, before the hard limit is reached."
         }
       }
     },
     "issue_tracker": {
       "type": "object",
+      "description": "Issue tracker integration settings. When enabled, the orchestrator creates and updates issues for features.",
       "additionalProperties": false,
       "properties": {
-        "enabled": { "type": "boolean" },
-        "type": { "type": "string", "enum": ["github", "linear", "jira"] },
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether issue tracker integration is active."
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "github",
+            "linear",
+            "jira"
+          ],
+          "description": "Issue tracker backend: 'github', 'linear', or 'jira'."
+        },
         "config": {
           "type": "object",
-          "additionalProperties": { "type": "string" }
+          "description": "Adapter-specific configuration key-value pairs (e.g. auth tokens, project keys).",
+          "additionalProperties": {
+            "type": "string"
+          }
         }
       }
     }