@agentskit/harness 0.3.0 → 0.5.0

package/loop.config.example.yaml

@@ -0,0 +1,121 @@
+# @agentskit/harness — keep-pushing loop configuration.
+# Copy to <your project>/loop.config.yaml. Everything project-specific lives here; the loop code has no names, paths or ids.
+# Never put secrets in this file: `envKeys` are the NAMES of environment variables the loop checks, not their values.
+schemaVersion: 1
+
+project:
+  name: my-project
+  repo: my-org/my-project            # GitHub owner/name used for PR review and merge
+  baseBranch: main
+  root: .                            # relative to this file
+  stateDir: .codex/loop              # ledger, cooldowns, contracts
+
+orca:
+  bin: orca                          # on Linux outside Orca terminals use orca-ide (bare `orca` is the GNOME screen reader)
+  # repoSelector: id:<orca-repo-id>  # default: path:<project.root>
+  # workspaceSelector: path:/abs/main/checkout   # existing worktree the automations run in
+  # host: runtime:<environment-id>   # paired remote Orca host
+  minVersion: 1.4.200
+  timeoutMs: 20000
+
+linear:
+  workspaceId: <linear-workspace-id> # orca linear team list --workspace all --json
+  teamKey: ENG
+  person: my-linear-display-name     # the ONLY queue this machine drains
+  people:                            # display name -> Linear user id (orca linear team members …)
+    my-linear-display-name: <linear-user-id>
+  states: [Todo, Ready]              # dispatchable states; anything already started is left alone
+  excludeLabels: [blocked, needs-info]
+  requireLabels: []
+  projects: []                       # empty = all projects
+  order: [priority, updatedAt]       # urgent first; priority 0 (none) sorts last
+  maxQueue: 50
+  inProgressState: In Progress
+  reviewState: In Review
+  doneState: Done
+  blockedLabel: blocked
+  needsInfoLabel: needs-info
+
+models:
+  # Tiers, in order. Inside a tier the first provider with usage available wins.
+  # Tier 1 = subscriptions, tier 2 = cheap hosted, tier 3 = last resort.
+  orchestrator: [[codex/gpt-5.6-sol, claude/opus], [opencode/opencode-go/glm-5.3], [grok/grok-4-fast]]
+  reviewer:     [[codex/gpt-5.6-sol, claude/opus], [opencode/opencode-go/glm-5.3], [grok/grok-4-fast]]
+  builder:      [[codex/gpt-5.6-luna, claude/sonnet, claude/haiku], [opencode/opencode-go/glm-5.3-flash], [grok/grok-4-fast]]
+  watcher:      [[claude/haiku, codex/gpt-5.6-luna], [opencode/opencode-go/glm-5.3-flash]]
+  cooldown:
+    initialMin: 30                   # provider marked exhausted without a known reset waits 30 min, doubling…
+    maxMin: 240                      # …up to 4 h
+    probeBeforeReenable: true
+    exhaustedPercent: 100
+  providers:
+    claude:
+      bin: claude
+      auth: subscription
+      envKeys: [ANTHROPIC_API_KEY]   # optional API-key fallback
+      tui: "claude --model {model} --permission-mode auto"
+      headless: [claude, -p, "{prompt}", --model, "{model}", --permission-mode, plan, --output-format, text]
+    codex:
+      bin: codex
+      auth: subscription
+      envKeys: [OPENAI_API_KEY]
+      tui: "codex -m {model} --full-auto"
+      headless: [codex, exec, -m, "{model}", -s, read-only, --skip-git-repo-check, "{prompt}"]
+    opencode:
+      bin: opencode
+      auth: none
+      orcaUsageKey: opencodeGo       # key inside `orca account list` rateLimits
+      tui: "opencode -m {model}"
+      headless: [opencode, run, -m, "{model}", --agent, plan, "{prompt}"]
+    grok:
+      bin: grok
+      auth: subscription             # `grok login` (OAuth) — no API key needed
+      tui: "grok -m {model}"
+      headless: [grok, -p, "{prompt}", -m, "{model}"]
+
+machine:
+  floor: 1                           # always allow one worker
+  # ceiling: 4                       # default: cpus / 2
+  minFreeRamGb: 4
+  warningPercent: 75
+  criticalPercent: 90
+  agentRssMb: 1400                   # RAM budget per agent when live RSS is unknown
+  wslCap: 1                          # host Defender load is invisible from a WSL distro
+
+delivery:
+  verifyCommand: "pnpm lint && pnpm test"   # what the worker must pass before opening a PR
+  review:
+    cli: agentskit-review
+    mode: trusted-local              # reuse this user's CLI logins; the isolated default has no credentials
+    profile: fast                    # one bounded pass over required lenses; `full` needs batching to fit a 600 s stage
+    votes: 1
+    concurrency: 4
+    minSeverity: med                 # nit < med < high < blocker; findings at/above this block auto-merge
+    deadlineMs: 600000
+  merge:
+    auto: true
+    method: squash
+    requireChecks: true
+  maxFixRounds: 2
+  workerIdleTimeoutMin: 45
+  selfEditPaths: [loop.config.yaml, ".github/**"]   # PRs touching these never auto-merge
+  ignoreChecks: []                   # advisory check names that never block
+  requiredChecks: []                 # empty = every reported check must be green
+  cleanupWorktree: true              # remove the Orca worktree after merge
+  returnState: Todo                  # where a stuck/blocked issue goes back to
+
+contract:
+  maxIssueChars: 12000               # issue text rendered into the orchestrator prompt (as untrusted data)
+  timeoutMs: 300000
+  maxContextReferences: 6            # Doc Bridge hits appended when .doc-bridge/index.json exists
+  reuseHours: 72                     # cached contract reused for this long
+
+schedule:
+  tick: "*/5 * * * *"
+  deliver: "*/10 * * * *"
+  precheckTimeoutSec: 120
+  harnessCommand: ak-harness         # how the Orca automation runs the harness inside the workspace
+  namePrefix: loop                   # automations: loop-tick, loop-deliver
+  runner: precheck                   # the stage runs inside Orca's precheck command; no agent session is ever opened
+  stageTimeoutSec: 600               # Orca caps prechecks at 600 s; one tick/deliver run must fit
+  # provider: claude                 # Orca agent that executes the automation prompt (default: watcher role)

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@agentskit/harness",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Portable, evidence-backed development harness for coding agents.",
   "type": "module",
