@mikenguyen69/harness 0.1.0-beta.1

package/profiles/terraform/bindings.toml

@@ -0,0 +1,66 @@
+# Terraform profile — the 10-name vocabulary (ADR 0004) bound to a Terraform
+# stack. This file is the ENTIRE diff for a second stack: zero src changes.
+#
+# The hermetic rule: `terraform validate` and `fmt` are offline and safe in
+# `verify`; anything that reaches a provider or state (`plan` against real infra)
+# is marked external = true and runs only in the component's deploy phase.
+
+[harness]
+profile_version = "0.0.1"
+
+[gates.spec]
+run = "harness gate spec"
+severity = "blocking"
+cost = "cheap"
+
+[gates.fmt]
+run = "terraform fmt -check -recursive"
+severity = "blocking"
+cost = "cheap"
+
+[gates.lint]
+run = "tflint --format compact"
+severity = "changed-lines"
+cost = "cheap"
+
+[gates.types]
+run = "terraform validate"          # offline: schema + reference checks
+severity = "blocking"
+cost = "cheap"
+
+[gates.test]
+run = "terraform test"              # native test framework, module-scoped
+severity = "advisory"
+cost = "expensive"
+
+[gates."sec:deps"]
+run = "trivy config --exit-code 1 ."
+severity = "changed-lines"
+cost = "cheap"
+snapshot_max_age_days = 7
+
+[gates."sec:secrets"]
+run = "gitleaks detect --no-banner"
+severity = "blocking"
+cost = "cheap"
+
+[gates.arch]
+run = "checkov -d . --compact --quiet"
+severity = "advisory"
+cost = "cheap"
+
+[gates.contract]
+run = "terraform plan -detailed-exitcode -lock=false"   # reality check vs live state
+severity = "advisory"
+cost = "expensive"
+external = true                     # deploy phase only — never in hermetic verify
+
+[gates.size]
+run = "harness gate size"
+severity = "blocking"
+cost = "cheap"
+
+[gates."gen:fresh"]
+run = "harness gate gen-fresh"
+severity = "blocking"
+cost = "cheap"

package/profiles/typescript/bindings.toml

@@ -0,0 +1,64 @@
+# TypeScript profile — reference bindings of the abstract vocabulary to real
+# tools. Data, not code: a consuming repo's component.toml starts from this and
+# overrides per module. Every vocabulary gate appears — bound or declined.
+#
+# Vocabulary: the 10-name closed set (ADR 0004) — spec fmt lint types test
+# sec:* arch contract size gen:fresh. `sec:*` is a namespace: bind as many
+# concrete sec:<tool> gates as the stack needs.
+
+[harness]
+profile_version = "0.0.2"
+
+[gates.spec]
+run = "harness gate spec"          # built-in linter vs schema/spec.schema.json
+severity = "blocking"
+cost = "cheap"
+
+[gates.fmt]
+run = "prettier --check ."
+severity = "blocking"
+cost = "cheap"
+
+[gates.lint]
+run = "eslint ."
+severity = "changed-lines"
+cost = "cheap"
+
+[gates.types]
+run = "tsc --noEmit"
+severity = "blocking"
+cost = "cheap"
+
+[gates.test]
+run = "vitest run"                 # the component's own fast suite; true cross-
+severity = "blocking"              # component integration is the ring-3 e2e
+cost = "cheap"                     # component (system.toml role="integration")
+
+[gates."sec:deps"]
+run = "osv-scanner --lockfile package-lock.json"
+severity = "changed-lines"
+cost = "cheap"
+snapshot_max_age_days = 7          # vendored advisory DB; no network during verify
+
+[gates."sec:secrets"]
+run = "gitleaks detect --no-banner"
+severity = "blocking"
+cost = "cheap"
+
+[gates.arch]
+run = "dependency-cruiser --validate .dependency-cruiser.cjs src"
+severity = "advisory"
+cost = "cheap"
+
+[gates.contract]
+declined = "no service boundary in the reference profile; bind per repo (openapi-diff / buf breaking)"
+
+[gates.size]
+run = "harness gate size"          # built-in: diff vs the unit's size_budget
+severity = "blocking"
+cost = "cheap"
+
+[gates."gen:fresh"]
+run = "harness gate gen-fresh"     # built-in: generated adapters match policy hash
+severity = "blocking"
+cost = "cheap"

