@mikenguyen69/harness 0.1.0-beta.1

package/schema/system.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schema/system.schema.json",
+  "title": "Contract C — system manifest (system.toml)",
+  "description": "Implements system-harness-blueprint.md §3 (\"Contract C — system manifest\"). The system's single source of topology: the component DAG, typed artifact handoffs, and e2e scenario ownership. Owned like policy — versioned data, changed by reviewed PR. Consumed by `harness verify --system` (blueprint §4, ring 2): DAG acyclic, no unit scope crosses a component, every consumed artifact hash matches its producer's latest. This schema describes the parsed TOML: `[system]` -> object, `[[component]]` -> array, etc.",
+  "type": "object",
+  "required": ["system", "component"],
+  "additionalProperties": false,
+  "properties": {
+    "system": {
+      "type": "object",
+      "required": ["id"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "system identifier, e.g. 'acme'"
+        }
+      }
+    },
+    "component": {
+      "type": "array",
+      "minItems": 1,
+      "description": "one entry per component — a thing with its own build, verification, deploy surface, and blast radius. The scope unit: one agent session works one component (blueprint §1).",
+      "items": {
+        "type": "object",
+        "required": ["id", "profile"],
+        "additionalProperties": false,
+        "oneOf": [
+          {
+            "required": ["root"],
+            "description": "monorepo: component lives at a path prefix"
+          },
+          {
+            "required": ["repo"],
+            "description": "polyrepo: component lives in its own git repository"
+          }
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "component name, unique within the system; referenced by spec.component, envelope.component_id, and other components' deps"
+          },
+          "root": {
+            "type": "string",
+            "description": "path prefix from the system root, e.g. 'apps/backend/' (monorepo). Mutually exclusive with repo."
+          },
+          "repo": {
+            "type": "string",
+            "description": "git URL when the component is its own repository, e.g. 'git@github.com:acme/acme-infra'. Mutually exclusive with root — the one line that changes when a component graduates out."
+          },
+          "profile": {
+            "type": "string",
+            "description": "base profile name, e.g. 'typescript', 'terraform', 'playwright'"
+          },
+          "deps": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "component ids this one depends on; the DAG, validated acyclic. Dependencies point down only."
+          },
+          "mode": {
+            "enum": ["standard", "propose-only"],
+            "default": "standard",
+            "description": "propose-only = a human approves before commit (e.g. a component that is mostly UX copy)"
+          },
+          "role": {
+            "enum": ["standard", "integration"],
+            "default": "standard",
+            "description": "integration = runs only after every dep's verify has passed (the e2e ring, blueprint §4)"
+          }
+        }
+      }
+    },
+    "artifact": {
+      "type": "array",
+      "description": "typed handoffs between components — never prose. Referenced by spec.outputs / spec.consumes and proven in envelope.artifacts by hash.",
+      "items": {
+        "type": "object",
+        "required": ["name", "producer", "schema"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "artifact identifier, e.g. 'rate-limit-config'"
+          },
+          "producer": {
+            "type": "string",
+            "description": "component id that publishes this artifact (exactly one)"
+          },
+          "schema": {
+            "type": "string",
+            "description": "path to the JSON Schema the artifact value validates against, e.g. 'artifacts/rate-limit-config.schema.json'"
+          }
+        }
+      }
+    },
+    "scenario_ownership": {
+      "type": "array",
+      "description": "e2e failure routing (blueprint §4, ring 3): a failing integration scenario becomes a new scoped unit for the owning component(s), and the failure itself becomes a corpus fixture.",
+      "items": {
+        "type": "object",
+        "required": ["match", "owns"],
+        "additionalProperties": false,
+        "properties": {
+          "match": {
+            "type": "string",
+            "description": "glob over scenario ids, e.g. 'rate-limit/*'"
+          },
+          "owns": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" },
+            "description": "component ids that own failures matching this pattern"
+          }
+        }
+      }
+    },
+    "door_class": {
+      "type": "array",
+      "description": "Merge-door routing as reviewed data (solution design §6.3). A merge whose facts match `match` is routed to `class`. Matched against: gate:external, artifact-producer-change, new-dependency, schema-or-api-change, security-touching, component:<id>, mode:<name>. Nothing hardcoded in src — this array plus schema/decision-classes.yaml are the whole policy.",
+      "items": {
+        "type": "object",
+        "required": ["match", "class"],
+        "additionalProperties": false,
+        "properties": {
+          "match": {
+            "type": "string",
+            "description": "a condition token, e.g. 'gate:external', 'artifact-producer-change', 'component:frontend', 'mode:propose-only'"
+          },
+          "class": {
+            "enum": ["two-way", "one-way", "propose-only"],
+            "description": "two-way auto-passes on green verify; one-way and propose-only halt for an operator decision"
+          },
+          "until": {
+            "type": "string",
+            "description": "condition that relaxes this class once measured, e.g. 'route-eval>=90' (D8)"
+          }
+        }
+      }
+    }
+  }
+}

package/templates/ci/verify.yml

@@ -0,0 +1,23 @@
+# Reusable verify workflow — consuming repos import this; `harness init`
+# wires it. CI is just another caller of the same entrypoint (principle 2).
+name: harness-verify
+
+on:
+  workflow_call: {}
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 } # changed-lines severity needs the base
+      - uses: actions/setup-node@v4
+        with: { node-version: 24 }
+      - name: Run harness verify
+        run: npx harness verify
+      - name: Upload report envelope
+        if: always() # calibration needs failures too
+        uses: actions/upload-artifact@v4
+        with:
+          name: harness-envelope
+          path: .harness/reports/

package/templates/target-kit/README.md

