@agentskit/harness 0.3.0 → 0.4.0

package/docs/ADR-0026-kernel-adapters-boundary.md

@@ -0,0 +1,82 @@
+# ADR-0026: Kernel and adapter boundary for 0.4.0
+
+## Status
+
+Accepted — approved by the owner on 2026-09-10.
+
+## Context
+
+The Harness now contains deterministic SDLC controls, local execution
+plumbing, and three provider-facing adapters. The 0.4.0 goal is a modular
+engine that can plug in orchestrators, documentation, trackers, memory,
+models, MCP, and event bridges without making the kernel provider-specific.
+H-040 requires a baseline before changing behavior and must not infer
+architecture decisions that belong to the owner.
+
+## Decision
+
+Adopt the following boundary for review:
+
+1. **Kernel:** deterministic contracts and decisions: state machine, discovery,
+   WIP admission, delivery gates, eval scoring, cache/memory record contracts,
+   workflow scheduling, policy, preflight, coordination, resilience, status,
+   learning, model bindings, and metric projections. Kernel modules may use
+   Node standard library and other kernel contracts only.
+2. **Execution support:** local filesystem, Git/source snapshots, process or
+   Docker execution, event logs, evidence, run persistence, reconciliation,
+   and the CLI. It may depend on the kernel but does not define provider
+   semantics.
+3. **Adapters/plugins:** Doc Bridge, Orca, Linear/GitHub (or another tracker),
+   LLM providers, memory stores, MCP, and event bridges. They implement
+   generic contracts and own credentials/network side effects.
+4. **Composition:** `src/index.ts` and `src/cli.ts` compose the surfaces. A
+   consumer must not import private module paths as a supported API.
+5. **Fail-closed rule:** provider failure, missing evidence, stale source, or
+   ambiguous product decisions cannot be converted into a passing kernel
+   decision by an adapter.
+
+## Dependency constraints
+
+```text
+consumer -> composition -> execution support -> kernel
+consumer -> composition -> adapters -> kernel contracts
+kernel -> kernel / Node stdlib only
+```
+
+Type-only references between `context`, `plugins`, `events`, `runtime`, and
+`types` are allowed. `bundle` may call run reconciliation because signed
+evidence must be exported only from a reconciled terminal run. These are the
+only baseline exceptions; a new runtime import direction requires an ADR.
+
+## Human decisions required
+
+The following decisions are intentionally not inferred by this ADR:
+
+- approve the module classifications in `docs/MODULE-BOUNDARIES.md`;
+- approve `codex / gpt-5.6-luna / high` as the pilot's fixed provider/model
+  binding, or provide a replacement;
+- approve the proposed eval thresholds and three repetitions, or provide
+  different values;
+- provide or authorize a controlled no-Harness cohort and its task IDs;
+- decide whether future MCP/event-bridge adapters belong in this package or a
+  separate integration package once their contracts are specified.
+
+The architecture decision is accepted. H-040 still requires empirical baseline
+collection and verification evidence before it can be reported complete.
+
+## Consequences
+
+- Swapping Orca, a tracker, Doc Bridge, a model, or a memory backend does not
+  require changing kernel decisions.
+- External side effects stay auditable and testable through adapter contracts.
+- The kernel remains usable in a local process or Docker execution mode.
+- Provider-specific integration tests and evals are required before an adapter
+  can be described as production-ready.
+
+## Alternatives considered
+
+- **Provider logic in the kernel:** rejected; it couples decisions to vendors
+  and makes deterministic comparison impossible.
+- **A new abstraction layer for every capability:** rejected for now; one-file
+  capabilities stay in the existing capability-first layout until a second
+  implementation or boundary test requires a directory.

package/docs/GETTING-STARTED.md