-  "bin": { "ak-harness": "dist/cli.js", "ak-verify": "dist/cli.js" },
+  "bin": {
+    "ak-harness": "dist/cli.js",
+    "ak-verify": "dist/cli.js"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,8 +15,25 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md", "MANIFESTO.md", "LICENSE", "docs"],
-  "engines": { "node": ">=22" },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "MANIFESTO.md",
+    "LICENSE",
+    "docs",
+    "capabilities",
+    "examples",
+    "compatibility",
+    "release",
+    "loop.config.example.yaml"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "tsup && node -e \"console.log(JSON.stringify({status:'passed',criteria:['package']}))\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -43,6 +63,18 @@
     "test:optimization": "pnpm typecheck && vitest run --config vitest.config.ts test/optimization.test.ts test/issues-010-014.eval.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['optimization-contracts','eval','cache','parallelism']}))\"",
     "test:source": "pnpm typecheck && vitest run --config vitest.config.ts test/source.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['source-current']}))\"",
     "test:metrics": "pnpm typecheck && vitest run --config vitest.config.ts test/metrics.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['metrics']}))\"",
+    "test:capabilities": "node scripts/generate-capability-manifest.mjs --check capabilities/public-surface.json",
+    "test:boundaries": "pnpm typecheck && vitest run --config vitest.config.ts test/boundaries.test.ts && node scripts/verify-dependency-directions.mjs",
+    "test:phase-executor": "pnpm typecheck && vitest run --config vitest.config.ts test/phase-executor.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['phase-executor']}))\"",
+    "test:artifacts": "pnpm typecheck && vitest run --config vitest.config.ts test/artifacts.test.ts && node scripts/verify-artifact-cli.mjs",
+    "test:adapters": "pnpm typecheck && vitest run --config vitest.config.ts test/adapters.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['adapters']}))\"",
+    "test:loop": "pnpm typecheck && vitest run --config vitest.config.ts test/loop.test.ts test/loop-adapters.test.ts test/loop-tick.test.ts test/loop-deliver.test.ts test/loop-install.test.ts test/loop-guided-install.test.ts test/loop-retro.test.ts test/loop-debrief.test.ts test/loop-watch.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['loop-config','loop-providers','loop-routing','loop-doctor','loop-adapters','loop-tick','loop-deliver','loop-install','loop-debrief','loop-watch']}))\"",
+    "test:review": "pnpm typecheck && vitest run --config vitest.config.ts test/review.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['review-delivery']}))\"",
+    "test:quality": "pnpm typecheck && vitest run --config vitest.config.ts test/quality.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['quality-matrix']}))\"",
+    "test:eval-battery": "pnpm typecheck && vitest run --config vitest.config.ts test/eval-battery.test.ts test/issues-010-014.eval.test.ts test/optimization.test.ts && pnpm build >/dev/null && node scripts/verify-harness-eval-manifest.mjs && node -e \"console.log(JSON.stringify({status:'passed',criteria:['eval-battery','eval-manifest','eval-coverage']}))\"",
+    "test:compatibility": "pnpm typecheck && vitest run --config vitest.config.ts test/compatibility.test.ts && pnpm build >/dev/null && node scripts/verify-harness-compatibility-manifest.mjs && node -e \"console.log(JSON.stringify({status:'passed',criteria:['compatibility-contract','compatibility-manifest','pinned-revisions','real-adapter-boundary']}))\"",
+    "test:examples": "pnpm typecheck && pnpm build >/dev/null && node scripts/verify-harness-examples.mjs && node scripts/verify-adoption-docs.mjs",
+    "test:release-manifest": "pnpm typecheck && pnpm build >/dev/null && node scripts/verify-release-workflow.mjs && node scripts/verify-release-manifest.mjs",
     "test:benchmark-record": "pnpm typecheck && node scripts/verify-harness-benchmark-record.mjs",
     "test:agent-protocol": "pnpm typecheck && vitest run --config vitest.config.ts test/agent.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['agent-protocol']}))\"",
     "test:policy-gate": "pnpm typecheck && vitest run --config vitest.config.ts test/policy.test.ts test/agent.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['policy-gate','agent-protocol']}))\"",
@@ -53,10 +85,15 @@
     "prepublishOnly": "pnpm typecheck && pnpm build && pnpm test"
   },
   "dependencies": {
-    "commander": "^14.0.0"
+    "commander": "^14.0.0",
+    "ink": "7.1.1",
+    "react": "19.3.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.6.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/react": "^19.3.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.10"
@@ -67,9 +104,14 @@
     "type": "git",
     "url": "git+https://github.com/AgentsKit-io/harness.git"
   },