package/profiles/typescript/smoke/README.md

@@ -0,0 +1,8 @@
+# TypeScript profile smoke test
+
+A tiny fixture repo proving the profile end to end: `harness init` scaffolds
+it, `harness verify` runs every bound gate against it and emits a valid
+envelope. Runs in the harness's own CI on every profile change.
+
+TODO(milestone 1): materialize the fixture (minimal package.json, one source
+file, one test, one deliberate lint finding to prove severity handling).

package/schema/baseline.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/baseline.schema.json",
+  "title": "Brownfield baseline — frozen debt inventory (.harness/baseline.json)",
+  "description": "Written once by `harness init --audit`, then only ever lowered (by verify runs observing debt shrink) — never raised by hand. Serves two roles: the ratchet floor (repo debt totals may only fall) and the calibration baseline ('is the harness helping' is measured against this). Live secrets never appear here: they are incidents to fix before init, not debt to ratchet.",
+  "type": "object",
+  "required": ["captured_at", "harness_version", "debt"],
+  "properties": {
+    "captured_at": { "type": "string", "format": "date-time" },
+    "harness_version": { "type": "string" },
+    "debt": {
+      "type": "object",
+      "description": "per-gate frozen finding counts, e.g. { \"lint\": 1847, \"types\": 612, \"fmt\": 311 }",
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
+    "outcome_baseline": {
+      "type": "object",
+      "description": "pre-harness delivery metrics for calibration (capture ~1 day of effort; without these, measurement can only report gate activity, never value)",
+      "properties": {
+        "escaped_defects_per_week": { "type": "number" },
+        "rework_rate": { "type": "number" },
+        "review_cycle_hours": { "type": "number" }
+      }
+    }
+  }
+}

package/schema/decision-classes.yaml

@@ -0,0 +1,45 @@
+# Decision classes — what always requires a human (v1 trust boundary).
+# Policy data, versioned and reviewed like the gate vocabulary.
+# Everything NOT listed is eligible for agent review once the reviewer has
+# earned it (seeded-defect catch rate — see calibration/).
+# Revisit as data accumulates; changes land as reviewed PRs, never inline.
+#
+# v2 (system-harness-blueprint.md §3): decision classes gain system scope —
+# rules that only exist once the system is a component DAG (system.toml).
+
+version: 2
+
+human_required:
+  - id: one-way-door
+    match: "unit.door == 'one-way' or unit.door unset"
+    why: irreversible decisions get a human by definition
+  - id: new-dependency
+    match: "diff adds entry to lockfile/manifest (package.json, go.mod, requirements, ...)"
+    why: supply-chain surface; agents pull packages without risk review
+  - id: schema-or-api-change
+    match: "diff touches API contracts, migrations, protobuf/openapi files"
+    why: breaks ripple across boundaries; contract gate catches compat, not intent
+  - id: security-touching
+    match: "diff touches auth, crypto, secrets handling, permission checks"
+    why: highest blast radius, weakest test coverage in most repos
+
+system_scope:
+  # Classes that exist only under Contract C (system.toml). Evaluated by
+  # `harness verify --system` (blueprint §4 ring 2) in addition to per-unit review.
+  - id: infra-apply
+    match: "unit.component's profile applies external infrastructure (e.g. terraform apply)"
+    door: one-way
+    why: infrastructure applies are irreversible by definition — write_external, always a human
+  - id: cross-component-api-change
+    match: "diff changes an interface a downstream component consumes (published artifact schema, cross-component API)"
+    why: breaks ripple across the component boundary; the contract gate catches compat, not intent
+  - id: producer-artifact-diff
+    match: "diff touches a published artifact's producer"
+    effect: re-verify all consumer components before merge
+    why: a stale artifact hash is a fail-closed condition, not a warning
+
+anti_rubber_stamp:
+  # A door approved >95% of the time within seconds is measurably dead:
+  # flag for demotion to two-way or redesign. Calibration job enforces.
+  approval_rate_threshold: 0.95
+  min_deliberation_seconds: 30

