@eir-labs/coltrane 0.5.1 → 0.7.2

package/domain_types/branch-state.json

@@ -0,0 +1,21 @@
+{
+  "slug": "branch-state",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "preview-deploy",
+  "status": "active",
+  "description": "The sensed state of the branch to deploy: its name and its HEAD commit, read independently of the change-set the run reviewed. The between-movement edge carries a change-set (diffs, tests, rationale) which holds no commit_sha and no branch — software-change-v1's write-change chair emits diffs as content, never an applied commit — so the deploy input is sensed here rather than threaded through the diff. This decouples the deploy from the diff content and keeps the edge honest.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "branch":     { "type": "string", "description": "The git branch to deploy to the preview target." },
+      "commit_sha": { "type": "string", "description": "The branch HEAD commit, sensed directly — the exact commit the preview will build." },
+      "project_id": { "type": "string", "description": "The Vercel project id the branch belongs to, when known at sense time." }
+    }
+  },
+  "required_fields": [
+    "source",
+    "branch",
+    "commit_sha"
+  ]
+}

package/domain_types/change-context.json

@@ -0,0 +1,39 @@
+{
+  "slug": "change-context",
+  "version": 1,
+  "extends": "Interpretation",
+  "domain": "software-change",
+  "status": "active",
+  "description": "The exhaustive read of the material a change lands in, produced before any decision is taken. Records what is present AND what is absent: unknowns is required because an incomplete reading that omits its gaps is indistinguishable from a complete one, and every downstream seat would treat it as complete.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "repository":          { "type": "string", "description": "Repository or working-tree the reading covers." },
+      "boundary":            { "type": "array", "items": { "type": "string" }, "description": "The declared extent of the read: paths and artefacts inside it, and those deliberately outside it." },
+      "entry_points":        { "type": "array", "items": { "type": "string" }, "description": "Where control or data enters the region under change." },
+      "relevant_files":      {
+        "type": "array",
+        "description": "Each file the change plausibly touches, with the reason it is relevant and the locator the reading came from.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "path":    { "type": "string" },
+            "why":     { "type": "string" },
+            "locator": { "type": "string", "description": "Tool plus path or query that produced this finding." }
+          },
+          "required": ["path", "why"]
+        }
+      },
+      "existing_tests":      { "type": "array", "items": { "type": "string" }, "description": "Checks that already cover the region — the baseline a later verdict is measured against." },
+      "conventions_observed": { "type": "array", "items": { "type": "string" }, "description": "Prevailing patterns the change is expected to hold to." },
+      "unknowns":            { "type": "array", "items": { "type": "string" }, "description": "Questions the material does not answer and paths that could not be reached. Required: the honest bound of the read." }
+    }
+  },
+  "required_fields": [
+    "claims",
+    "input_refs",
+    "relevant_files",
+    "existing_tests",
+    "unknowns"
+  ]
+}

package/domain_types/change-decision.json

@@ -0,0 +1,36 @@
+{
+  "slug": "change-decision",
+  "version": 1,
+  "extends": "Judgment",
+  "domain": "software-change",
+  "status": "active",
+  "description": "The direction, fixed once. Names the three commitments a change is held to — scope, non-goals, stop condition — and records the alternatives that were rejected, because subtraction that leaves no record is indistinguishable from oversight. Downstream seats may append observations; they may not revise these fields.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "scope":                 { "type": "string", "description": "The observable outcome this change commits to." },
+      "non_goals":             { "type": "array", "items": { "type": "string" }, "description": "What this change is NOT, and the neighbouring shapes it must not collapse into." },
+      "stop_condition":        { "type": "string", "description": "The observation at which the work is finished, stated so that someone else could call it." },
+      "rejected_alternatives": {
+        "type": "array",
+        "description": "Directions considered and set aside, each with its reason.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "alternative": { "type": "string" },
+            "reason":      { "type": "string" }
+          },
+          "required": ["alternative", "reason"]
+        }
+      },
+      "risks":                 { "type": "array", "items": { "type": "string" }, "description": "Consequences the direction accepts knowingly." }
+    }
+  },
+  "required_fields": [
+    "criteria",
+    "input_refs",
+    "scope",
+    "non_goals",
+    "stop_condition"
+  ]
+}

