agentic-orchestrator 0.1.4 → 0.1.6

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

@@ -1,42 +1,83 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/gates.schema.json",
+  "description": "Gate profiles defining the verification steps and coverage thresholds used to validate feature branches.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version", "profiles"],
+  "required": [
+    "version",
+    "profiles"
+  ],
   "properties": {
-    "version": { "type": "number" },
+    "version": {
+      "type": "number",
+      "description": "Schema version number for this gates configuration file."
+    },
     "profiles": {
       "type": "object",
+      "description": "Named gate profiles. A feature's active profile is recorded in plan.gate_profile and referenced by the gate service when running checks.",
       "additionalProperties": {
         "type": "object",
-        "required": ["modes"],
+        "description": "A named gate profile containing one or more execution modes.",
+        "required": [
+          "modes"
+        ],
         "properties": {
           "modes": {
             "type": "object",
+            "description": "Named gate execution modes (e.g. 'fast', 'full', 'merge') each containing an ordered list of steps to run.",
             "additionalProperties": {
               "type": "array",
               "items": {
                 "type": "object",
-                "required": ["name", "cmd"],
+                "required": [
+                  "name",
+                  "cmd"
+                ],
                 "additionalProperties": false,
                 "properties": {
-                  "name": { "type": "string", "minLength": 1 },
+                  "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Unique step identifier within the mode. Used as the key in depends_on arrays."
+                  },
                   "cmd": {
                     "type": "array",
                     "minItems": 1,
-                    "items": { "type": "string", "minLength": 1 }
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "description": "Command tokens to execute for this step. The first element is the executable; subsequent elements are arguments."
+                  },
+                  "cwd": {
+                    "type": "string",
+                    "description": "Working directory for the command, relative to the feature worktree. Defaults to the worktree root if omitted."
                   },
-                  "cwd": { "type": "string" },
                   "env": {
                     "type": "object",
-                    "additionalProperties": { "type": "string" }
+                    "additionalProperties": {
+                      "type": "string"
+                    },
+                    "description": "Additional environment variables for this step's subprocess. Only variables listed in policy.execution.env_allowlist are inherited from the host."
+                  },
+                  "timeout_seconds": {
+                    "type": "number",
+                    "minimum": 1,
+                    "description": "Per-step execution timeout in seconds. Falls back to policy.execution.default_step_timeout_seconds when omitted."
+                  },
+                  "parallel_group": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Steps sharing the same parallel_group label may execute concurrently within the mode run."
                   },
-                  "timeout_seconds": { "type": "number", "minimum": 1 },
-                  "parallel_group": { "type": "string", "minLength": 1 },
                   "depends_on": {
                     "type": "array",
-                    "items": { "type": "string", "minLength": 1 }
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "description": "List of step names that must complete successfully before this step starts."
                   }
                 }
               }
@@ -44,16 +85,38 @@
           },
           "parsers": {
             "type": "object",
-            "additionalProperties": true
+            "additionalProperties": true,
+            "description": "Coverage parser configuration for this profile. The 'coverage' key selects the parser type (e.g. { type: 'lcov' })."
           },
           "thresholds": {
             "type": "object",
             "additionalProperties": false,
+            "description": "Per-profile coverage thresholds. These are combined with policy.testing.coverage values (max wins) during gate evaluation.",
             "properties": {
-              "coverage_line_min": { "type": "number", "minimum": 0, "maximum": 1 },
-              "coverage_branch_min": { "type": "number", "minimum": 0, "maximum": 1 },
-              "coverage_line_target": { "type": "number", "minimum": 0, "maximum": 1 },
-              "coverage_branch_target": { "type": "number", "minimum": 0, "maximum": 1 }
+              "coverage_line_min": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum line coverage fraction (0\u20131) required for a gate run to pass. Combined with policy.testing.coverage.minimums.line \u2014 the higher value wins."
+              },
+              "coverage_branch_min": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum branch coverage fraction (0\u20131) required for a gate run to pass."
+              },
+              "coverage_line_target": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Target line coverage fraction (0\u20131) used for reporting and trend tracking, not enforcement."
+              },
+              "coverage_branch_target": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Target branch coverage fraction (0\u20131) used for reporting and trend tracking, not enforcement."
+              }
             }
           }
         }
