agentic-orchestrator 0.1.4 → 0.1.6

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.local/agentic/plan.schema.json",
+  "description": "Feature plan submitted by the planner agent and stored in .aop/features/<id>/plan.json. Governs which files and contracts the builder agent may touch.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -18,82 +19,169 @@
   "properties": {
     "feature_id": {
       "type": "string",
-      "pattern": "^[a-z0-9_][a-z0-9_-]*$"
+      "pattern": "^[a-z0-9_][a-z0-9_-]*$",
+      "description": "Identifier of the feature this plan belongs to. Must match the enclosing feature ID and the state's feature_id."
     },
     "plan_version": {
       "type": "integer",
-      "minimum": 1
+      "minimum": 1,
+      "description": "Monotonically incrementing plan version. The first plan must be version 1; each revision must increment by exactly 1."
     },
     "summary": {
       "type": "string",
-      "minLength": 5
+      "minLength": 5,
+      "description": "Human-readable description of what this feature implements or changes."
     },
     "allowed_areas": {
       "type": "array",
-      "items": { "type": "string", "minLength": 1 },
-      "minItems": 1
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "description": "Path prefixes or glob patterns that agent patches are permitted to touch. Enforced by patch_policy.enforce_allowed_areas."
     },
     "forbidden_areas": {
       "type": "array",
-      "items": { "type": "string", "minLength": 1 }
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Path prefixes or glob patterns that agent patches must not touch, regardless of allowed_areas."
     },
     "base_ref": {
       "type": "string",
-      "minLength": 1
+      "minLength": 1,
+      "description": "Git ref (branch name or commit SHA) from which the feature worktree was created."
     },
     "files": {
       "type": "object",
+      "description": "Planned file operations. When a plan is present, every patched file must appear in one of these lists.",
       "additionalProperties": false,
-      "required": ["create", "modify", "delete"],
+      "required": [
+        "create",
+        "modify",
+        "delete"
+      ],
       "properties": {
-        "create": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-        "modify": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-        "delete": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+        "create": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Files the plan intends to create. Patches creating unlisted files are rejected when a plan exists."
+        },
+        "modify": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Files the plan intends to modify. Patches modifying unlisted files are rejected when a plan exists."
+        },
+        "delete": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Files the plan intends to delete."
+        }
       }
     },
     "contracts": {
       "type": "object",
+      "description": "Declares which shared contract types this plan modifies. Each 'modify' or 'migration' value triggers a lock requirement.",
       "additionalProperties": false,
-      "required": ["openapi", "events", "db"],
+      "required": [
+        "openapi",
+        "events",
+        "db"
+      ],
       "properties": {
-        "openapi": { "type": "string", "enum": ["none", "modify"] },
-        "events": { "type": "string", "enum": ["none", "modify"] },
-        "db": { "type": "string", "enum": ["none", "migration"] }
+        "openapi": {
+          "type": "string",
+          "enum": [
+            "none",
+            "modify"
+          ],
+          "description": "'modify' means this plan changes the OpenAPI contract file, requiring the 'openapi' lock to be held before plan submission."
+        },
+        "events": {
+          "type": "string",
+          "enum": [
+            "none",
+            "modify"
+          ],
+          "description": "'modify' means this plan changes the events contract file, requiring the 'events' lock."
+        },
+        "db": {
+          "type": "string",
+          "enum": [
+            "none",
+            "migration"
+          ],
+          "description": "'migration' means this plan adds a database schema migration, requiring the 'db' lock."
+        }
       }
     },
     "acceptance_criteria": {
       "type": "array",
-      "items": { "type": "string", "minLength": 1 },
-      "minItems": 1
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "description": "Human-readable conditions that must all be met before the feature is considered complete and ready for merge."
+    },
+    "gate_profile": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the gates profile to apply to this feature. Written to state.gate_profile on plan acceptance."
     },
-    "gate_profile": { "type": "string", "minLength": 1 },
     "gate_targets": {
       "type": "array",
-      "items": { "type": "string", "minLength": 1 },
-      "minItems": 1
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "description": "Optional explicit list of gate mode names to run. When omitted the profile's full mode set is used."
     },
     "risk": {
       "type": "array",
-      "items": { "type": "string", "minLength": 1 }
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Free-text notes about known risks, edge cases, or areas needing extra care during implementation."
     },
     "revision_of": {
       "type": "integer",
-      "minimum": 1
+      "minimum": 1,
+      "description": "plan_version of the previous plan this revision supersedes. Must equal expectedPlanVersion when updating a plan."
     },
     "revision_reason": {
       "type": "string",
-      "minLength": 1
+      "minLength": 1,
+      "description": "Human-readable explanation of why this plan revision was made."
     },
     "verification_overrides": {
       "type": "object",
+      "description": "Per-mode step overrides that replace the profile's default steps for this specific feature only.",
       "additionalProperties": false,
       "properties": {
         "modes": {
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "fast": { "$ref": "#/$defs/modeOverride" },
-            "full": { "$ref": "#/$defs/modeOverride" }
+            "fast": {
+              "$ref": "#/$defs/modeOverride"
+            },
+            "full": {
+              "$ref": "#/$defs/modeOverride"
+            }
           }
         }
       }
@@ -102,22 +190,39 @@
   "$defs": {
     "modeOverride": {
       "type": "object",
+      "description": "Override steps for a single gate mode. Replaces the profile's default step list for this feature.",
       "additionalProperties": false,
       "properties": {
         "steps": {
           "type": "array",
+          "description": "Replacement step list for this mode.",
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["name", "cmd"],
+            "required": [
+              "name",
+              "cmd"
+            ],
             "properties": {
-              "name": { "type": "string", "minLength": 1 },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Step identifier."
+              },
               "cmd": {
                 "type": "array",
-                "items": { "type": "string", "minLength": 1 },
-                "minItems": 1
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 1,
+                "description": "Command tokens to execute."
               },
-              "timeout_seconds": { "type": "number", "minimum": 1 }
+              "timeout_seconds": {
+                "type": "number",
+                "minimum": 1,
+                "description": "Timeout in seconds for this step."
+              }
             }
           }
         }