{
  "id": "2026-04-28-ac-project-governance-332734709c",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-28-ac-project-governance.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.686Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "A+C Project Governance — Pre-Planned + Supervised Execution",
  "summary": "A+C Project Governance — Pre Planned + Supervised Execution Date: 2026 04 28 Status: Design approved — pending implementation plan Problem The platform's claim mechanism is proven. Atomic HCS claims, dep graph dispatch, and per task verification all work. The failure point is between a locked Plan and a completed Build: no one governs execution. Mindy receiv...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "A+C Project Governance — Pre-Planned + Supervised Execution",
      "level": 1,
      "body": "**Date:** 2026-04-28  \n**Status:** Design approved — pending implementation plan\n\n---"
    },
    {
      "title": "Problem",
      "level": 2,
      "body": "The platform's claim mechanism is proven. Atomic HCS claims, dep-graph dispatch, and per-task verification all work. The failure point is between a locked Plan and a completed Build: no one governs execution. Mindy receives a brief and interprets it — sometimes producing 3 tasks instead of 9, sometimes building in the wrong repository. Manual intervention becomes routine. The infrastructure is correct; the orchestration layer above it is not.\n\n---"
    },
    {
      "title": "Design Principles",
      "level": 2,
      "body": "1. **Front-load intelligence.** By the time Build starts, every task is fully specified. No agent makes structural decisions during execution.\n2. **Lock the plan.** PLAN.json is approved by Justin before Build starts. It is immutable once Build begins. Engine dispatches from it. Mindy enforces it.\n3. **Supervisors govern, workers execute.** Workers (Quinn, Vikram, Priya, Zara) never touch project structure. Mindy never creates tasks during Build — she validates them.\n4. **Targeted correction, not retry.** When output fails, the supervisor diagnoses the specific gap and writes a surgical correction brief. Same input never produces different output.\n5. **Checkpoints are reports, not gates.** Phase boundaries produce a health report to Justin. Not a blocker — a signal. Justin can intervene if something looks wrong. By default, execution continues.\n\n---"
    },
    {
      "title": "Track A — Recipes (small projects)",
      "level": 3,
      "body": "Select a recipe → pre-built PLAN.json loaded → Engine dispatches → Mindy supervises.\n\nA recipe is a pre-built PLAN.json template for a known project type (new agent, DB migration, content campaign, etc.). The Build stage runs identically to Track B — same Engine dispatch, same Mindy supervision. Recipes eliminate the Design + Planning stages for well-understood work.\n\n**Recipe library is a follow-on.** Build Track B governance first. Recipes emerge naturally as PLAN.json templates from completed real projects."
    },
    {
      "title": "Track B — Staged Projects (big projects)",
      "level": 3,
      "body": "Full lifecycle with governed execution:\n\n```\nIntake → Design → Plan → Build → QA\n```\n\nEach stage is a stage on the workflow instance. Exec gates exist between Design→Plan and Plan→Build. QA closes with an exec gate.\n\n---"
    },
    {
      "title": "Workflow Instance as Container",
      "level": 2,
      "body": "The workflow instance (Project → Stage → Phase → Task) is already the right container. No new infrastructure needed.\n\n```\nProject (workflow_instance, HCS topic 0.0.XXXXX)\n  Stage: Intake\n  Stage: Design\n  Stage: Plan\n  Stage: Build         ← governed by A+C\n  Stage: QA\n```\n\nThe Atlas+Justin planning session is a task on `roles.architect`. The output of that task — and the output of the Plan stage broadly — is PLAN.json. Justin approves the Plan exec gate. PLAN.json is locked. Build starts.\n\n---"
    },
    {
      "title": "Intake",
      "level": 3,
      "body": "**Owner:** Justin + Atlas  \n**Mechanism:** Task dispatched to `roles.architect`. Atlas runs an interactive session — conversational intake, can include wireframes, analysis, structured brief output.  \n**Output:** Locked project brief on HCS (title, problem statement, success criteria, constraints, anti-requirements, scope).  \n**Gate:** Justin approves before Design starts."
    },
    {
      "title": "Design",
      "level": 3,
      "body": "**Agents:** Priya (PRD), Vikram (Architecture), Zara (UX Spec) — parallel  \n**Output:** Three documents. Each agent reads the project brief. Priya owns the coherence check at the end.  \n**Gate:** Justin reviews all three outputs. Approves before Planning starts."
    },
    {
      "title": "Plan",
      "level": 3,
      "body": "**Owner:** Priya (generates), Atlas + Justin (review and correct)  \n**Mechanism:**\n1. Priya reads all three Design outputs and produces a PLAN.json draft.\n2. Atlas reviews the PLAN.json with Justin in an interactive session — correcting task scope, dep-graph structure, output contracts, brief quality.\n3. The reviewed PLAN.json is the exec gate artifact.\n\n**Gate:** Justin approves PLAN.json. Once approved, it is immutable. Engine and Mindy both treat it as ground truth."
    },
    {
      "title": "Build",
      "level": 3,
      "body": "See *Build Stage Governance* section below.\n\n**Gate:** Mindy posts a Build completion report when all phases pass. Justin approves before QA starts."
    },
    {
      "title": "QA",
      "level": 3,
      "body": "**Agent:** Luna  \n**Mechanism:** Luna validates the Build outputs against the spec (PRD + UX Spec + Architecture). Automated checks where possible.  \n**Gate:** Justin reviews QA report. Final approval.\n\n---"
    },
    {
      "title": "PLAN.json Schema",
      "level": 2,
      "body": "PLAN.json is the complete, executable description of a Build stage. It is produced during Planning and immutable once the Plan exec gate is approved.\n\n```json\n{\n  \"version\": \"1\",\n  \"project_id\": \"0.0.XXXXX\",\n  \"stage_id\": \"0.0.XXXXX\",\n  \"client_id\": \"dreamborn\",\n  \"repo_url\": \"https://github.com/org/repo.git\",\n  \"worktree_path\": \"/opt/redk3y/apps/project-name\",\n  \"phases\": [\n    {\n      \"id\": \"phase-1\",\n      \"name\": \"Foundation\",\n      \"tasks\": [\n        {\n          \"local_id\": \"1.1\",\n          \"title\": \"Short descriptive title\",\n          \"role\": \"developer\",\n          \"brief\": \"Full task brief text...\",\n          \"output_path\": \"relative/path/to/output/file\",\n          \"completion\": {\n            \"type\": \"file\",\n            \"min_length\": 500,\n            \"evaluate\": \"Human-readable description of what correct output looks like\"\n          },\n          \"depends_on\": []\n        },\n        {\n          \"local_id\": \"1.2\",\n          \"title\": \"...\",\n          \"role\": \"developer\",\n          \"brief\": \"...\",\n          \"output_path\": \"...\",\n          \"completion\": { \"type\": \"file\", \"min_length\": 1000, \"evaluate\": \"...\" },\n          \"depends_on\": [\"1.1\"]\n        }\n      ]\n    },\n    {\n      \"id\": \"phase-2\",\n      \"name\": \"Core Pages\",\n      \"tasks\": [\n        {\n          \"local_id\": \"2.1\",\n          \"title\": \"...\",\n          \"role\": \"developer\",\n          \"brief\": \"...\",\n          \"output_path\": \"...\",\n          \"completion\": { \"type\": \"file\", \"min_length\": 200, \"evaluate\": \"...\" },\n          \"depends_on\": [\"1.1\", \"1.2\"]\n        }\n      ]\n    }\n  ]\n}\n```\n\n**`depends_on` uses `local_id` references.** Engine translates these to HCS topic IDs when ingesting. `local_id` values are stable identifiers within a PLAN.json — e.g., `\"1.1\"`, `\"2.3\"`.\n\n**`completion` contract** is required on every task. It is what the Build Supervisor validates against after each task.complete.\n\n---"
    },
    {
      "title": "Build Stage Governance",
      "level": 2,
      "body": "Two actors run in parallel during Build:"
    },
    {
      "title": "Engine — Dispatcher (unchanged)",
      "level": 3,
      "body": "Engine reads PLAN.json from Priya's Planning output. Ingests all tasks as `agent_tasks` rows (status=`created`). As deps complete, posts `task.available` to the appropriate role topic. Pure state machine. Never interprets or modifies PLAN.json."
    },
    {
      "title": "Mindy — Build Supervisor (new role)",
      "level": 3,
      "body": "Mindy's job changes entirely. She is no longer a dispatcher. She is a governor.\n\n**How she's invoked:** When the Plan exec gate is approved, a supervisor task is posted to `roles.supervisor` with PLAN.json as the brief. Mindy claims it on her next tick.\n\n**What she does every tick:**\n1. Reads PLAN.json (from task brief).\n2. Queries `agent_tasks` for all tasks in this Build stage.\n3. For each newly-completed task (status=`complete`, not yet validated by her): runs validation.\n4. Checks phase completion: if all tasks in a phase are validated, posts a phase health report to Justin's inbox.\n5. Checks for failures that need correction tasks.\n6. Exits and returns on next tick (120s).\n\n**Validation per task:**\n- Mechanical: `output_ref` is set, file exists in Supabase storage, `output_path` matches what PLAN.json specifies.\n- Contract: output satisfies `completion.evaluate` (Haiku semantic check if `completion.evaluate` is non-null).\n- PASS: write `supervisor_validated_at` timestamp to `agent_tasks` row, advance.\n- FAIL: enter correction loop.\n\n**Mindy does not create the main tasks.** Engine creates them. Mindy only creates correction tasks.\n\n---"
    },
    {
      "title": "Correction Loop (Model C)",
      "level": 2,
      "body": "When Mindy's validation fails on a task:\n\n**C1 — Diagnose.** Mindy reads the task brief, the actual output, and the completion contract. She identifies the specific gap: what was expected, what was produced, what specifically is wrong.\n\n**C2 — Correction task.** Mindy posts `task.blocked` on the original task's HCS topic (listener updates Supabase status). Then creates a new correction task with a targeted brief:\n- Full context of what was attempted\n- Exact description of what failed\n- Precise instruction to fix only that gap (not redo the whole task)\n\nMindy dispatches the correction task **directly** (posts `task.available` to the role topic herself, not through Engine's dep-graph check). The correction task records the original task ID in its brief for traceability, but its dispatch is immediate and unconditional.\n\n**C3 — Re-validate.** When the correction task completes, Mindy validates it against the same contract. If PASS: mark phase task as corrected+validated, advance.\n\n**C4 — Escalate.** If the correction task also fails: Mindy posts to Justin's exec inbox with:\n- Original task title and brief\n- Original output (what Quinn produced)\n- Correction task brief (what Mindy asked for)\n- Correction output (what Quinn produced on retry)\n- Diagnosis: what Mindy thinks is wrong\n- Recommended action (retry with different approach, modify brief, skip task, etc.)\n\nJustin decides. The Build stage pauses on the affected branch of the dep-graph until Justin responds.\n\n---"
    },
    {
      "title": "Phase Checkpoints",
      "level": 2,
      "body": "When all tasks in a phase reach validated status, Mindy posts a phase health report to Justin's inbox. This is a status report, not a gate.\n\n**Report contains:**\n- Phase name and number\n- Tasks completed: N/N\n- Corrections applied: N (with summaries)\n- Cost incurred this phase (sum of `agent_tasks.cost_usd`)\n- Duration\n- Any open escalations\n\nJustin can respond to intervene. If no response, the next phase continues automatically — Engine dispatches the next phase's tasks as their deps are satisfied.\n\n---"
    },
    {
      "title": "What Changes",
      "level": 2,
      "body": "| # | Change | Type | Notes |\n|---|--------|------|-------|\n| 1 | PLAN.json schema | New doc | Defined above — the planning contract |\n| 2 | Priya persona update | Persona edit | Planning output = PLAN.json with this schema |\n| 3 | Mindy persona — full rewrite | Major persona rewrite | Dispatcher → Build Supervisor |\n| 4 | New role: `roles.supervisor` | 1 HCS topic + agent_definitions | Mindy subscribes to this role |\n| 5 | Migration: `supervisor_validated_at` column | Small migration | Add `timestamptz` column to `agent_tasks` — Mindy writes this after validating each task |\n| 6 | Engine PLAN.json ingestion | Verify + minor field alignment | Engine already bulk-ingests project_plan blocks — align local_id dep resolution |\n| 7 | Supervisor task dispatch | Small script addition | Post supervisor task to roles.supervisor at Build start (Plan exec gate approval) |\n\n---"
    }
  ],
  "html_path": "artifacts/2026-04-28-ac-project-governance-332734709c.html",
  "json_path": "artifacts/2026-04-28-ac-project-governance-332734709c.json"
}