package/schema/envelope.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/envelope.schema.json",
+  "title": "Contract B — verify report envelope (component-first)",
+  "description": "One envelope per `harness verify` run, wrapping one SARIF file. The envelope IS the provenance record: work check, merge doors, CI, and calibration jobs all consume this same artifact. Honesty rules: retries are recorded per gate (a pass-on-retry is visibly not a clean pass); agent identity is self-reported until signed attestations land. Extended per system-harness-blueprint.md §3 (\"Contract B — envelope (extended)\"): every envelope names its `component_id`; `feature_id` is the top-level trace linking all units of one feature across components (null for standalone units); `artifacts` records which published contract values the unit was built against. Extended again by the review pass: `session_id` joins fleet telemetry (Contract D); `scope_attested` is the harness-computed diff-in-scope check; `signature` is the harness-key signature that makes envelopes unforgeable; per-gate `pre_failures` counts ring-0 catches.",
+  "type": "object",
+  "required": [
+    "envelope_version",
+    "harness_version",
+    "policy_version",
+    "profile_version",
+    "binding_hash",
+    "component_id",
+    "unit_id",
+    "spec_hash",
+    "agent_identity",
+    "started_at",
+    "gates",
+    "verdict",
+    "sarif_path",
+    "scope_attested",
+    "signature"
+  ],
+  "properties": {
+    "envelope_version": { "type": "string" },
+    "session_id": {
+      "type": ["string", "null"],
+      "description": "the agent-harness session that produced this run (Contract D); null for human/ci runs. This is the join key for fleet telemetry — system-harness never reads it back to decide a merge (solution design D2)."
+    },
+    "scope_attested": {
+      "type": "boolean",
+      "description": "true iff the diff is a subset of the unit's declared scope. Computed from the diff by the harness — never asserted by the agent. A false value is a fail-closed condition."
+    },
+    "scope_evidence": {
+      "type": "object",
+      "description": "signed inputs and result of the harness-computed diff-in-scope check",
+      "required": ["base_ref", "changed_files", "effective_scope", "violations", "reason"],
+      "properties": {
+        "base_ref": { "type": ["string", "null"] },
+        "changed_files": { "type": "array", "items": { "type": "string" } },
+        "effective_scope": { "type": "array", "items": { "type": "string" } },
+        "violations": { "type": "array", "items": { "type": "string" } },
+        "reason": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "signature": {
+      "type": "string",
+      "description": "detached signature over the canonical envelope body (every field except this one) by the harness binary key. Agents cannot mint envelopes; `agent_identity.attested` is a weaker self-report and is orthogonal."
+    },
+    "harness_version": { "type": "string", "description": "binary semver" },
+    "policy_version": {
+      "type": "string",
+      "description": "policy-data semver in force"
+    },
+    "profile_version": { "type": "string" },
+    "binding_hash": {
+      "type": "string",
+      "description": "hash of the resolved gate bindings — answers 'which rules were actually in force for this merge'"
+    },
+    "component_id": {
+      "type": "string",
+      "description": "the component this run verified (must exist in system.toml); every envelope names its component — blueprint §3"
+    },
+    "feature_id": {
+      "type": ["string", "null"],
+      "description": "top-level trace linking all units of one feature across components; null for standalone units. This is where product-harness's story-mapped feature ids land — no new field needed later."
+    },
+    "unit_id": { "type": "string" },
+    "spec_hash": { "type": "string" },
+    "artifacts": {
+      "type": "object",
+      "description": "typed handoffs this run produced or built against — proves which published contract values were in force (blueprint §3). Optional: absent when the component neither produces nor consumes artifacts.",
+      "properties": {
+        "produced": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "hash"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "artifact name, as declared in system.toml"
+              },
+              "hash": {
+                "type": "string",
+                "description": "content hash of the published artifact value"
+              },
+              "path": {
+                "type": "string",
+                "description": "path the artifact was written to"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "consumed": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "hash"],
+            "properties": {
+              "name": { "type": "string" },
+              "hash": {
+                "type": "string",
+                "description": "hash of the producer's value this unit built against; `verify --system` halts if it is stale"
+              },
+              "path": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "agent_identity": {
+      "type": "object",
+      "required": ["kind", "id", "attested"],
+      "properties": {
+        "kind": { "enum": ["agent", "human", "ci"] },
+        "id": {
+          "type": "string",
+          "description": "e.g. claude-fable-5, cursor+model, git author"
+        },
+        "attested": {
+          "type": "boolean",
+          "description": "false = self-reported (provenance-flavored, not provenance)"
+        }
+      }
+    },
+    "started_at": { "type": "string", "format": "date-time" },
+    "duration_ms": { "type": "integer" },
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "outcome", "severity", "duration_ms", "retries"],
+        "properties": {
+          "name": { "type": "string" },
+          "outcome": { "enum": ["pass", "fail", "declined", "quarantined"] },
+          "severity": { "enum": ["advisory", "changed-lines", "blocking"] },
+          "duration_ms": { "type": "integer" },
+          "retries": {
+            "type": "integer",
+            "minimum": 0,
+            "description": ">0 means pass-on-retry — never a clean pass"
+          },
+          "pre_failures": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "ring-0 (`gate --pre`) failures for this gate absorbed in-loop before this ring-1 run — the evidence of ring-0's value; feeds calibration and evals"
+          },
+          "declined_reason": { "type": "string" },
+          "quarantine_expires": {
+            "type": "string",
+            "format": "date-time",
+            "description": "flaky gates are quarantined with an expiry, never silently rerun"
+          },
+          "ratchet": {
+            "type": "object",
+            "description": "present in ratchet mode: the frozen debt floor and this run's observed total — current > floor fails even at changed-lines severity; current < floor lowers the floor",
+            "required": ["floor", "current"],
+            "properties": {
+              "floor": { "type": "integer", "minimum": 0 },
+              "current": { "type": "integer", "minimum": 0 }
+            }
+          }
+        }
+      }
+    },
+    "substrate": {
+      "type": "object",
+      "description": "self-report of the guarantee layer: when server-side enforcement is not yet active (dated cutover on brownfield repos), verify declares itself ADVISORY at the repo level rather than letting the guarantee be silently absent",
+      "required": ["enforced"],
+      "properties": {
+        "enforced": { "type": "boolean" },
+        "enforced_from": { "type": "string", "format": "date" }
+      }
+    },
+    "verdict": {
+      "enum": ["pass", "fail", "halt"],
+      "description": "halt = fail-closed condition (ambiguity, out-of-scope touch, all-skip). All-declined/all-skip is never 'pass'."
+    },
+    "sarif_path": { "type": "string" }
+  }
+}