@@ -0,0 +1,18 @@
+# Getting started
+
+Install the package, then run the included consumer example:
+
+```bash
+pnpm add -D @agentskit/harness
+pnpm build
+node examples/minimum-profile.mjs
+```
+
+The example uses a fake profile in YOLO mode, a coding-agent adapter, a local
+Doc Bridge index, adversarial code review, and a dry-run tracking adapter. It
+prints a structured result and never performs a network mutation.
+
+For a real project, keep phase decisions in the kernel, select a named profile,
+and provide integrations through adapters. Start with `mode: "dry-run"`, inspect
+the evidence, then move to `safe` or `yolo` only after the preflight contract is
+current.

package/docs/MODULE-BOUNDARIES.md

@@ -0,0 +1,143 @@
+# Module and boundary inventory (H-040)
+
+This document is the reviewed starting point for the 0.4.0 work. It describes
+the repository at revision `f4b2b092af97d528bd5fe5955ed38f101521b98d` (the
+`main` baseline captured on 2026-09-10) and is intentionally descriptive: it
+does not claim that the proposed 0.4.0 boundary has already been accepted.
+
+## Classification
+
+| Class | Meaning | Dependency rule |
+| --- | --- | --- |
+| Kernel | Deterministic contracts, state transitions, policy and metric projections | May use Node standard library and other kernel modules; must not import adapters, provider SDKs, CLI composition, or credentials. |
+| Execution support | Local process, filesystem, event, evidence, and run lifecycle plumbing | May depend on the kernel; must expose provenance and fail closed at trust boundaries. |
+| Adapter | Provider-specific or external-system integration | May depend on kernel contracts; must not be imported by kernel modules. |
+| Composition | Package and CLI entry points | May compose kernel, execution support, and adapters; consumers use `src/index.ts`. |
+
+## Complete source inventory
+
+Every current TypeScript module is listed below. Relative imports are the
+observed imports at the baseline revision; `stdlib` means Node's built-in
+modules, not a provider dependency.
+
+| Module | Class | Responsibility | Relative dependencies | External boundary |
+| --- | --- | --- | --- | --- |
+| `src/kernel/constants.ts` | Kernel | State, decision, and surface constants | `types` (type-only) | None |
+| `src/kernel/errors.ts` | Kernel | Typed fail-closed errors | None | None |
+| `src/kernel/hash.ts` | Kernel | SHA-256 and JSON digests | stdlib | None |
+| `src/kernel/types.ts` | Kernel | Shared contract, run, evidence, and metric types | `context` (type-only) | None |
+| `src/kernel/state-machine.ts` | Kernel | Legal lifecycle transitions and human decisions | `constants`, `types` | None |
+| `src/kernel/discovery.ts` | Kernel | Discovery freshness, ambiguity, and decision packets | `errors`, `hash` | None |
+| `src/kernel/wip.ts` | Kernel | WIP admission and capacity decisions | `errors` | None |
+| `src/kernel/experiment.ts` | Kernel | Comparable runtime/provider selection | `errors` | None |
+| `src/delivery/index.ts` | Delivery | G2–G5 delivery gates and deterministic PR projection | `errors`, `hash` | None |
+| `src/delivery/review.ts` | Delivery | Bounded parallel adversarial review lenses and evidence verdicts | `errors`, `hash`, `workflow`, `delivery/index` (type-only) | Reviewer callback supplied by caller |
+| `src/kernel/cycle.ts` | Kernel | Bounded improvement-cycle assessment | stdlib, `errors` | None |
+| `src/kernel/eval.ts` | Kernel | Versioned eval manifest validation, deterministic battery runner, min/median/max aggregation, and fail-closed assessment | `errors`, `hash` | Grader callback supplied by caller |
+| `src/kernel/compatibility.ts` | Kernel | Pinned AgentsKit component manifest and evidence-bound compatibility assessment | `errors`, `hash` | Upstream commands and reports supplied by caller |
+| `src/kernel/cache.ts` | Kernel | Safe cache keys and in-memory LLM cache contract | `hash`, `errors` | Cache backend supplied by caller |
+| `src/kernel/optimization.ts` | Kernel | Token, memory, cache, parallelism comparisons | `hash`, `errors` | None |
+| `src/kernel/memory.ts` | Kernel | Memory record validation and memory adapter contract | `errors` | KV store supplied by caller |
+| `src/kernel/policy.ts` | Kernel | Tool/action policy gate | `errors` | None |
+| `src/kernel/preflight.ts` | Kernel | File-scoped checks and safe-command validation | stdlib, `errors` | Shell command is data, never executed here |
+| `src/kernel/block.ts` | Kernel | Portable execution block manifest and dependency admission | `errors`, `hash` | None |
+| `src/kernel/learning.ts` | Kernel | Retrospective parsing and human learning promotion | stdlib, `errors` | None |
+| `src/kernel/status.ts` | Kernel | Deterministic status snapshot and digest | `errors`, `hash`, `block`, `types` (type-only) | None |
+| `src/kernel/model-policy.ts` | Kernel | Role-to-model binding and validation | `errors`, `hash` | Provider is data, not an SDK |
+| `src/execution/machine.ts` | Execution support | Machine sampling and adaptive concurrency | stdlib, `types`, `errors` | Host CPU/memory metrics |
+| `src/execution/coordination.ts` | Execution support | Atomic issue/worktree claims and dispatch ledger | stdlib, `errors`, `hash` | Local state directory only |
+| `src/kernel/resilience.ts` | Kernel | Failure classification and bounded retry/recovery policy | `errors` | Operation callback supplied by caller |
+| `src/kernel/workflow.ts` | Kernel | Bounded workflow scheduling | `errors` | Node callbacks supplied by caller |
+| `src/kernel/phase-executor.ts` | Kernel | Declarative phase routing, preflight, effect policy, and bounded decisions | `errors`, `workflow` | Phase handlers, gates, and Grill-me callback supplied by caller |
+| `src/kernel/artifacts.ts` | Kernel support | Versioned provenance-bound artifacts, Markdown rendering, and idempotent phase resume projection | stdlib, `errors`, `hash`, `events`, `phase-executor` (type-only) | Local state directory only |
+| `src/kernel/adapter-contract.ts` | Kernel | Shared assurance levels and bounded telemetry contract | `errors` | Provider measurements supplied by adapters |
+| `src/kernel/quality.ts` | Kernel | Phase telemetry validation, 0–100 quality matrix, baseline deltas, and watchdog blockers | `errors`, `hash` | Metrics supplied by phases/adapters |
+| `src/kernel/pilot.ts` | Kernel | Cohort freeze and pilot assessment | `errors`, `hash` | None |
+| `src/kernel/plugins.ts` | Kernel | Generic slots, dependency checks, and lifecycle listeners | `errors`, `events` (type-only) | Plugin implementation supplied by caller |
+| `src/context/index.ts` | Context | Context snapshot contract, hashing, and provider slot | stdlib, `plugins`, `hash`, `errors` | Provider implementation supplied by caller |
+| `src/execution/metrics.ts` | Execution support | Benchmark manifest validation, run projection, and comparison | stdlib, `errors`, `files`, `types` | Reads local state only |
+| `src/execution/config.ts` | Execution support | Contract loading, profile resolution, and config hashing | stdlib, `constants`, `profiles`, `errors`, `hash`, `files`, `types` | Local `.codex/verification.json` |
+| `src/profiles/index.ts` | Profiles | Profile defaults and overrides | `errors` | None |
+| `src/execution/files.ts` | Execution support | Run/config JSON and task-artifact filesystem helpers | stdlib, `errors`, `types` | Local filesystem |
+| `src/execution/source.ts` | Execution support | Git/source snapshot and dirty-tree detection | stdlib, `hash`, `errors`, `types` | Git CLI |
+| `src/execution/runs.ts` | Execution support | Run persistence and lifecycle event creation | `hash`, `files`, `events`, `context`, `types` | Local state directory |
+| `src/execution/verification.ts` | Execution support | Plan/start/verify/reconcile/approval orchestration | stdlib, `runs`, `config`, `errors`, `evidence`, `state-machine`, `source`, `files`, `context`, `hash`, `types`, `events`, `machine` | Configured check commands and local processes |
+| `src/kernel/events.ts` | Kernel support | Event contracts, append-only log, hash chain, and lock recovery | stdlib, `errors`, `hash`, `context` (type-only), `types` (type-only), `runtime` (type-only) | Local filesystem |
+| `src/execution/evidence.ts` | Execution support | Structured evidence parsing and artifact validation | stdlib, `hash`, `files`, `types` | Check output and local artifacts |
+| `src/execution/bundle.ts` | Execution support | Signed evidence bundle export and verification | stdlib, `errors`, `files`, `hash`, `verification`, `events`, `config`, `types` | Local keys and files |
+| `src/execution/agent.ts` | Execution support | Agent session recorder, resume, and tool lifecycle | stdlib, `events`, `errors`, `policy`, `runtime`, `types` | Agent/runtime callbacks |
+| `src/execution/runtime.ts` | Execution support | Process, Docker, and generic tool runtimes | stdlib, `hash`, `errors`, `types` | Child process and Docker CLI |
+| `src/cli.ts` | Composition | `ak-harness` / `ak-verify` command surface | `index`, `metrics`, `errors`, `events`, stdlib, `commander` | Shell/CLI invocation |
+| `src/index.ts` | Composition | Supported package entry point | All supported public modules | Consumer import boundary |
+| `src/adapters/doc-bridge.ts` | Adapter | Deterministic Doc Bridge context provider | stdlib, `hash`, `context` | `.doc-bridge/index.json` |
+| `src/adapters/agent.ts` | Adapter | Structured coding-agent execution with bounded timeout and failure classification | `errors`, `resilience`, `adapter-contract` | Agent/provider callback supplied by caller |
+| `src/adapters/orca.ts` | Adapter | Safe, idempotent Orca dispatch plan | `errors`, `hash`, `preflight` | Orca CLI arguments; no execution |
+| `src/adapters/tracking.ts` | Adapter | Idempotent provider-neutral tracking transition | `errors`, `hash` | User-supplied Linear/GitHub/etc. handler |
+
+## Allowed dependency directions and exceptions
+
+```text
+consumer -> src/index.ts -> composition
+                         -> execution support -> kernel
+                         -> adapters -> kernel
+kernel -----------------> kernel (or Node stdlib)
+```
+
+The following are intentional exceptions and are type-only or composition
+edges, not provider leakage:
+
+1. `context.ts` uses the generic plugin slot from `plugins.ts`; the provider
+   implementation remains outside the kernel.
+2. `plugins.ts` references event types and `events.ts` references context and
+   runtime types only. These are compile-time contracts, not runtime cycles.
+3. `cli.ts` imports from `index.ts` so the CLI exercises the supported public
+   surface rather than private implementation paths.
+4. `bundle.ts` calls reconciliation because a bundle is only exportable from a
+   reconciled terminal run; this is a local execution-support dependency.
+5. `runtime.ts` contains process/Docker mechanics because those are execution
+   providers. Kernel decisions receive runtime evidence as data and do not
+   import the runtime implementation.
+
+Any new external provider (Linear, GitHub, Orca, Doc Bridge, MCP, event bridge,
+LLM, or memory backend) must enter through an adapter or plugin slot. A new
+provider import in a kernel module is a boundary violation and requires an ADR.
+
+## Public entry point inventory
+
+`src/index.ts` is the only supported consumer entry point. Its named exports
+are grouped below; the source file remains authoritative for exact signatures.
+
+| Area | Named exports |
+| --- | --- |
+| Lifecycle/config | `STATES`, `LEGAL_TRANSITIONS`, `HarnessError`, `loadConfig`, `validateConfig`, `transition`, `assertHuman`, `approvedDecision`, `loadLatestRun`, `planRun`, `startRun`, `verifyRun`, `reconcileRun`, `approveRun`, `authorizeRun`, `retryRun`, `cancelRun`, `cleanTaskArtifacts` |
+| Events/plugins/context | `EVENT_LOG_GENESIS`, `FileEventStore`, `HARNESS_EVENT_SCHEMA_VERSION`, `HARNESS_EVENT_TYPES`, `inspectEventLogLock`, `recoverEventLogLock`, `createPluginRegistry`, `createPluginSlot`, `HARNESS_PLUGIN_API_VERSION`, `CONTEXT_PROVIDER_SLOT`, `hashContextSnapshot`, `hashContextSnapshots`, `readContextSnapshots`, `validateContextSnapshot`, `validateContextSnapshots` |
+| Discovery and delivery | `assessDiscovery`, `isDiscoveryCurrent`, `assessWip`, `WIP_STATES`, `selectRuntime`, `assessAcceptance`, `assessIntegration`, `assessPreflight`, `assessProduction`, `assessWorktreeCleanup`, `composePullRequest`, `assessPilot`, `IMPROVEMENT_CYCLE_STEPS`, `assessImprovementCycle` |
+| Eval and optimization | `assessAgentEval`, `runAgentEval`, `createLlmCache`, `createLlmCacheKey`, `validateCacheableOperation`, `compareOptimization`, `validateOptimizationObservation`, `MEMORY_SCOPES`, `createInMemoryMemoryAdapter`, `createKvMemoryAdapter`, `validateMemoryRecord`, `runWorkflow`, `BENCHMARK_SCHEMA_VERSION`, `benchmarkRuns`, `loadBenchmarkManifest`, `recordBenchmarkObservation`, `validateBenchmarkManifest` |
+| Agent/runtime controls | `createSessionRecorder`, `createCodingAgentAdapter`, `createPolicyGate`, `createConfiguredToolRuntime`, `createDockerToolRuntime`, `createProcessToolRuntime`, `createToolRuntime`, `adaptiveConcurrency`, `createMachineMonitor`, `sampleMachine`, `summarizeMachine`, `createDispatchLedger`, `classifyFailure`, `recoveryDelayMs`, `runWithRecovery`, `planFilePreflight`, `validateSafeCommand`, `BLOCK_STATUSES`, `assessBlock`, `validateBlockManifest`, `LEARNING_STATUSES`, `parseRetro`, `promoteLearnings`, `createStatusSnapshot`, `validateStatusSnapshot`, `MODEL_ROLES`, `createModelPolicy`, `modelFor`, `PHASE_MODES`, `createPhaseProfile`, `planPhaseProfile`, `executePhaseProfile`, `ARTIFACT_SCHEMA_VERSION`, `createArtifactEnvelope`, `FileArtifactStore`, `artifactIsFresh`, `resumeStateFromArtifacts`, `ASSURANCE_LEVELS`, `validateAdapterMetadata` |
+| Integrations and evidence | `createDocBridgeContextProvider`, `createOrcaDispatchPlan`, `createTrackingAdapter`, `createTrackingTransition`, `EVIDENCE_BUNDLE_SCHEMA_VERSION`, `exportEvidenceBundle`, `readEvidenceTrustStore`, `verifyEvidenceBundle` |
+
+The entry point also re-exports the public type surfaces from `types`,
+`events`, `plugins`, `context`, `discovery`, `wip`, `experiment`, `delivery`,
+`pilot`, `cycle`, `metrics`, `agent`, `policy`, `runtime`, `bundle`, and
+`machine`, `phase-executor`, `artifacts`, plus explicit type exports for cache, optimization, memory,
+coordination, resilience, preflight, block, learning, status, model policy,
+Orca, and tracking. No adapter implementation is re-exported wholesale.
+
+## External integration inventory
+
+| Integration | Current location | Side effects | 0.4.0 boundary |
+| --- | --- | --- | --- |
+| Doc Bridge | `src/adapters/doc-bridge.ts` | Reads a local index | Keep behind `ContextProvider`; measure context hit/quality separately. |
+| Orca | `src/adapters/orca.ts` | None; produces argv and lifecycle projections only | Keep lease/worktree/issue-lock/SHA planning provider-neutral; execution belongs to the orchestrator. |
+| Linear/GitHub/other tracker | `src/adapters/tracking.ts` callback | Caller-owned network mutation | Require idempotency key and explicit tracking authorization. |
+| Process runtime | `src/execution/runtime.ts` | Starts child processes | Execution support; policy and evidence gates remain kernel decisions. |
+| Docker runtime | `src/execution/runtime.ts` | Starts Docker containers | Optional sandbox selected by config, never a mandatory kernel dependency. |
+| LLM provider/model | Caller/plugin | Provider call and token spend | Bind provider/model in experiment metadata; do not embed SDKs in kernel. |
+| Memory backend | Caller/plugin; `memory.ts` contract | Backend reads/writes | Keep record validation in kernel; backend adapter owns persistence. |
+| MCP/event bridge | Not implemented | Future network/event effects | Add as adapters only after a separate ADR and eval coverage. |
+
+## Review status
+
+This inventory is evidence for H-040. ADR-0026 records the accepted boundary;
+the remaining H-040 work is empirical baseline collection and verification
+evidence, not an unresolved architecture choice.