package/domain_types/change-plan.json

@@ -0,0 +1,47 @@
+{
+  "slug": "change-plan",
+  "version": 1,
+  "extends": "Plan",
+  "domain": "software-change",
+  "status": "active",
+  "description": "The ordered structure a change will be built through, settled before anything is written. test_first is required and separate from steps: a plan that lists the check after the change it checks cannot distinguish a passing check from one written to pass, which is the failure this repository's change discipline exists to close.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "test_first":     {
+        "type": "array",
+        "description": "The checks that land before the change, each with the failure it is expected to show first.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "check":           { "type": "string" },
+            "expected_before": { "type": "string", "description": "What this check reports while the change is absent." }
+          },
+          "required": ["check", "expected_before"]
+        }
+      },
+      "files_touched":  { "type": "array", "items": { "type": "string" }, "description": "Paths the plan commits to changing. A path outside this list is a departure to be recorded, not a silent extension." },
+      "tradeoffs":      {
+        "type": "array",
+        "description": "Steps where more than one structure would have served, and why this one was taken.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "at":     { "type": "string" },
+            "chosen": { "type": "string" },
+            "over":   { "type": "string" },
+            "why":    { "type": "string" }
+          },
+          "required": ["at", "chosen", "why"]
+        }
+      },
+      "rollback":       { "type": "string", "description": "How the change is undone if the verdict fails." }
+    }
+  },
+  "required_fields": [
+    "steps",
+    "objective",
+    "test_first",
+    "files_touched"
+  ]
+}

package/domain_types/change-request.json

@@ -0,0 +1,24 @@
+{
+  "slug": "change-request",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "software-change",
+  "status": "active",
+  "description": "The seed of a software-change run: the change as it arrives, before anyone has read the codebase it lands in. A request that names no observable acceptance cannot be verified at the end of the run, so acceptance_criteria is required at the boundary rather than discovered at the verdict.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "request_text":        { "type": "string", "description": "The change as stated by the requester, unparaphrased." },
+      "repository":          { "type": "string", "description": "Repository or working-tree identifier the change lands in." },
+      "target_paths":        { "type": "array", "items": { "type": "string" }, "description": "Paths the requester believes are in scope. A belief, not a finding — the reading phase may contradict it." },
+      "acceptance_criteria": { "type": "array", "items": { "type": "string" }, "description": "Observations that would show the change was made. Each entry must be checkable by someone who did not write the change." },
+      "out_of_scope":        { "type": "array", "items": { "type": "string" }, "description": "Work the requester explicitly excludes." },
+      "requested_by":        { "type": "string", "description": "The requesting party." }
+    }
+  },
+  "required_fields": [
+    "source",
+    "request_text",
+    "acceptance_criteria"
+  ]
+}

package/domain_types/change-set.json

@@ -0,0 +1,46 @@
+{
+  "slug": "change-set",
+  "version": 1,
+  "extends": "Artifact",
+  "domain": "software-change",
+  "status": "active",
+  "description": "The change itself, carried as content rather than applied — the seat that produces it holds a read-only grant, so the artefact is reviewable before anything mutates. departures is separate from rationale on purpose: a change that diverged from its plan and amended the record is honest, and a change that diverged silently is not distinguishable from one that did not.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "diffs":       {
+        "type": "array",
+        "description": "Per-path patch content, in unified-diff form.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "path":  { "type": "string" },
+            "patch": { "type": "string" }
+          },
+          "required": ["path", "patch"]
+        }
+      },
+      "tests_added": { "type": "array", "items": { "type": "string" }, "description": "Checks introduced by this change, named so a verifier can run exactly them." },
+      "rationale":   { "type": "array", "items": { "type": "string" }, "description": "The non-obvious choices this change makes, each with the reason it was made." },
+      "departures":  {
+        "type": "array",
+        "description": "Where the artefact left the plan, and why.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "from_step": { "type": "string" },
+            "instead":   { "type": "string" },
+            "why":       { "type": "string" }
+          },
+          "required": ["from_step", "instead", "why"]
+        }
+      }
+    }
+  },
+  "required_fields": [
+    "validation_criteria",
+    "input_refs",
+    "diffs",
+    "rationale"
+  ]
+}