package/schema/ledger-event.schema.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/ledger-event.schema.json",
+  "title": "Ledger event — one line of .harness/ledger/*.jsonl",
+  "description": "The record plane (solution design §5). One append-only, hash-chained event ledger per system is the single source of truth; the board, the hub index and calibration input are all derived and rebuildable. Each event is one JSON object on one line. `prev_hash` chains every event to its predecessor and `hash` is over this event's canonical form (all fields except `hash`), so any deletion or rewrite is evident at `harness ledger verify-chain` and at hub sync. system-harness emits spec.* unit.* envelope door.* system.* escape.* fixture.* calibration.*; agent-harness (Contract D) emits session.* eval.* through the same `harness ledger append` so chaining and signing stay in one implementation.",
+  "type": "object",
+  "required": [
+    "v",
+    "seq",
+    "ts",
+    "system",
+    "actor",
+    "type",
+    "prev_hash",
+    "hash",
+    "body"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "v": { "const": 1, "description": "ledger-event schema major version" },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "0-based position in the ledger; strictly increasing, no gaps. seq 0 is the genesis event."
+    },
+    "ts": { "type": "string", "format": "date-time" },
+    "system": {
+      "type": "string",
+      "minLength": 1,
+      "description": "system id — one ledger per system"
+    },
+    "actor": {
+      "type": "object",
+      "required": ["kind", "id"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "enum": ["harness", "agent", "human", "ci"] },
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "e.g. harness@1.2.0, claude-fable-5, git author, ci-runner"
+        }
+      }
+    },
+    "type": {
+      "enum": [
+        "spec.authored",
+        "spec.validated",
+        "spec.amended",
+        "unit.planned",
+        "unit.ready",
+        "unit.claimed",
+        "unit.done",
+        "unit.merged",
+        "unit.aborted",
+        "session.started",
+        "session.heartbeat",
+        "session.gate_fired",
+        "session.escalated",
+        "session.ended",
+        "envelope",
+        "door.opened",
+        "door.decided",
+        "door.expired",
+        "system.verified",
+        "system.halted",
+        "escape.detected",
+        "escape.routed",
+        "fixture.added",
+        "fixture.passed",
+        "fixture.reopened",
+        "eval.run",
+        "calibration.proposed",
+        "calibration.applied",
+        "run.analyzed"
+      ],
+      "description": "event type. `envelope` is a single type (not `envelope.*`) whose body is a full Contract B envelope."
+    },
+    "prev_hash": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "SHA-256 hex of the previous event's `hash`. The genesis event (seq 0) uses 64 zeros."
+    },
+    "hash": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "SHA-256 hex over the canonical JSON of this event with the `hash` key removed (so `prev_hash` is covered). verify-chain recomputes and compares every line."
+    },
+    "sig": {
+      "type": "string",
+      "description": "detached signature by the harness binary key. REQUIRED on `envelope` events — agents cannot mint them. Optional on other event types in v1."
+    },
+    "body": {
+      "type": "object",
+      "description": "event-specific payload. A few types are constrained below; the rest follow the taxonomy in solution design §5.1 and are tightened as their producers land."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "type": { "const": "envelope" } },
+        "required": ["type"]
+      },
+      "then": {
+        "required": ["sig"],
+        "properties": { "body": { "$ref": "envelope.schema.json" } }
+      }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "system.halted" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "body": {
+            "type": "object",
+            "required": ["cause"],
+            "properties": {
+              "cause": {
+                "enum": ["stale_artifact", "scope_cross", "dag_cycle"]
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "door.decided" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "body": {
+            "type": "object",
+            "required": ["verdict", "reason", "who"],
+            "properties": {
+              "verdict": { "enum": ["approved", "rejected"] },
+              "reason": { "type": "string", "minLength": 1 },
+              "who": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "calibration.proposed" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "body": {
+            "type": "object",
+            "required": ["action", "target"],
+            "properties": {
+              "action": { "enum": ["promote", "demote", "delete"] },
+              "target": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "eval.run" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "body": {
+            "type": "object",
+            "required": ["route", "catch_rate", "n"],
+            "properties": {
+              "route": { "type": "string" },
+              "catch_rate": { "type": "number", "minimum": 0, "maximum": 1 },
+              "n": { "type": "integer", "minimum": 0 }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "run.analyzed" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "body": {
+            "type": "object",
+            "required": ["run_id", "units", "findings", "log_ref"],
+            "description": "one bounded summary per orchestration run — metrics and rule ids only, no free-text prose (see the description on run.analyzed in ledger/index.ts).",
+            "properties": {
+              "run_id": { "type": "string", "minLength": 1 },
+              "units": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["unit_id", "turns_total", "attempts", "wall_ms"],
+                  "properties": {
+                    "unit_id": { "type": "string" },
+                    "turns_total": { "type": "integer", "minimum": 0 },
+                    "tool_failures": { "type": "integer", "minimum": 0 },
+                    "attempts": { "type": "integer", "minimum": 0 },
+                    "wall_ms": { "type": "integer", "minimum": 0 },
+                    "agent_ms": { "type": "integer", "minimum": 0 },
+                    "cost_usd": { "type": "number", "minimum": 0 },
+                    "runner": { "type": "string" },
+                    "model": { "type": "string" }
+                  }
+                }
+              },
+              "findings": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["rule", "unit_id", "severity"],
+                  "properties": {
+                    "rule": { "type": "string" },
+                    "unit_id": { "type": "string" },
+                    "severity": { "enum": ["info", "warn", "action"] },
+                    "count": { "type": "integer", "minimum": 0 }
+                  }
+                }
+              },
+              "log_ref": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  ]
+}