-  "bugs": { "url": "https://github.com/AgentsKit-io/harness/issues" },
+  "bugs": {
+    "url": "https://github.com/AgentsKit-io/harness/issues"
+  },
   "homepage": "https://github.com/AgentsKit-io/harness",
   "author": "AgentsKit Contributors",
   "sideEffects": false,
-  "publishConfig": { "access": "public", "provenance": true }
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
 }

package/release/manifest.json

@@ -0,0 +1,36 @@
+{
+  "type": "agentskit-harness-release-manifest",
+  "schemaVersion": 1,
+  "package": "@agentskit/harness",
+  "version": "0.5.0",
+  "channel": "latest",
+  "sourceRevision": "b8cfe596e5f30f2c373b89f00f271079b296feaf",
+  "requiredChecks": [
+    "typecheck",
+    "test",
+    "build",
+    "pack",
+    "cli",
+    "consumer",
+    "eval-battery",
+    "pilot-benchmark",
+    "ecosystem-compatibility",
+    "registry-smoke"
+  ],
+  "publication": {
+    "workflow": ".github/workflows/release-harness.yml",
+    "branch": "main",
+    "trustedPublishing": true,
+    "usesNpmToken": false
+  },
+  "evidenceOutputs": [
+    "release/qualification.json",
+    "release/notes.md"
+  ],
+  "blockedCriteria": [
+    "ecosystem-compatibility",
+    "pilot-benchmark"
+  ],
+  "nextBaseline": "benchmarks/harness-0.4.0-baseline.json",
+  "digest": "712347d25fac5a6b0819cf8ba60f11ba9dc37c8d9380fb7df9e834f711509a86"
+}

