mandrel 1.93.0 → 2.0.0

package/.agents/schemas/dispatch-manifest.json

@@ -1,232 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "dispatch-manifest",
-  "title": "Dispatch Manifest",
-  "description": "Output of dispatcher.js (epic-dispatch variant) and orchestration/story-executor.js (story-execution variant). Written to temp/dispatch-manifest-<epicId>.json for the epic-dispatch variant. The two variants are discriminated by the `type` field. 2-tier shape only (Epic #3078): manifests are Story-only — there is no Task-level fan-out. Open-root by design — the AJV fixture drift test is the enforcement boundary; see docs/decisions.md ADR 20260427-868a.",
-  "type": "object",
-  "required": ["generatedAt", "dryRun"],
-  "properties": {
-    "type": {
-      "type": "string",
-      "enum": ["epic-dispatch", "story-execution"],
-      "description": "Discriminator for the manifest variant."
-    },
-    "schemaVersion": {
-      "type": "string",
-      "description": "Schema version for forward-compatibility checks. Emitted by the epic-dispatch variant.",
-      "examples": ["2.0.0"]
-    },
-    "generatedAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "ISO-8601 timestamp when this manifest was produced."
-    },
-    "epicId": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "GitHub Issue number of the Epic."
-    },
-    "epicTitle": {
-      "type": "string",
-      "description": "Title of the Epic issue."
-    },
-    "executor": {
-      "type": "string",
-      "description": "The executor identifier used for this dispatch cycle (e.g., 'claude-code').",
-      "examples": ["claude-code"]
-    },
-    "dryRun": {
-      "type": "boolean",
-      "description": "If true, no branches were created and no Stories were dispatched."
-    },
-    "protocolVersionMismatch": {
-      "type": "boolean",
-      "description": "True if any Story's generation-time protocol version differs from the current runtime version."
-    },
-    "agentTelemetry": {
-      "type": ["object", "null"],
-      "description": "Optional runtime telemetry attached by the executor. Open-shape: any executor-defined fields are allowed.",
-      "additionalProperties": true
-    },
-    "hierarchy": {
-      "type": "string",
-      "const": "2-tier",
-      "description": "Hierarchy identifier. 2-tier is the only supported shape (Epic #3078)."
-    },
-    "summary": {
-      "type": "object",
-      "required": [
-        "totalStories",
-        "doneStories",
-        "progressPercent",
-        "totalWaves",
-        "dispatched"
-      ],
-      "properties": {
-        "totalStories": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Story-centric count for the 2-tier shape (Epic #3078)."
-        },
-        "doneStories": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Number of Stories that have reached agent::done."
-        },
-        "progressPercent": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 100
-        },
-        "totalWaves": {
-          "type": "integer",
-          "minimum": 0
-        },
-        "dispatched": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Number of Stories dispatched in this invocation."
-        }
-      },
-      "additionalProperties": false
-    },
-    "waves": {
-      "type": "array",
-      "description": "Ordered list of execution waves computed from the Story DAG.",
-      "items": {
-        "type": "object",
-        "required": ["waveIndex", "stories"],
-        "properties": {
-          "waveIndex": {
-            "type": "integer",
-            "minimum": 0
-          },
-          "stories": {
-            "type": "array",
-            "description": "Story-centric wave entries. Each entry describes one Story dispatched in this wave, with inline acceptance/verify so the wave can run without re-fetching Story tickets.",
-            "items": {
-              "type": "object",
-              "required": [
-                "storyId",
-                "title",
-                "persona",
-                "acceptance",
-                "verify",
-                "dependsOn"
-              ],
-              "properties": {
-                "storyId": { "type": "integer", "minimum": 1 },
-                "title": { "type": "string" },
-                "persona": { "type": "string" },
-                "acceptance": {
-                  "type": "array",
-                  "description": "Inline acceptance criteria for the Story (markdown checklist lines).",
-                  "items": { "type": "string" }
-                },
-                "verify": {
-                  "type": "array",
-                  "description": "Inline verify commands or shell snippets run by the pre-close acceptance self-eval critic as required, binding evidence that the Story's acceptance criteria are met — NOT by the close-validation gate chain (which runs only the canonical gate list).",
-                  "items": { "type": "string" }
-                },
-                "dependsOn": {
-                  "type": "array",
-                  "description": "Story-level dependencies (Story IDs that must reach agent::done before this Story dispatches).",
-                  "items": { "type": "integer" }
-                },
-                "branch": {
-                  "type": "string",
-                  "description": "Optional Story branch name (e.g., story-3098). Omitted when the runtime derives it from storyId."
-                },
-                "status": {
-                  "type": "string",
-                  "enum": [
-                    "agent::ready",
-                    "agent::executing",
-                    "agent::done",
-                    "status::blocked"
-                  ]
-                }
-              },
-              "additionalProperties": false
-            }
-          }
-        },
-        "additionalProperties": false
-      }
-    },
-    "dispatched": {
-      "type": "array",
-      "description": "Stories dispatched during this invocation.",
-      "items": {
-        "type": "object",
-        "required": ["storyId", "dispatchId", "status"],
-        "properties": {
-          "storyId": { "type": "integer", "minimum": 1 },
-          "dispatchId": { "type": "string" },
-          "status": {
-            "type": "string",
-            "enum": ["dispatched", "queued"]
-          }
-        },
-        "additionalProperties": false
-      }
-    },
-    "stories": {
-      "type": "array",
-      "description": "Story-execution variant payload — one entry per Story this manifest covers.",
-      "items": {
-        "type": "object",
-        "required": ["storyId", "storyTitle", "branchName"],
-        "properties": {
-          "storyId": { "type": "integer", "minimum": 1 },
-          "storyTitle": { "type": "string" },
-          "epicId": {
-            "type": ["integer", "null"],
-            "minimum": 1
-          },
-          "epicBranch": { "type": ["string", "null"] },
-          "branchName": { "type": "string" },
-          "status": {
-            "type": "string",
-            "enum": [
-              "agent::ready",
-              "agent::executing",
-              "agent::done",
-              "status::blocked"
-            ]
-          }
-        },
-        "additionalProperties": false
-      }
-    }
-  },
-  "oneOf": [
-    {
-      "title": "epic-dispatch variant",
-      "description": "Output of dispatcher.js / buildManifest(). The `type` field may be absent for back-compat; presence is restricted to 'epic-dispatch'. The 4-tier `storyManifest[]` collection is explicitly forbidden (Epic #3078 cutover).",
-      "properties": {
-        "type": { "const": "epic-dispatch" },
-        "storyManifest": false
-      },
-      "required": [
-        "schemaVersion",
-        "epicId",
-        "epicTitle",
-        "executor",
-        "summary",
-        "waves",
-        "dispatched"
-      ],
-      "not": { "required": ["stories"] }
-    },
-    {
-      "title": "story-execution variant",
-      "description": "Output of orchestration/story-executor.js / executeStory(). The 4-tier `storyManifest[]` collection is explicitly forbidden (Epic #3078 cutover).",
-      "properties": {
-        "type": { "const": "story-execution" },
-        "storyManifest": false
-      },
-      "required": ["type", "stories"]
-    }
-  ]
-}

