@mikenguyen69/harness 0.1.0-beta.1

package/schema/manifest.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/manifest.schema.json",
+  "title": "Contract A — component.toml (gate manifest)",
+  "description": "Binds the abstract gate vocabulary to real commands per component root (ADR 0003: the file is component.toml). Structural rules: every vocabulary gate is either bound or explicitly declined with a reason — absence is an error (all-skip is never a pass); a gate name outside the closed vocabulary is a config error. Severity is data so the maturity ramp needs no tooling fork. Re-rooted per component and extended with `external` gates per system-harness-blueprint.md §3 (\"Contract A — component manifest\").",
+  "type": "object",
+  "required": ["harness", "gates"],
+  "properties": {
+    "harness": {
+      "type": "object",
+      "required": ["policy_version", "profile"],
+      "properties": {
+        "policy_version": {
+          "type": "string",
+          "description": "semver of the policy data this manifest conforms to"
+        },
+        "profile": {
+          "type": "string",
+          "description": "base profile name, e.g. 'typescript'"
+        },
+        "mode": {
+          "enum": ["standard", "ratchet"],
+          "default": "standard",
+          "description": "ratchet = brownfield adoption: bulk gates run changed-lines against a frozen debt baseline that may only fall"
+        }
+      }
+    },
+    "ratchet": {
+      "type": "object",
+      "description": "Required when mode=ratchet. Debt is counted at init (harness init --audit), frozen, and may only fall — repo totals above the floor fail even at changed-lines severity.",
+      "required": ["baseline_path"],
+      "properties": {
+        "baseline_path": {
+          "type": "string",
+          "default": ".harness/baseline.json",
+          "description": "frozen debt inventory, schema/baseline.schema.json"
+        }
+      }
+    },
+    "quarantine": {
+      "type": "array",
+      "description": "Flaky tests parked by name — never silently retried. Suspended for any quarantined test covering code inside the current unit's touched scope: fix the flake or the behavior. Expired entries fail verify until fixed, deleted, or re-quarantined with a fresh reason.",
+      "items": {
+        "type": "object",
+        "required": ["test_id", "expires", "reason"],
+        "properties": {
+          "test_id": {
+            "type": "string",
+            "description": "suite/case identifier as the runner reports it"
+          },
+          "expires": { "type": "string", "format": "date" },
+          "reason": { "type": "string", "minLength": 10 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "substrate": {
+      "type": "object",
+      "description": "The one layer with no maturity ramp — branch protection is on or decorative. enforced_from allows a dated cutover on brownfield repos; until that date, verify reports itself as ADVISORY at the repo level (the harness never lets the guarantee be silently absent).",
+      "properties": {
+        "enforced_from": {
+          "type": "string",
+          "format": "date",
+          "description": "date server-side enforcement becomes active; absent = enforced now"
+        }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "description": "One entry per vocabulary gate: spec, fmt, lint, types, test, arch, contract, size, gen:fresh, or any sec:<tool> under the sec:* namespace (ADR 0004). Each is a binding or a declination — never absent.",
+      "propertyNames": {
+        "pattern": "^(spec|fmt|lint|types|test|arch|contract|size|gen:fresh|sec:[a-z][a-z-]*)$",
+        "description": "closed vocabulary — an unrecognised gate name is a config error, not a silent skip"
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["run", "severity", "cost"],
+            "properties": {
+              "run": { "type": "string", "description": "the real command" },
+              "severity": {
+                "enum": ["advisory", "changed-lines", "blocking"],
+                "description": "maturity-ramp position; moved by calibration data, not by hand"
+              },
+              "cost": {
+                "enum": ["cheap", "expensive"],
+                "description": "runner orders cheap-first, fail-fast"
+              },
+              "timeout_seconds": { "type": "integer", "minimum": 1 },
+              "external": {
+                "type": "boolean",
+                "default": false,
+                "description": "true = runs only in the component's deploy phase (e.g. terraform post-apply reality checks), never in hermetic `verify`. Blueprint §3: keeps verify offline and reproducible."
+              },
+              "snapshot_max_age_days": {
+                "type": "integer",
+                "description": "for gates needing external data (sec:deps): max staleness of the vendored snapshot; network during verify is otherwise forbidden"
+              }
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "required": ["declined"],
+            "properties": {
+              "declined": {
+                "type": "string",
+                "minLength": 10,
+                "description": "explicit reason this gate does not apply here"
+              }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  }
+}

package/schema/routes.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/routes.schema.json",
+  "title": "routes.toml — agent-harness routing policy",
+  "description": "Hub-side policy data (solution design §8). Maps a component profile to a model + config, plus optional mode-tightening that the eval loop lifts on measurement (e.g. `propose-only until route-eval>=90`). Adapters read the resolved route at session start; calibration may PROPOSE route changes, never apply them. An A/B test is two entries for one profile with `split` weights. Describes the parsed TOML: `[[route]]` -> the `route` array.",
+  "type": "object",
+  "required": ["route"],
+  "additionalProperties": false,
+  "properties": {
+    "route": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["profile", "model"],
+        "additionalProperties": false,
+        "properties": {
+          "profile": {
+            "type": "string",
+            "minLength": 1,
+            "description": "component profile this route serves, e.g. 'typescript'"
+          },
+          "model": {
+            "type": "string",
+            "minLength": 1,
+            "description": "model id, e.g. 'claude-fable-5'"
+          },
+          "runner": {
+            "enum": ["claude", "codex", "cursor"],
+            "default": "claude",
+            "description": "which coding agent runs the unit. Routing policy, same as `model`. Absent = claude, so existing routes.toml files stay valid. An A/B `split` may vary runner as well as model."
+          },
+          "config": {
+            "type": "string",
+            "description": "config/preset id; hashed into session.config_hash"
+          },
+          "split": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "A/B weight when more than one route shares a profile; weights across a profile should sum to 1"
+          },
+          "mode": {
+            "enum": ["standard", "propose-only"],
+            "default": "standard"
+          },
+          "until": {
+            "type": "string",
+            "description": "condition that lifts a tightened mode, e.g. 'route-eval>=90'"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/run-status.schema.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/run-status.schema.json",
+  "title": "Run-status document — the live overlay for the board",
+  "description": "A latest-state-wins snapshot of one orchestration run on one machine (dashboard-plan.md). NOT a ledger event: in-flight state (attempt counts, a session mid-run, cost ticking) is high-churn and worthless after the run, so it never enters the hash-chained ledger. system-harness owns this shape; orchestration-harness (and any future actuator) emits documents conforming to it via `harness runstatus publish`, which stamps `machine_id` and writes to the hub spool. The hub keeps latest-per-(machine_id, run_id); `heartbeat_at` older than the staleness threshold renders as stale, never live; a terminal `outcome` (or staleness past expiry) retires the run from the overlay.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "machine_id",
+    "run_id",
+    "system_id",
+    "spec_ref",
+    "started_at",
+    "heartbeat_at",
+    "lanes",
+    "needs_you",
+    "counts"
+  ],
+  "properties": {
+    "machine_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "the machine the run is on. Stamped by `harness runstatus publish`; a publisher that sets it itself is overridden."
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "unique per `orchestrate` invocation. A restart is a new run_id (crash = restart, by design)."
+    },
+    "system_id": { "type": "string", "minLength": 1 },
+    "spec_ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "the materialised spec DAG the run is driving (path or id)."
+    },
+    "started_at": { "type": "string", "format": "date-time" },
+    "heartbeat_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "last time the machine published. The board's staleness rules key off this — older than the threshold renders 'stale (machine silent since …)'."
+    },
+    "outcome": {
+      "enum": ["completed", "halted", "crashed"],
+      "description": "present only on the terminal publish. Retires the run from the live overlay."
+    },
+    "lanes": {
+      "type": "array",
+      "description": "one entry per unit the run has opened a lane for.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["unit_id", "step", "runner", "model", "attempt", "retry_budget", "cost", "emitter"],
+        "properties": {
+          "unit_id": { "type": "string", "minLength": 1 },
+          "step": {
+            "type": "string",
+            "minLength": 1,
+            "description": "the lane's current step (the emitter's vocabulary, e.g. claim | implement | rebase | verify | review | merge | land)."
+          },
+          "runner": {
+            "type": "string",
+            "minLength": 1,
+            "description": "which coding agent is driving the lane (claude | codex | cursor)."
+          },
+          "model": { "type": "string", "minLength": 1 },
+          "attempt": { "type": "integer", "minimum": 1 },
+          "retry_budget": { "type": "integer", "minimum": 0 },
+          "cost": {
+            "type": "number",
+            "minimum": 0,
+            "description": "cumulative estimated USD spent on this lane so far."
+          },
+          "emitter": {
+            "enum": ["session", "orchestrator"],
+            "description": "telemetry tier — `session` = first-hand from the agent's adapter; `orchestrator` = reconstructed by the actuator for an adapter-less runner (badged as such on the board)."
+          },
+          "settled": {
+            "type": "boolean",
+            "description": "the lane reached a terminal step (merged / halted). Optional; absent = still in flight."
+          },
+          "envelope_hash": {
+            "type": "string",
+            "minLength": 1,
+            "description": "the `hash` of the ring-1 `envelope` ledger event for this lane's verify (from `harness verify --json`). Optional; present once ring 1 has passed."
+          },
+          "door_id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "the real door id `harness merge` opened for this lane (parsed from its stderr), when the lane halted on a one-way / propose-only door. Optional."
+          },
+          "activity": {
+            "type": "string",
+            "maxLength": 160,
+            "description": "Live-activity group (latest-state-wins snapshot — NOT a ledger/event channel): one-line summary of the agent's current/last action (a tool name plus a short target — never transcript or model prose). Optional; absent means the runner emits no session-tier stream (degraded tier: Codex / Cursor)."
+          },
+          "activity_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Live-activity group (latest-state-wins snapshot — NOT a ledger/event channel): when this activity snapshot was last stamped. Optional; absent means the runner emits no session-tier stream (degraded tier)."
+          },
+          "turn": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Live-activity group (latest-state-wins snapshot — NOT a ledger/event channel): agent turn counter for the current session. Optional; absent means the runner emits no session-tier stream (degraded tier)."
+          },
+          "tokens": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["in", "out"],
+            "description": "Live-activity group (latest-state-wins snapshot — NOT a ledger/event channel): running token count for the session. Optional; absent means the runner emits no session-tier stream (degraded tier).",
+            "properties": {
+              "in": { "type": "integer", "minimum": 0 },
+              "out": { "type": "integer", "minimum": 0 }
+            }
+          },
+          "recent": {
+            "type": "array",
+            "maxItems": 5,
+            "description": "Live-activity group (latest-state-wins snapshot — NOT a ledger/event channel): small ring buffer of recent action lines — each a one-line summary of an agent action (a tool name plus a short target — never transcript or model prose). Optional; absent means the runner emits no session-tier stream (degraded tier).",
+            "items": { "type": "string", "maxLength": 160 }
+          }
+        }
+      }
+    },
+    "needs_you": {
+      "type": "array",
+      "description": "the operator queue — doors pending, escalations, exhausted retries, budget trips.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "message", "unblock"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "minLength": 1,
+            "description": "e.g. one-way-door | escalation | retry-exhausted | stranded-in-review | ledger-ahead-of-git | budget."
+          },
+          "unit_id": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 },
+          "unblock": {
+            "type": "string",
+            "minLength": 1,
+            "description": "the exact operator command (or config fix) that clears this entry."
+          }
+        }
+      }
+    },
+    "counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["merged", "escalated", "parked", "in_flight", "needs_you"],
+      "properties": {
+        "merged": { "type": "integer", "minimum": 0 },
+        "escalated": { "type": "integer", "minimum": 0 },
+        "parked": { "type": "integer", "minimum": 0 },
+        "in_flight": { "type": "integer", "minimum": 0 },
+        "needs_you": { "type": "integer", "minimum": 0 },
+        "dag_size": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schema/session-event.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/session-event.schema.json",
+  "title": "Contract D — session event body",
+  "description": "The `body` of a `session.*` ledger event, emitted by an agent adapter (Claude Code first) through `harness ledger append`. One session = one agent working one unit in one component. Carries model id, config hash, token counts, cost, in-loop (ring-0) gate firings, and escalations. This is the join key set for fleet telemetry: agent-harness joins these to Contract B envelopes by `session_id`. system-harness never reads a session event to decide a merge (solution design D2). v1 keeps per-phase fields optional; the ledger event's `type` (session.started | heartbeat | gate_fired | escalated | ended) is the discriminator.",
+  "type": "object",
+  "required": ["session_id", "unit_id", "component_id"],
+  "additionalProperties": false,
+  "properties": {
+    "session_id": { "type": "string", "minLength": 1 },
+    "unit_id": { "type": "string", "minLength": 1 },
+    "component_id": { "type": "string", "minLength": 1 },
+    "phase": {
+      "enum": ["started", "heartbeat", "gate_fired", "escalated", "ended"],
+      "description": "mirrors the ledger event type suffix; optional self-description for standalone consumers"
+    },
+    "emitter": {
+      "enum": ["adapter", "orchestrator"],
+      "default": "adapter",
+      "description": "who produced this event. `adapter` (default) = first-hand, from the agent's own agent-harness adapter in-session. `orchestrator` = reconstructed by orchestration-harness from a RunResult for a runner with no adapter (P7.1 / degraded tier); telemetry joins keep the distinction."
+    },
+    "model": {
+      "type": "string",
+      "description": "model id, e.g. claude-fable-5"
+    },
+    "runner": { "type": "string" },
+    "role": { "enum": ["implementer", "verifier"] },
+    "transcript_ref": { "type": ["string", "null"] },
+    "config_hash": {
+      "type": "string",
+      "description": "hash of the model config/preset; distinguishes A/B arms of one route"
+    },
+    "tokens": {
+      "type": "object",
+      "required": ["in", "out"],
+      "additionalProperties": false,
+      "properties": {
+        "in": { "type": "integer", "minimum": 0 },
+        "out": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "cost_usd": { "type": "number", "minimum": 0 },
+    "gate": {
+      "type": "object",
+      "description": "present on session.gate_fired — a ring-0 (`gate --pre`) firing observed in the loop",
+      "required": ["name", "outcome"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "outcome": { "enum": ["pass", "fail"] },
+        "ring": { "const": 0 }
+      }
+    },
+    "escalation": {
+      "type": "object",
+      "description": "present on session.escalated",
+      "required": ["reason", "wants"],
+      "additionalProperties": false,
+      "properties": {
+        "reason": { "type": "string", "minLength": 1 },
+        "wants": { "type": "string", "minLength": 1 }
+      }
+    },
+    "ended": {
+      "type": "object",
+      "description": "present on session.ended",
+      "required": ["outcome"],
+      "additionalProperties": false,
+      "properties": {
+        "outcome": { "enum": ["handed-off", "escalated", "abandoned"] }
+      }
+    }
+  }
+}

package/schema/spec.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/spec.schema.json",
+  "title": "Spec standard — the required form of a unit of work",
+  "description": "What the `spec` gate lints. Every acceptance criterion is either machine-checkable (names a verifier) or explicitly manual with a reason — absence is an error, the same declined-with-reason structure the manifest uses. Mechanizes the FORM of specs; intent quality remains the human's job upstream. Component-first extension per system-harness-blueprint.md §3 (\"Spec standard (extended)\"): every unit names its `component`; `outputs`/`consumes` reference artifact names declared in Contract C (system.toml); `deps` items are `[component#]unit-id`.",
+  "type": "object",
+  "required": ["id", "component", "intent", "acceptance_criteria", "scope"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[^#]+$",
+      "description": "globally unique bare canonical unit id; component identity belongs in the component field"
+    },
+    "component": {
+      "type": "string",
+      "description": "the component this unit belongs to (must exist in system.toml). One agent session works one component — blueprint §1."
+    },
+    "mode": {
+      "enum": ["build", "explore"],
+      "default": "build",
+      "description": "explore = a throwaway branch, ring-0 gates only, NO edge to merged (D7). Its only exits are abort or graduate (graduate emits a draft build spec from what was learned)."
+    },
+    "intent": { "type": "string", "minLength": 20 },
+    "acceptance_criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["statement"],
+        "properties": {
+          "statement": {
+            "type": "string",
+            "description": "RFC 2119 vocabulary (MUST/SHOULD/MAY); Given-When-Then encouraged"
+          },
+          "verifier": {
+            "type": "string",
+            "description": "gate name or command that checks this mechanically"
+          },
+          "manual": {
+            "type": "string",
+            "minLength": 10,
+            "description": "reason this criterion cannot be machine-checked"
+          }
+        },
+        "oneOf": [{ "required": ["verifier"] }, { "required": ["manual"] }]
+      }
+    },
+    "scope": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "path globs this unit may touch; anything outside halts (fail closed), never warns"
+    },
+    "size_budget": {
+      "type": "object",
+      "properties": {
+        "max_changed_lines": { "type": "integer", "default": 400 },
+        "max_changed_files": { "type": "integer", "default": 15 }
+      },
+      "description": "the `size` gate's input — bounded diffs are the biggest single lever on review quality and blast radius"
+    },
+    "door": {
+      "enum": ["two-way", "one-way"],
+      "description": "one-way (or unset) requires human approval at merge"
+    },
+    "merge_facts": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "the spec-declared merge facts `harness merge` classifies a door from (src/doors/classify.ts fact set). Booleans, all default false; `door` above stays the top-level field. `harness claim --json` (P7.4) delivers these to the orchestrator verbatim — facts are declared here and only here, never diff-guessed.",
+      "properties": {
+        "adds_dependency": {
+          "type": "boolean",
+          "default": false,
+          "description": "the change adds a runtime/build dependency (`harness merge --adds-dependency`)"
+        },
+        "schema_change": {
+          "type": "boolean",
+          "default": false,
+          "description": "the change touches a schema or a published API surface (`--schema-change`)"
+        },
+        "security": {
+          "type": "boolean",
+          "default": false,
+          "description": "the change touches auth, crypto, secrets, or another security-sensitive path (`--security`)"
+        },
+        "gate_external": {
+          "type": "boolean",
+          "default": false,
+          "description": "the change runs a gate marked external:true — a deploy-phase side effect (`--gate-external`)"
+        },
+        "artifact_producer_change": {
+          "type": "boolean",
+          "default": false,
+          "description": "the change alters a published artifact's producer (`--artifact-producer-change`)"
+        }
+      }
+    },
+    "deps": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "unit ids this unit depends on; cross-component deps are written `component#unit-id`, same-component deps may omit the prefix"
+    },
+    "outputs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "artifact names this unit publishes; each MUST be declared in system.toml with this unit's component as producer (blueprint §3)"
+    },
+    "consumes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "artifact names this unit consumes; the `spec` gate checks every one has a producer unit upstream in the DAG"
+    }
+  }
+}