package/domain_types/change-verdict.json

@@ -0,0 +1,26 @@
+{
+  "slug": "change-verdict",
+  "version": 1,
+  "extends": "Verdict",
+  "domain": "software-change",
+  "status": "active",
+  "description": "Whether the change built is the change that was decided, measured against the commitments as fixed and not against a revised memory of them. inferred_not_run is required: a verdict that does not separate what was executed from what was reasoned about reads as evidence while resting on inference, which is the one thing a verdict must never do.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "decision_ref":    { "type": "string", "description": "The change-decision this verdict measures against." },
+      "criteria_unmet":  { "type": "array", "items": { "type": "string" }, "description": "Acceptance criteria the change does not meet, stated plainly." },
+      "inferred_not_run": { "type": "array", "items": { "type": "string" }, "description": "Checks that could NOT be executed under the granted tools and were reasoned about instead. Required — an empty list is a claim that everything ran." },
+      "failures_verbatim": { "type": "array", "items": { "type": "string" }, "description": "Failure output as the tool reported it: messages, counts, names. Not summaries of them." },
+      "scope_drift":     { "type": "array", "items": { "type": "string" }, "description": "Where the change exceeded or fell short of the fixed scope." },
+      "recommendation":  { "type": "string", "enum": ["accept", "amend", "reject", "insufficient-evidence"], "description": "insufficient-evidence is the honest answer when the granted tools could not check what the verdict turns on." }
+    }
+  },
+  "required_fields": [
+    "checks",
+    "target_ref",
+    "pass",
+    "inferred_not_run",
+    "recommendation"
+  ]
+}

package/domain_types/deploy-verdict.json

@@ -0,0 +1,23 @@
+{
+  "slug": "deploy-verdict",
+  "version": 1,
+  "extends": "Verdict",
+  "domain": "preview-deploy",
+  "status": "active",
+  "description": "Whether the preview build reached a terminal state, and which one. pass is true only when terminal_state is READY. terminal_state carries the honest never-settled path: when the deploy chair's bounded poll loop exhausts its budget with no READY | ERROR | CANCELED observed, it seals terminal_state UNSETTLED with deadline_exceeded true and pass false — a give-up made visible in the ledger rather than a silent hang. logs_tail is present only on a non-READY terminal, so a failure carries the tail of the build log a human can read.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "terminal_state":   { "type": "string", "enum": ["READY", "ERROR", "CANCELED", "UNSETTLED"], "description": "The build's terminal readyState, or UNSETTLED when the poll budget was spent before any terminal state was observed." },
+      "logs_tail":        { "type": "array", "items": { "type": "string" }, "description": "The tail of the build log, present only when terminal_state is not READY." },
+      "deadline_exceeded": { "type": "boolean", "description": "True when the bounded poll loop reached its max_tool_calls ceiling without a terminal readyState. Pairs with terminal_state UNSETTLED and pass false." }
+    }
+  },
+  "required_fields": [
+    "checks",
+    "target_ref",
+    "pass",
+    "terminal_state",
+    "deadline_exceeded"
+  ]
+}

package/domain_types/design-brief.json

@@ -0,0 +1,37 @@
+{
+  "slug": "design-brief",
+  "version": 1,
+  "extends": "Interpretation",
+  "domain": "product-design",
+  "status": "active",
+  "description": "The product of the first divergence: what was found when the question was held open, before anything was chosen. divergence_breadth and unknowns are both required — a brief that reports only its findings makes a narrow exploration and an exhaustive one look identical, and the definition phase would converge on the narrow one without knowing it.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "observations":        {
+        "type": "array",
+        "description": "What was found, each with the locator it was found through.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "observation": { "type": "string" },
+            "locator":     { "type": "string", "description": "Tool plus path or query that produced this observation." }
+          },
+          "required": ["observation"]
+        }
+      },
+      "audience_segments":   { "type": "array", "items": { "type": "string" }, "description": "Distinguishable groups the question lands differently for." },
+      "unmet_needs":         { "type": "array", "items": { "type": "string" }, "description": "Needs the current state does not serve. Findings, not proposals." },
+      "adjacent_questions":  { "type": "array", "items": { "type": "string" }, "description": "Questions the exploration surfaced that the posed question did not contain." },
+      "divergence_breadth":  { "type": "string", "enum": ["narrow", "moderate", "wide"], "description": "How far the exploration actually reached, judged against the material available rather than against effort spent." },
+      "unknowns":            { "type": "array", "items": { "type": "string" }, "description": "What the exploration could not determine. Required: the honest bound of the divergence." }
+    }
+  },
+  "required_fields": [
+    "claims",
+    "input_refs",
+    "observations",
+    "unmet_needs",
+    "unknowns"
+  ]
+}