package/.agents/schemas/epic-spec.schema.json

@@ -1,153 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/epic-spec.schema.json",
-  "version": "4.0.0",
-  "title": "Epic Spec (declarative structural SSOT)",
-  "description": "Canonical structural specification for an Epic and its child Stories, consumed by the epic-spec-reconciler. Lives on disk as .agents/epics/<epic-id>.yaml. The reconciler diffs this spec against live GitHub state and applies structural mutations (Create/Update/Close/Relink) behind a dry-run default. Slugs are stable, GH-incarnation-independent identifiers used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping persisted in the sibling .agents/epics/<epic-id>.state.json. This schema describes the 2-tier structural shape only (Epic → Story with inline Story-level acceptance[]/verify[]); agent-execution state (agent::* labels) is intentionally not modelled — that surface belongs to the wave-runner, not the reconciler.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["epic", "stories"],
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "description": "Relative or absolute reference to this schema file. Allowed at the top level so YAML editors with $schema-aware autocomplete (e.g. the Red Hat YAML extension) can resolve the schema from the spec file itself."
-    },
-    "version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Optional schema-shape identifier. Identification-only — readers MUST NOT branch behavior on this value. Bumped to 4.0.0 when the Feature tier was removed under the 2-tier collapse (Story #4041); 3.0.0 removed Task-level decomposition (Epic #3078)."
-    },
-    "epic": {
-      "$ref": "#/$defs/epic",
-      "description": "The Epic this spec describes. Carries the GH issue number, human title, and structural labels (type::epic plus any project-specific structural tags). Execution-state labels (agent::*) MUST NOT appear here."
-    },
-    "stories": {
-      "type": "array",
-      "description": "Ordered list of Stories under this Epic. Order is preserved for human readability but is not load-bearing — execution order is driven by stories[].wave + dependsOn, not by array position.",
-      "items": { "$ref": "#/$defs/story" }
-    },
-    "gates": {
-      "$ref": "#/$defs/gates",
-      "description": "Optional references to baseline + gate-config slugs resolved by the baseline subsystem. Carried in the spec so structural changes can be reviewed alongside the quality-gate config that will run against them."
-    }
-  },
-  "$defs": {
-    "slug": {
-      "type": "string",
-      "minLength": 1,
-      "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable kebab-case identifier used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping. Slugs must be unique within the Epic's stories[] array. Slugs are not GH issue numbers — they survive Epic re-incarnations and ticket renumbering. Pattern: lowercase alphanumeric + hyphens, must start with [a-z0-9]."
-    },
-    "label": {
-      "type": "string",
-      "minLength": 1,
-      "description": "A GitHub label name. Structural labels only (e.g. type::epic, type::story, persona::*, area::*). Execution-state labels in the AGENT_LABELS allow-list (agent::*) MUST NOT appear in the spec — they are owned by the wave-runner and the reconciler refuses to write them."
-    },
-    "labels": {
-      "type": "array",
-      "description": "Structural labels attached to this entity. The reconciler enforces an allow-list (STRUCTURAL_LABELS) and rejects any plan that attempts to update AGENT_LABELS via the structural path.",
-      "items": { "$ref": "#/$defs/label" },
-      "uniqueItems": true
-    },
-    "epic": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "title"],
-      "description": "Top-level Epic descriptor. Unlike Stories (which are slug-keyed and may not exist in GH yet), the Epic always has a real GH issue number — the spec lives at .agents/epics/<id>.yaml and that <id> is the same number used here.",
-      "properties": {
-        "id": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "GitHub issue number for the Epic. Authoritative — the spec file's filename derives from this value (.agents/epics/<id>.yaml) and the sibling state file (<id>.state.json) is keyed against it."
-        },
-        "title": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable Epic title. Reconciler updates the GH issue title to match this value on every apply (subject to mayUpdate gating)."
-        },
-        "body": {
-          "type": "string",
-          "description": "Optional Epic body. When present, the reconciler updates the GH issue body to match. When omitted, the GH issue body is left untouched (allowing operator-curated bodies to coexist with structural reconciliation). Multi-line markdown is fully supported. Thematic grouping of Stories — formerly the Feature tier's job — lives here (and in the Tech Spec) as prose."
-        },
-        "labels": {
-          "$ref": "#/$defs/labels",
-          "description": "Structural labels attached to the Epic (e.g. type::epic plus any project-specific structural tags). agent::* labels are forbidden — they are owned by the wave-runner."
-        }
-      }
-    },
-    "story": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["slug", "title", "wave"],
-      "description": "A Story is the unit of agent execution — exactly one Story branch (story-<id>) and exactly one Story sub-agent per Story per wave. Stories are direct children of the Epic (2-tier hierarchy, Story #4041). They declare their wave assignment and inter-Story dependencies via slug references; the wave-runner consumes these to schedule the parallel fan-out. Stories carry inline acceptance[] + verify[] arrays that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface; there is no child-Task decomposition.",
-      "properties": {
-        "slug": {
-          "$ref": "#/$defs/slug",
-          "description": "Stable kebab-case identifier for this Story. Must be unique within the Epic's stories[] array, and is the value referenced by sibling Stories' dependsOn arrays."
-        },
-        "title": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable Story title. Becomes the GH issue title."
-        },
-        "body": {
-          "type": "string",
-          "description": "Optional Story body. Written by the reconciler when present; left untouched when omitted. Used to carry Story-level acceptance criteria / context that the decomposer authored."
-        },
-        "wave": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Zero-indexed wave number. The wave-runner groups Stories with the same wave value into a single parallel batch and waits for every Story in wave N to close before dispatching wave N+1. Wave 0 typically contains Stories with no inbound dependsOn edges."
-        },
-        "dependsOn": {
-          "type": "array",
-          "description": "Slugs of Stories (within this Epic) that must close before this Story may dispatch. Slugs reference stories[].slug values — not GH issue numbers — so the spec survives GH re-incarnations. The reconciler resolves slugs to issue numbers via the sibling state file when writing GH-side `blocked by` references.",
-          "items": {
-            "$ref": "#/$defs/slug",
-            "description": "Slug of a sibling Story that must close before this Story may dispatch."
-          },
-          "uniqueItems": true
-        },
-        "labels": {
-          "$ref": "#/$defs/labels",
-          "description": "Structural labels attached to this Story (e.g. type::story, persona::*). agent::* labels are forbidden — they are owned by the wave-runner at dispatch time."
-        },
-        "acceptance": {
-          "type": "array",
-          "description": "Inline acceptance criteria for this Story. Each entry is a single user-visible acceptance statement that the Story-level agent must satisfy. Acts as the Story-level outcome contract that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface.",
-          "items": {
-            "type": "string",
-            "minLength": 1,
-            "description": "A single acceptance criterion expressed as a user-visible outcome (e.g. 'A Story object containing inline acceptance[] validates against the schema')."
-          }
-        },
-        "verify": {
-          "type": "array",
-          "description": "Inline verification commands for this Story. Each entry is a shell-runnable command (typically a contract test invocation) that proves the corresponding acceptance[] entries hold.",
-          "items": {
-            "type": "string",
-            "minLength": 1,
-            "description": "A single verification command (e.g. 'node --test tests/scripts/epic-spec-schema.test.js')."
-          }
-        }
-      }
-    },
-    "gates": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Optional references to baseline + gate-config slugs. Carried in the spec so structural changes can be reviewed alongside the quality-gate config that will run against them. Resolved to baseline-service inputs by the existing baseline subsystem; opaque to the reconciler itself.",
-      "properties": {
-        "baseline": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Slug naming the baseline ratchet snapshot this Epic targets (e.g. ratchet-baseline-2026-05-12). The baseline subsystem resolves this to concrete lint/mi/crap baseline files at close-validation time."
-        },
-        "config": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Slug naming the gate-config version this Epic uses (e.g. gate-config-v6). Allows different Epics to opt into different gate configurations during long-lived migrations."
-        }
-      }
-    }
-  }
-}