@@ -0,0 +1,78 @@
+# Target intake kit
+
+These templates are a reviewed starting point, not target-ready configuration.
+They intentionally contain `REPLACE` markers and fail-closed gates. Copy them
+only after the intake checklist is complete; replace every marker before
+materializing a unit.
+
+**Operator prerequisite:** install the published package
+(`npm install --global @mikenguyen69/harness@next`) and follow
+[docs/onboarding.md](../../../../docs/onboarding.md). Do not wire compiled
+portfolio entrypoints for target work.
+
+Expected target layout:
+
+```text
+component.toml
+system.toml
+routes.toml
+orchestration.json
+profiles/target/bindings.toml
+specs/first-unit.yaml
+```
+
+Before dispatch, record:
+
+- absolute repository path;
+- base branch and exact base commit SHA;
+- language/runtime/package-manager versions;
+- normal install, format, lint, typecheck, test, build, and security commands;
+- component IDs and absolute/relative component roots;
+- the first unit's exact allowed file globs and explicit exclusions;
+- external services the checks contact, including offline alternatives;
+- required secret names, their source, and which subprocess may read them;
+- maximum cost, wall time, parallelism, and retry count;
+- whether local fast-forward is allowed or the run must stop before merge;
+- rollback command and the disposable branch/worktree policy;
+- evidence directory outside generated/build output;
+- a low-risk first change with objective acceptance criteria.
+
+Then:
+
+1. Copy and customize all templates.
+2. Run `rg -n "REPLACE" component.toml system.toml routes.toml orchestration.json profiles specs`; zero matches are required.
+3. From the target root, scaffold hooks (no separate hook-install step):
+
+```sh
+harness init
+```
+
+   Hook installation is one step of `harness init`. Owner: system-harness
+   `init` composing the agent-harness hook-install path; generated commands call
+   `harness hook pre-tool-use`.
+4. Read-only preflight, then materialize once:
+
+```sh
+harness spec check --specs ./specs --system ./system.toml
+harness spec materialize --specs ./specs --system ./system.toml --ledger ./.harness/ledger --json
+harness doctor --repo . --routes ./routes.toml --spool ./.harness/spool --json
+```
+
+5. Review doctor’s resolved runner/model, commands, budgets, base branch, and dirty-tree decision.
+6. Obtain separate authorization for the target dispatch and its merge policy.
+   Installing `@mikenguyen69/harness` authorizes neither a dry run nor a real target
+   run. `doctor` / `spec check` do not dispatch agents.
+
+Only after that authorization:
+
+```sh
+harness run --repo . --config ./orchestration.json --routes ./routes.toml --spool ./.harness/spool --report ./run-report.html
+```
+
+Evidence lands in `.harness/ledger/`, the `--spool` directory, the `--report`
+path, and (by default) `.harness/runs/<run-id>/`. On a one-way door halt,
+approve then `harness resume --unit <id> …` — see
+[docs/onboarding.md](../../../../docs/onboarding.md).
+
+The operator keeps the target base SHA and evidence directory. The agent must
+not infer them or broaden scope from repository contents.

package/templates/target-kit/component.toml

@@ -0,0 +1,20 @@
+# REPLACE every command/decline rationale with the target's reviewed policy.
+[harness]
+policy_version = "0.0.1"
+profile = "target"
+mode = "standard"
+
+[gates]
+# Fail closed until the target's real commands replace these sentinels.
+types = { run = "node -e \"process.exit(1)\"", severity = "blocking", cost = "cheap" }
+test = { run = "node -e \"process.exit(1)\"", severity = "blocking", cost = "cheap" }
+
+spec = { declined = "REPLACE: bind the target spec check or justify declining it" }
+fmt = { declined = "REPLACE: bind the target formatter" }
+lint = { declined = "REPLACE: bind the target linter" }
+arch = { declined = "REPLACE: bind architecture checks or document why absent" }
+contract = { declined = "REPLACE: bind API/schema compatibility checks if applicable" }
+size = { declined = "REPLACE: define a change-size policy" }
+"gen:fresh" = { declined = "REPLACE: bind generated-artifact freshness if applicable" }
+"sec:deps" = { declined = "REPLACE: bind an offline dependency advisory check" }
+"sec:secrets" = { declined = "REPLACE: bind secret scanning" }

package/templates/target-kit/orchestration.json

@@ -0,0 +1,9 @@
+{
+  "forge": "local",
+  "baseBranch": "REPLACE-base-branch",
+  "maxParallel": 1,
+  "retryBudget": 0,
+  "maxRunCost": 2,
+  "maxRunDuration": 900000,
+  "runners": { "enabled": ["claude"] }
+}

package/templates/target-kit/profiles/target/bindings.toml

@@ -0,0 +1,6 @@
+[harness]
+profile_version = "0.0.1"
+
+# The component contract owns the initial bindings. Move stable, shared target
+# bindings here only after the first dry run proves them.
+[gates]

package/templates/target-kit/routes.toml

@@ -0,0 +1,5 @@
+[[route]]
+profile = "target"
+runner = "claude"
+model = "REPLACE-approved-model"
+mode = "standard"

package/templates/target-kit/specs/first-unit.yaml

@@ -0,0 +1,11 @@
+id: first-unit
+component: app
+intent: >
+  REPLACE with one low-risk, observable change that can be reverted locally.
+acceptance_criteria:
+  - statement: REPLACE with an objective behavior the normal test suite proves
+    verifier: test
+scope:
+  - REPLACE/with/exact/allowed/glob/**
+door: two-way
+merge_facts: {}

package/templates/target-kit/system.toml

@@ -0,0 +1,7 @@
+[system]
+id = "REPLACE-target-system-id"
+
+[[component]]
+id = "app"
+root = "."
+profile = "target"