@@ -61,9 +124,17 @@
     },
     "capabilities": {
       "type": "array",
+      "description": "Coverage format capabilities declared for this project. Used to select the appropriate coverage parser (e.g. 'lcov', 'junit_xml').",
       "items": {
         "type": "string",
-        "enum": ["none", "lcov", "junit_xml", "jacoco_xml", "cobertura_xml", "custom"]
+        "enum": [
+          "none",
+          "lcov",
+          "junit_xml",
+          "jacoco_xml",
+          "cobertura_xml",
+          "custom"
+        ]
       }
     }
   }

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

@@ -1,83 +1,167 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/index.schema.json",
+  "description": "Global feature index stored in .aop/features/index.json. Acts as the single source of truth for all active features, locks, and the current orchestrator run lease.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version", "active", "blocked", "merged", "locks", "lock_leases", "blocked_queue", "runtime_sessions"],
+  "required": [
+    "version",
+    "active",
+    "blocked",
+    "merged",
+    "locks",
+    "lock_leases",
+    "blocked_queue",
+    "runtime_sessions"
+  ],
   "properties": {
-    "version": { "type": "integer", "minimum": 1 },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonically incrementing integer for optimistic concurrency on the index file. Incremented on every index write."
+    },
     "active": {
       "type": "array",
-      "items": { "type": "string" }
+      "description": "Feature IDs currently in an active lifecycle state (planning, building, or qa).",
+      "items": {
+        "type": "string"
+      }
     },
     "blocked": {
       "type": "array",
-      "items": { "type": "string" }
+      "description": "Feature IDs that are blocked (due to collisions, dependency waits, budget overrun, or errors).",
+      "items": {
+        "type": "string"
+      }
     },
     "merged": {
       "type": "array",
-      "items": { "type": "string" }
+      "description": "Feature IDs that have been successfully merged. Used by the dependency scheduler to unblock waiting features.",
+      "items": {
+        "type": "string"
+      }
     },
     "locks": {
       "type": "object",
+      "description": "Current lock holders. Keys are resource names from policy.locks.resources; values are the holding feature_id or null.",
       "additionalProperties": {
         "anyOf": [
-          { "type": "string" },
-          { "type": "null" }
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
         ]
       }
     },
     "lock_leases": {
       "type": "object",
+      "description": "Full lease objects for each lock resource. Used for stale-lease detection and reclamation.",
       "additionalProperties": {
         "anyOf": [
           {
             "type": "object",
-            "required": ["holder", "lease_id", "expires_at"],
+            "required": [
+              "holder",
+              "lease_id",
+              "expires_at"
+            ],
             "properties": {
-              "holder": { "type": "string" },
-              "lease_id": { "type": "string" },
-              "expires_at": { "type": "string", "format": "date-time" }
+              "holder": {
+                "type": "string",
+                "description": "Feature ID that holds this lease."
+              },
+              "lease_id": {
+                "type": "string",
+                "description": "UUID for the current lease, generated on acquisition and rotated on renewal."
+              },
+              "expires_at": {
+                "type": "string",
+                "format": "date-time",
+                "description": "ISO 8601 expiry time. Leases past this timestamp are eligible for stale reclamation by any feature calling locksAcquire."
+              }
             }
           },
-          { "type": "null" }
+          {
+            "type": "null"
+          }
         ]
       }
     },
     "blocked_queue": {
       "type": "array",
+      "description": "Queue of features waiting for a lock after a collision when collision_policy is 'block'. Entries are ordered by detected_at and re-driven when a lock is released.",
       "items": {
         "type": "object",
-        "required": ["feature_id", "plan_version", "detected_at", "collision_fingerprint", "required_resources"],
+        "required": [
+          "feature_id",
+          "plan_version",
+          "detected_at",
+          "collision_fingerprint",
+          "required_resources"
+        ],
         "properties": {
-          "feature_id": { "type": "string" },
-          "plan_version": { "type": "integer", "minimum": 1 },
-          "detected_at": { "type": "string", "format": "date-time" },
-          "collision_fingerprint": { "type": "string" },
+          "feature_id": {
+            "type": "string",
+            "description": "Feature ID waiting to re-submit its plan once the conflicting feature's locks are released."
+          },
+          "plan_version": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Version of the plan that triggered the block; used to re-validate on re-drive."
+          },
+          "detected_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp when the collision was first detected."
+          },
+          "collision_fingerprint": {
+            "type": "string",
+            "description": "Stable hash of the collision set, used to deduplicate queue entries."
+          },
           "required_resources": {
             "type": "array",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string"
+            },
+            "description": "Lock resource names this feature must acquire before its plan can be accepted."
           }
         }
       }
     },