package/docs/ORGANIZATION.md

@@ -9,10 +9,17 @@ the repository stays navigable without speculative layers.
 ├── src/
 │   ├── index.ts          # supported package API
 │   ├── cli.ts            # ak-harness / ak-verify commands
-│   ├── adapters/         # optional integrations
-│   └── <capability>.ts   # contract, evidence, delivery, runtime, metrics...
+│   ├── kernel/           # deterministic contracts and decisions
+│   ├── execution/        # filesystem, runtime, evidence, and run plumbing
+│   ├── context/          # context contracts and provider slot
+│   ├── delivery/         # delivery gates and PR projection
+│   ├── profiles/         # configuration profiles
+│   └── adapters/         # optional integrations
 ├── test/                 # deterministic tests and fixtures
 ├── scripts/              # real CLI, packaging, and repository checks
+├── capabilities/         # generated public-surface capability manifest
+├── examples/              # runnable consumer examples
+├── compatibility/         # pinned ecosystem manifest and migration/rollback procedures
 ├── docs/                 # ADRs and this organization contract
 ├── .codex/               # verification contract and local run state
 └── .github/              # CI and release workflows
@@ -22,8 +29,10 @@ the repository stays navigable without speculative layers.
 
 - Import internal modules with explicit relative paths; only `src/index.ts`
   is supported for consumers.