package/release/notes.md

@@ -0,0 +1,25 @@
+# 0.5.0 release candidate
+
+This release adds the keep-pushing SDLC loop (`ak-harness loop …`): project config with a per-machine overlay,
+provider detection with Orca usage awareness and cooldowns, tiered model routing, machine slot assessment, Orca /
+Linear / GitHub / code-review adapters, the dispatch tick with orchestrator-frozen contracts, the deliver stage
+(CI → review → fix rounds → squash-merge → Linear Done) and the Orca automation installer. See `docs/LOOP.md` and
+ADR-0027. `yaml` and `zod` become runtime dependencies.
+
+Publication happens only when this candidate merges to `main` (release workflow, npm Trusted Publishing, no
+`NPM_TOKEN`). `release/qualification.json` still records the 0.4.0 publication and will be refreshed after 0.5.0 is
+on the registry. Compatibility and pilot-benchmark criteria remain fail-closed as in 0.4.0.
+
+# 0.4.0 release
+
+This release packages the deterministic SDLC kernel, phase quality matrix,
+versioned eval battery, compatibility contract, and consumer examples.
+
+Publication is intentionally limited to a merge on `main`. The release
+workflow uses npm Trusted Publishing (`id-token: write`) and no `NPM_TOKEN`.
+
+The package was published from `main` through npm Trusted Publishing at
+`2df60bcbda850382d1a1112f338fa53858c5d4cf`. Pinned upstream tests and the
+registry/consumer smoke are recorded as passed. Compatibility remains fail-closed
+until the real Code Review quality baseline and the owner-approved ten-task
+Harness/no-Harness pilot cohort are captured.

package/release/qualification.json

@@ -0,0 +1,14 @@
+{
+  "type": "agentskit-harness-release-qualification",
+  "schemaVersion": 1,
+  "package": "@agentskit/harness",
+  "version": "0.4.0",
+  "sourceRevision": "2df60bcbda850382d1a1112f338fa53858c5d4cf",
+  "status": "blocked",
+  "harnessVerification": { "runId": "1789065264843-3627-dgz8xb", "decision": "COMPLETE", "checksPassed": 21, "checksTotal": 21 },
+  "upstreamCompatibility": { "report": "compatibility/report.json", "status": "blocked" },
+  "pilotBenchmark": { "status": "blocked", "reason": "No comparable owner-approved no-Harness cohort; real code-review run has no baseline and did not pass quality matrix." },
+  "registrySmoke": { "status": "passed", "registry": "https://registry.npmjs.org", "package": "@agentskit/harness@0.4.0", "consumerImport": "passed (runEvalBattery, startRun)", "cliHelp": "passed (ak-verify)" },
+  "publishable": false,
+  "blockers": ["ecosystem-compatibility", "pilot-benchmark"]
+}