package/domain_types/design-concept.json

@@ -0,0 +1,36 @@
+{
+  "slug": "design-concept",
+  "version": 1,
+  "extends": "Artifact",
+  "domain": "product-design",
+  "status": "active",
+  "description": "The product of the second divergence, built rather than described: a concept stated in enough mechanism that someone else could evaluate it. tradeoffs and open_questions are required — a concept presented without either reads as settled, and the delivery seat would verify it against criteria it has no way to know were contested.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "concept_name":    { "type": "string", "description": "Short handle for the concept." },
+      "description":     { "type": "string", "description": "What it is, in the audience's register." },
+      "mechanism":       { "type": "array", "items": { "type": "string" }, "description": "How it works, step by step. The part that distinguishes a concept from a wish." },
+      "addresses":       { "type": "array", "items": { "type": "string" }, "description": "Which success criteria from the definition this concept answers, named individually." },
+      "tradeoffs":       {
+        "type": "array",
+        "description": "What this concept gives up, and what it buys with it.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "gives_up": { "type": "string" },
+            "buys":     { "type": "string" }
+          },
+          "required": ["gives_up", "buys"]
+        }
+      },
+      "open_questions":  { "type": "array", "items": { "type": "string" }, "description": "What remains unresolved in the concept as built." }
+    }
+  },
+  "required_fields": [
+    "validation_criteria",
+    "input_refs",
+    "mechanism",
+    "tradeoffs"
+  ]
+}

package/domain_types/design-definition.json

@@ -0,0 +1,37 @@
+{
+  "slug": "design-definition",
+  "version": 1,
+  "extends": "Plan",
+  "domain": "product-design",
+  "status": "active",
+  "description": "The seam between the two diamonds: the one problem the second diamond is opened on, and the ones it is not. discarded is required because a definition that names only what it kept cannot be audited — the reader cannot tell whether an option was considered and rejected or never seen at all.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "problem_statement": { "type": "string", "description": "The single problem the run commits to solving, stated so that a solution to a different problem would be visibly off-target." },
+      "in_scope":          { "type": "array", "items": { "type": "string" }, "description": "What the second diamond may explore." },
+      "out_of_scope":      { "type": "array", "items": { "type": "string" }, "description": "What it may not, and the neighbouring problems this one must not collapse into." },
+      "success_criteria":  { "type": "array", "items": { "type": "string" }, "description": "Observations that would confirm the problem was solved. Each checkable by someone who did not do the work." },
+      "discarded":         {
+        "type": "array",
+        "description": "Problems the brief surfaced and this definition set aside, each with its reason.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "problem": { "type": "string" },
+            "reason":  { "type": "string" }
+          },
+          "required": ["problem", "reason"]
+        }
+      },
+      "audience":          { "type": "string", "description": "Who the delivered answer is for, carried forward from the seed." }
+    }
+  },
+  "required_fields": [
+    "steps",
+    "objective",
+    "problem_statement",
+    "out_of_scope",
+    "success_criteria"
+  ]
+}

package/domain_types/design-question.json

@@ -0,0 +1,23 @@
+{
+  "slug": "design-question",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "product-design",
+  "status": "active",
+  "description": "The seed of a product-design run: the question the first diamond is opened on, and for whom. audience is required at the boundary because a divergent exploration with no stated audience converges on whoever the reader imagines, and the definition phase then has nothing external to converge against.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "question":       { "type": "string", "description": "The question as posed, unparaphrased." },
+      "audience":       { "type": "string", "description": "Who the eventual answer is for." },
+      "known_context":  { "type": "array", "items": { "type": "string" }, "description": "What the requester already holds as established." },
+      "constraints":    { "type": "array", "items": { "type": "string" }, "description": "Bounds the answer must respect regardless of what the exploration finds." },
+      "success_signal": { "type": "string", "description": "What the requester would observe if the run answered well." }
+    }
+  },
+  "required_fields": [
+    "source",
+    "question",
+    "audience"
+  ]
+}