-- Add a directory when a capability has multiple cohesive modules. Do not add
-  a layer for one file.
+- Keep deterministic decisions in `kernel/`; execution mechanics and external
+  effects live behind the other capability boundaries.
+- A single-file capability may use an `index.ts` boundary when it has a
+  distinct public contract; do not add speculative layers.
 - Adapters may depend on the kernel; the kernel must not depend on adapters or
   external providers.
 - Tests may use internal modules when exercising a boundary, but consumer

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,24 @@
+# Troubleshooting
+
+## `STALE`
+
+The source, contract, or context changed after verification. Run `ak-verify`
+again; do not reuse the old evidence bundle.
+
+## `BLOCKED` or `AWAITING_HUMAN_APPROVAL`
+
+Inspect the structured run with `ak-harness status --json`. Resolve the listed
+ambiguity, failed gate, missing evidence, or approval, then rerun verification.
+YOLO only removes unnecessary pauses; it does not bypass a required safety or
+provenance gate.
+
+## Missing adapter telemetry
+
+Return `status: "unknown"` for measurements you cannot observe. Unknown values
+are excluded from improvement claims and can block a configured quality gate.
+
+## Runtime failures
+
+Use the process runtime for a local shell-free boundary or the Docker runtime
+when isolation is required. Both report timeout, cancellation, output-limit,
+and non-zero-exit failures as structured evidence.