-    "updated_at": { "type": "string", "format": "date-time" },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the most recent index write."
+    },
     "dep_blocked": {
       "type": "array",
+      "description": "Features whose plan submission was deferred because one or more declared feature dependencies have not yet merged.",
       "items": {
         "type": "object",
-        "required": ["feature_id", "depends_on_unresolved"],
+        "required": [
+          "feature_id",
+          "depends_on_unresolved"
+        ],
         "properties": {
-          "feature_id": { "type": "string" },
+          "feature_id": {
+            "type": "string",
+            "description": "Feature waiting for its dependencies to merge."
+          },
           "depends_on_unresolved": {
             "type": "array",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string"
+            },
+            "description": "IDs of dependency features that have not yet merged. When this list becomes empty the feature is automatically unblocked."
           }
         }
       }
     },
     "runtime_sessions": {
       "type": "object",
+      "description": "Current orchestrator run lease. Acts as a distributed mutex: only one supervisor may hold this at a time. Stored both inside index.json and in a separate run-lease file.",
       "additionalProperties": false,
       "required": [
         "run_id",
@@ -92,27 +176,78 @@
         "lease_expires_at"
       ],
       "properties": {
-        "run_id": { "type": "string" },
-        "orchestrator_session_id": { "type": "string" },
-        "provider": { "type": "string" },
-        "model": { "type": "string" },
-        "provider_config_ref_hash": { "type": "string" },
-        "owner_instance_id": { "type": "string" },
-        "lease_id": { "type": "string" },
-        "started_at": { "type": "string", "format": "date-time" },
-        "last_heartbeat_at": { "type": "string", "format": "date-time" },
-        "lease_expires_at": { "type": "string", "format": "date-time" },
-        "orchestrator_epoch": { "type": "integer", "minimum": 0 },
+        "run_id": {
+          "type": "string",
+          "description": "Stable identifier for the current orchestrator run, set at supervisor startup."
+        },
+        "orchestrator_session_id": {
+          "type": "string",
+          "description": "AI session ID of the orchestrator agent. Updated each time the orchestrator reconnects or starts a new session."
+        },
+        "provider": {
+          "type": "string",
+          "description": "AI provider name in use for this run (e.g. 'claude', 'codex')."
+        },
+        "model": {
+          "type": "string",
+          "description": "AI model string in use for this run."
+        },
+        "provider_config_ref_hash": {
+          "type": "string",
+          "description": "Stable hash of the resolved provider configuration. Used to detect config drift between runs."
+        },
+        "owner_instance_id": {
+          "type": "string",
+          "description": "Unique identifier for the supervisor process instance, combining PID and a random UUID."
+        },
+        "lease_id": {
+          "type": "string",
+          "description": "UUID of the current run lease, rotated on each acquisition or renewal."
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when the current run began."
+        },
+        "last_heartbeat_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of the most recent heartbeat from the lease-heartbeat service."
+        },
+        "lease_expires_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 time after which the run lease is considered stale and may be taken over by a new supervisor."
+        },
+        "orchestrator_epoch": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Monotonic integer incremented each time the orchestrator session ID changes. Used to invalidate cached worker session assignments."
+        },
         "feature_sessions": {
           "type": "object",
+          "description": "Per-feature agent session assignments keyed by feature_id. Used by SessionOrchestrator to reuse or close agent sessions across runs.",
           "additionalProperties": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["planner_session_id", "builder_session_id", "qa_session_id"],
+            "required": [
+              "planner_session_id",
+              "builder_session_id",
+              "qa_session_id"
+            ],
             "properties": {
-              "planner_session_id": { "type": "string" },
-              "builder_session_id": { "type": "string" },
-              "qa_session_id": { "type": "string" }
+              "planner_session_id": {
+                "type": "string",
+                "description": "AI session ID of the planner agent for this feature."
+              },
+              "builder_session_id": {
+                "type": "string",
+                "description": "AI session ID of the builder agent for this feature."
+              },
+              "qa_session_id": {
+                "type": "string",
+                "description": "AI session ID of the QA agent for this feature."
+              }
             }
           }
         }

