decision-gate

The decision gate

A browser page cannot hand data to a terminal agent. So the gate ships its own server: Claude launches gate-server.mjs in the background, the user chooses in a real browser, and the server writes the contract and exits. That exit is how Claude learns the gate passed.

options.json ──► gate-server ──► themed page in browser
                      ▲                    │
                      └──── POST /submit ◄─┘  (only on Submit)
                              │
                writes decisions.md + decisions.json
                sets phase = execute, exits 0

options.json

{
  "project": { "name": "…", "tagline": "…" },

  // Brownfield only — what the existing codebase already fixes.
  // Rendered as a panel above the tabs and copied into the contract.
  "context": {
    "mode": "brownfield",
    "summary": "two sentences a newcomer could act on",
    "stack": [
      { "name": "Django 5.0", "detail": "DRF for the API", "evidence": "pyproject.toml" }
    ],
    "constraints": ["Python 3.11 — pinned by the deployment image"],
    "doNotBreak": ["The nightly invoicing job — it is the revenue path"]
  },
  "theme": {
    "palette": { "bg","surface","surface2","line","ink","muted",
                 "accent","accent2","apply","infer","innovate" },
    "fontDisplay": "\"Fraunces\", Georgia, serif",
    "fontBody":    "\"Inter\", system-ui, sans-serif",
    "fontImport":  "https://fonts.googleapis.com/css2?…",
    "heroTexture": "radial-gradient(…)",
    "heroSvg":     "<svg …>…</svg>",      // inline, authored locally
    "heroImage":   "assets/hero.webp"      // relative to .aidd/02-research/
  },
  "segments": [
    {
      "id": "kebab-slug",
      "title": "Runtime & Language",
      "summary": "what this decision governs and what it locks in downstream",
      "question": "the question to hold in mind while choosing",   // optional

      // Already settled by the existing codebase. Renders read-only: no stance
      // buttons, no defer, excluded from the submit requirement, reaches the
      // contract as LOCKED. Requires lockedReason. Show exactly one option —
      // the thing that is actually in place.
      "locked": true,
      "lockedReason": "Celery already runs nightly invoicing (app/tasks/invoicing.py)",

      "options": [
        {
          "id": "kebab-slug",
          "name": "SvelteKit on Node",
          "kind": "Full-stack JS",                 // optional
          "maturity": "stable",                    // optional
          "recommended": true,                     // max one per segment
          "blurb": "one sentence",
          "pros": ["…"],                           // required, non-empty
          "cons": ["…"],                           // required, non-empty
          "sources": [{ "title": "…", "url": "https://…", "note": "…" }]
        }
      ]
    }
  ]
}