package/examples/minimum-profile.mjs

@@ -0,0 +1,27 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  createCodingAgentAdapter,
+  createDocBridgeContextProvider,
+  createPhaseProfile,
+  createTrackingAdapter,
+  executePhaseProfile,
+  runAdversarialReview,
+} from '../dist/index.js'
+
+const root = mkdtempSync(join(tmpdir(), 'agentskit-harness-example-'))
+try {
+  writeFileSync(join(root, '.doc-bridge.json'), JSON.stringify({ contentHash: 'example', knowledge: [{ id: 'guide', title: 'Guide', path: 'guide.md', body: 'approved workflow' }] }))
+  const profile = createPhaseProfile({ id: 'minimum', mode: 'yolo', phases: [{ id: 'implement', effect: 'write', outputs: ['result'] }], maxConcurrency: 1 })
+  const agent = createCodingAgentAdapter({ id: 'fake-agent', version: '1.0.0', execute: () => ({ output: { ok: true }, diff: '', usage: { status: 'measured', inputTokens: 1, outputTokens: 1, totalTokens: 2 } }) })
+  const tracking = createTrackingAdapter('fake-tracker', () => undefined, { dryRun: true })
+  const docs = createDocBridgeContextProvider({ root, indexPath: '.doc-bridge.json' })
+  const review = await runAdversarialReview({ lenses: [{ id: 'contract' }], binding: { candidateRevision: 'example', contractHash: 'contract', configHash: 'config' }, reviewer: () => ({ status: 'pass', evidence: 'example-review' }) })
+  const transition = await tracking.transition({ tracker: 'fake', issue: 'EXAMPLE-1', to: 'qa', reason: 'example' })
+  const context = await docs.resolve({ query: 'approved' })
+  const execution = await executePhaseProfile(profile, { preflight: () => ({ decision: 'pass' }), handlers: { implement: () => ({ decision: 'pass', outputs: { result: 'ok' } }) } })
+  console.log(JSON.stringify({ status: 'passed', profile: execution.status, agent: agent.id, review: review.decision, tracking: transition.to, contextReferences: context.references.length }))
+} finally {
+  rmSync(root, { recursive: true, force: true })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/harness",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Portable, evidence-backed development harness for coding agents.",
   "type": "module",
   "bin": { "ak-harness": "dist/cli.js", "ak-verify": "dist/cli.js" },
@@ -12,7 +12,7 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md", "MANIFESTO.md", "LICENSE", "docs"],
+  "files": ["dist", "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md", "MANIFESTO.md", "LICENSE", "docs", "capabilities", "examples", "compatibility", "release"],
   "engines": { "node": ">=22" },
   "scripts": {
     "build": "tsup && node -e \"console.log(JSON.stringify({status:'passed',criteria:['package']}))\"",
@@ -43,6 +43,17 @@
     "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: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']}))\"",

package/release/manifest.json

@@ -0,0 +1,14 @@
+{
+  "type": "agentskit-harness-release-manifest",
+  "schemaVersion": 1,
+  "package": "@agentskit/harness",
+  "version": "0.4.0",
+  "channel": "latest",
+  "sourceRevision": "PENDING_PR_MERGE_SHA",
+  "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", "published-registry-smoke"],
+  "nextBaseline": "benchmarks/harness-0.4.0-baseline.json",
+  "digest": "0661969c719964eae2a2ab5b7bddd8b108e8792bb51d4a27c223474430730158"
+}

package/release/notes.md

@@ -0,0 +1,10 @@
+# 0.4.0 release candidate
+
+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 candidate is not publishable until the pinned upstream AgentsKit tests/evals
+and the post-publication registry/consumer smoke produce current evidence.

package/release/qualification.json

@@ -0,0 +1,14 @@
+{
+  "type": "agentskit-harness-release-qualification",
+  "schemaVersion": 1,
+  "package": "@agentskit/harness",
+  "version": "0.4.0",
+  "sourceRevision": "a18b57d43f037b7a34b134e01baf913ae2341fd7",
+  "status": "blocked",
+  "harnessVerification": { "runId": "1789063362018-21016-775q93", "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": "pending-publication", "reason": "Run only after the main Trusted Publishing workflow succeeds." },
+  "publishable": false,
+  "blockers": ["ecosystem-compatibility", "pilot-benchmark", "published-registry-smoke"]
+}