package/agentic/orchestrator/schemas/multi-project.schema.json

@@ -1,39 +1,107 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/multi-project.schema.json",
+  "description": "Multi-project workspace configuration stored in agentic/orchestrator/multi-project.yaml. Defines multiple repository projects managed by a single orchestrator installation.",
   "type": "object",
-  "required": ["version", "projects"],
+  "required": [
+    "version",
+    "projects"
+  ],
   "additionalProperties": false,
   "properties": {
-    "version": { "type": "string", "pattern": "^1\\.0$" },
+    "version": {
+      "type": "string",
+      "pattern": "^1\\.0$",
+      "description": "Configuration format version. Must be '1.0'."
+    },
     "defaults": {
       "type": "object",
+      "description": "Default values applied to all projects unless overridden at the project level.",
       "additionalProperties": false,
       "properties": {
-        "max_active_features": { "type": "integer", "minimum": 1 },
-        "max_parallel_gate_runs": { "type": "integer", "minimum": 1 },
-        "dashboard_port": { "type": "integer", "minimum": 1, "maximum": 65535 },
-        "default_project": { "type": "string", "minLength": 1 },
-        "policy": { "type": "string" },
-        "gates": { "type": "string" },
-        "notifications": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }
+        "max_active_features": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Default maximum number of concurrently active features per project."
+        },
+        "max_parallel_gate_runs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Default maximum number of parallel gate runs per project."
+        },
+        "dashboard_port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "description": "Default dashboard HTTP port used when a project does not specify its own dashboard_port."
+        },
+        "default_project": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Name of the project to use when no --project flag is provided on the CLI."
+        },
+        "policy": {
+          "type": "string",
+          "description": "Default path to a policy.yaml override file. Applied to projects that do not specify their own policy path."
+        },
+        "gates": {
+          "type": "string",
+          "description": "Default path to a gates.yaml override file. Applied to projects that do not specify their own gates path."
+        },
+        "notifications": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Default notification enabled/disabled setting for all projects."
+            }
+          }
+        }
       }
     },
     "projects": {
       "type": "array",
+      "description": "Ordered list of project configurations managed by this orchestrator installation.",
       "minItems": 1,
       "items": {
         "type": "object",
-        "required": ["name", "path"],
+        "required": [
+          "name",
+          "path"
+        ],
         "additionalProperties": false,
         "properties": {
-          "name": { "type": "string", "minLength": 1 },
-          "path": { "type": "string" },
-          "repo": { "type": "string" },
-          "branch": { "type": "string" },
-          "policy": { "type": "string" },
-          "gates": { "type": "string" },
-          "dashboard_port": { "type": "integer", "minimum": 1, "maximum": 65535 }
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Unique short name for the project, used with the --project CLI flag."
+          },
+          "path": {
+            "type": "string",
+            "description": "Filesystem path to the project root. May be absolute, relative to the multi-project config file, or use ~ home expansion."
+          },
+          "repo": {
+            "type": "string",
+            "description": "Optional URL of the project's git remote. Currently informational only."
+          },
+          "branch": {
+            "type": "string",
+            "description": "Optional default branch override for this project."
+          },
+          "policy": {
+            "type": "string",
+            "description": "Optional path to a policy.yaml override for this project, relative to the project path."
+          },
+          "gates": {
+            "type": "string",
+            "description": "Optional path to a gates.yaml override for this project, relative to the project path."
+          },
+          "dashboard_port": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535,
+            "description": "Port for this project's dashboard HTTP server. Overrides defaults.dashboard_port."
+          }
         }
       }
     }