package/domain_types/design-verdict.json

@@ -0,0 +1,27 @@
+{
+  "slug": "design-verdict",
+  "version": 1,
+  "extends": "Verdict",
+  "domain": "product-design",
+  "status": "active",
+  "description": "The second convergence: whether the concept built answers the problem that was defined. Measured against the definition as sealed, criterion by criterion. inferred_not_run is required for the same reason as in software change — most design criteria cannot be executed, so a verdict that does not say which ones were only reasoned about overstates its own evidence.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "definition_ref":   { "type": "string", "description": "The design-definition this verdict measures against." },
+      "criteria_met":     { "type": "array", "items": { "type": "string" }, "description": "Success criteria the concept satisfies, each with the observation that shows it." },
+      "criteria_unmet":   { "type": "array", "items": { "type": "string" }, "description": "Success criteria the concept does not satisfy, stated plainly and unsoftened." },
+      "inferred_not_run": { "type": "array", "items": { "type": "string" }, "description": "Criteria judged by reasoning because no check could be executed. Required — an empty list is a claim that everything was observed." },
+      "scope_drift":      { "type": "array", "items": { "type": "string" }, "description": "Where the concept answers a different problem than the one defined." },
+      "recommendation":   { "type": "string", "enum": ["deliver", "iterate", "redefine", "insufficient-evidence"], "description": "redefine returns the run to the first seam: the concept is sound but the problem was the wrong one." }
+    }
+  },
+  "required_fields": [
+    "checks",
+    "target_ref",
+    "pass",
+    "criteria_unmet",
+    "inferred_not_run",
+    "recommendation"
+  ]
+}

package/domain_types/preview-deployment.json

@@ -0,0 +1,32 @@
+{
+  "slug": "preview-deployment",
+  "version": 1,
+  "extends": "Artifact",
+  "domain": "preview-deploy",
+  "status": "active",
+  "description": "A branch built to a Vercel preview and sealed as a typed artifact — the terminal record of movement-2 and the typed edge into a promote movement. commit_sha and branch are sensed independently of the change-set the run reviewed: the write-change chair that produces a change-set holds a read-only grant and emits diffs as content, never an applied commit, so the deploy is decoupled from the diff and reads the branch HEAD itself. protection is required because it decides whether the preview URL is reachable from a phone at the approval gate: supabase-auth is reachable by any credentialed app user, vercel-sso requires an active Vercel team SSO session, public needs no login. inspector_url is optional — present only when the deployment response carried it.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "preview_url":   { "type": "string", "description": "The reachable preview URL from POST /v13/deployments (the deployment's url, https-prefixed)." },
+      "commit_sha":    { "type": "string", "description": "The exact commit deployed, sensed from branch HEAD — not read out of the change-set." },
+      "branch":        { "type": "string", "description": "The git branch deployed to the preview target." },
+      "project_id":    { "type": "string", "description": "The Vercel project id (prj_...) the deployment belongs to." },
+      "deployment_id": { "type": "string", "description": "The Vercel deployment id (dpl_...), read later by a promote chair to call the promote API." },
+      "build_status":  { "type": "string", "description": "The last observed Vercel readyState: QUEUED | INITIALIZING | BUILDING | READY | ERROR | CANCELED." },
+      "protection":    { "type": "string", "enum": ["vercel-sso", "supabase-auth", "public"], "description": "How the preview URL is gated. supabase-auth is the phone-reachable mode required at the approval gate." },
+      "inspector_url": { "type": "string", "description": "The Vercel inspector/dashboard URL for the deployment, when the response carried it." }
+    }
+  },
+  "required_fields": [
+    "validation_criteria",
+    "input_refs",
+    "preview_url",
+    "commit_sha",
+    "branch",
+    "project_id",
+    "deployment_id",
+    "build_status",
+    "protection"
+  ]
+}