vinta-ai-workflows 0.6.1 → 0.7.0-alpha2

package/schemas/postmortem.v1.schema.json

@@ -0,0 +1,339 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/postmortem.v1.schema.json",
+  "title": "vinta-ai-maestro plan post-mortem",
+  "description": "What one finished `vinta-ai-maestro` run learned about the plan that produced it: dependencies that were never used, dependencies discovered missing, same-wave phases that conflicted, and phases whose duration diverged from their wave. Ids, waves, paths, durations and counts only. Lives at `.vinta-ai-maestro/runs/<run-id>/postmortem.json` in a target project, emitted by `vinta-ai-maestro` after a run ends and read by `plan-feature` when planning the next feature in the same repo. GENERATED from packages/vinta-ai-maestro/src/postmortem/postmortem.ts — edit there, not here. See schemas/README.md for versioning rules.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Optional URL of this schema, for editor validation. Ignored at runtime.",
+      "type": "string"
+    },
+    "schema_version": {
+      "type": "number",
+      "const": 1,
+      "description": "Schema major version. Bumped only on breaking changes."
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "workflow_id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "The workflow this run executed."
+    },
+    "plan_ref": {
+      "description": "The human-readable plan the workflow was emitted alongside, if it named one.",
+      "type": "string"
+    },
+    "run": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "done",
+            "failed"
+          ]
+        },
+        "started_at_ms": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        "ended_at_ms": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        "elapsed_ms": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        "node_count": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "wave_count": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "status",
+        "started_at_ms",
+        "ended_at_ms",
+        "elapsed_ms",
+        "node_count",
+        "wave_count"
+      ],
+      "additionalProperties": false,
+      "description": "The run this describes. Always finished — an unfinished run has no post-mortem."
+    },
+    "findings": {
+      "type": "object",
+      "properties": {
+        "unused_dependencies": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "node": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "description": "The dependent phase."
+              },
+              "depends_on": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "description": "The upstream phase the edge names."
+              }
+            },
+            "required": [
+              "node",
+              "depends_on"
+            ],
+            "additionalProperties": false,
+            "description": "One dependency edge, by id. The plan’s own `artifact` prose is deliberately not carried: the reader has the plan, and this file must stay free of repository text."
+          },
+          "description": "Edges whose artifact the dependent never needed. Empty on every run today: nothing observes dependency use, and the schedule cannot substitute. See `gaps`."
+        },
+        "missing_dependencies": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "node": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "description": "The phase that failed and later passed."
+              },
+              "depends_on": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "description": "The undeclared phase that landed in between."
+              },
+              "failed_at_ms": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "When the phase first failed."
+              },
+              "landed_at_ms": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "When the undeclared phase reached `done`."
+              },
+              "passed_at_ms": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "When the phase finally reached `done`."
+              },
+              "gate": {
+                "description": "The gate whose recorded result is the evidence: it failed at `failed_at_ms` and passed at `passed_at_ms`. Absent when the run recorded no gate result for the phase and the window came from its status transitions instead — a weaker signal, flagged in `gaps`.",
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              }
+            },
+            "required": [
+              "node",
+              "depends_on",
+              "failed_at_ms",
+              "landed_at_ms",
+              "passed_at_ms"
+            ],
+            "additionalProperties": false,
+            "description": "A dependency the run discovered and the plan did not declare: the phase failed, an undeclared phase landed, and only then did it pass. The evidence is still ordering — a recorded gate result narrows the window to one gate and rules out an unrelated failure, but it does not prove the undeclared phase is what fixed it. Confirm the edge against the plan before adding it."
+          }
+        },
+        "wave_conflicts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "wave": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "The wave whose merge produced the conflict."
+              },
+              "nodes": {
+                "minItems": 2,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[a-z0-9][a-z0-9-]*$"
+                },
+                "description": "The phases that both own the contested paths."
+              },
+              "paths": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Repository paths that conflicted. Paths, never hunks."
+              },
+              "fix_rounds": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Conflict-fixer rounds the resolution took. High is a strong split signal."
+              }
+            },
+            "required": [
+              "wave",
+              "nodes",
+              "paths",
+              "fix_rounds"
+            ],
+            "additionalProperties": false,
+            "description": "Two same-wave phases that actually fought over the same code at integration."
+          }
+        },
+        "duration_divergences": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "node": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              },
+              "wave": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991
+              },
+              "span_ms": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "Dispatch to final settle, including fix rounds."
+              },
+              "wave_baseline_ms": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "Median span of the *other* dispatched phases in the same wave."
+              },
+              "ratio": {
+                "type": "number",
+                "description": "`span_ms / wave_baseline_ms`, rounded to two decimals."
+              },
+              "direction": {
+                "type": "string",
+                "enum": [
+                  "longer",
+                  "shorter"
+                ],
+                "description": "`longer`: the phase set the wave’s wall clock on its own."
+              }
+            },
+            "required": [
+              "node",
+              "wave",
+              "span_ms",
+              "wave_baseline_ms",
+              "ratio",
+              "direction"
+            ],
+            "additionalProperties": false,
+            "description": "A phase whose real duration was wildly out of line with its wave placement — which is exactly what makes the next plan’s parallelism estimate wrong."
+          }
+        }
+      },
+      "required": [
+        "unused_dependencies",
+        "missing_dependencies",
+        "wave_conflicts",
+        "duration_divergences"
+      ],
+      "additionalProperties": false
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "dependency_use_unrecorded",
+              "gate_result_unrecorded",
+              "integration_record_unavailable"
+            ]
+          },
+          "needs": {
+            "type": "string",
+            "description": "What would have to be recorded for the finding to exist."
+          },
+          "edges": {
+            "description": "The edges the gap applies to.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "node": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[a-z0-9][a-z0-9-]*$",
+                  "description": "The dependent phase."
+                },
+                "depends_on": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[a-z0-9][a-z0-9-]*$",
+                  "description": "The upstream phase the edge names."
+                }
+              },
+              "required": [
+                "node",
+                "depends_on"
+              ],
+              "additionalProperties": false,
+              "description": "One dependency edge, by id. The plan’s own `artifact` prose is deliberately not carried: the reader has the plan, and this file must stay free of repository text."
+            }
+          },
+          "nodes": {
+            "description": "The phases the gap applies to.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[a-z0-9][a-z0-9-]*$"
+            }
+          }
+        },
+        "required": [
+          "kind",
+          "needs"
+        ],
+        "additionalProperties": false,
+        "description": "A finding this run could not produce, and why. Carried in the artifact rather than thrown or defaulted to an empty list: a reader that treats an empty finding as “nothing happened” has to reach past an explicit statement that nothing was recorded."
+      }
+    }
+  },
+  "required": [
+    "schema_version",
+    "run_id",
+    "workflow_id",
+    "run",
+    "findings",
+    "gaps"
+  ],
+  "additionalProperties": false
+}

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -312,9 +312,21 @@
               "default": false
             },
             "use_worktree": {
-              "description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision an isolated git worktree (via `prepare-worktree`) and run every phase's subagent inside it. False = run in the current checkout. True = create one shared worktree at the start of the plan run; all phase branches stack inside it. Per-run prompt still asks; this is the suggested default shown.",
+              "description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision isolated git worktrees (via `prepare-worktree`) and run phase subagents inside them. False = run in the current checkout. True = provision at the start of the plan run: one shared worktree for a sequential run, or one lane per concurrent phase plus an integration worktree when `parallel_phases` is on. Per-run prompt still asks; this is the suggested default shown.",
               "type": "boolean",
               "default": false
+            },
+            "parallel_phases": {
+              "description": "Default answer to Step 0 question (e) — whether `implement-plan` implements independent phases concurrently, one git worktree lane per in-flight phase. The plan's per-phase `**Depends on**:` lines define the graph; a phase starts as soon as every phase it depends on is green. True (default) = run in parallel whenever the graph has a wave wider than one phase. False = one phase at a time. Requires `foundation_skills.prepare-worktree` enabled and `use_worktree` resolving true — several agents cannot share one working tree — and `implement-plan` refuses rather than silently degrading when that is not the case. Per-run prompt still asks; this is the suggested default shown.",
+              "type": "boolean",
+              "default": true
+            },
+            "max_parallel_lanes": {
+              "description": "Upper bound on how many phases `implement-plan` keeps in flight at once, and therefore how many worktree lanes it provisions. Capped at runtime by the widest wave in the plan's dependency graph — a chain-shaped plan provisions one lane regardless. Each lane costs one runnable checkout (deps + forked dev/test DBs + its own compose project), so raise this only on machines with the disk and CPU for it. Ignored when `parallel_phases` is false.",
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 8,
+              "default": 3
             }
           }
         },