Agent Acceptance

An evidence-backed acceptance framework for work delivered by coding agents. It turns a vague goal into declared artifacts, executable checks, independent verification, and reports that explain exactly why a delivery passed or failed.

It is provider-neutral, has no runtime dependencies, and works offline. Command checks use argument arrays with no shell, stay inside the selected project root, and run only when --execute-commands is explicitly supplied.

Why use it

Agent output can look complete while missing a build artifact, test, required string, or independently reproducible proof. Agent Acceptance makes those expectations executable:

• every task declares a concrete goal;
• every artifact has a relative path, expected kind, and optional minimum size or SHA-256;
• every check is bound to one or more declared artifacts;
• every manifest includes at least one check marked independent;
• missing files, mismatched JSON, absent content, command failures, and timeouts get specific reasons;
• exit code 2 blocks CI when acceptance fails;
• deterministic JSON and concise Markdown reports support automation and human review.

Quick start

Requires Node.js 20 or newer.

npm install
npm run check:example

The example checks four artifacts, required text, two JSON values, and an independent command. Reports are written to reports/example.json and reports/example.md.

Use it on a project:

node ./bin/agent-acceptance.js check \
  --manifest ./acceptance.json \
  --root . \
  --execute-commands \
  --json ./reports/acceptance.json \
  --markdown ./reports/acceptance.md

Exit codes are 0 for accepted, 2 for valid checks that failed, and 1 for an invalid manifest or usage error.

Manifest format

{
  "schemaVersion": 1,
  "task": {
    "id": "release-homepage",
    "title": "Release homepage",
    "goal": "Build a deployable page with independently verified content"
  },
  "artifacts": [
    {
      "id": "web-build",
      "description": "Generated deployable page",
      "path": "dist/index.html",
      "kind": "file",
      "minBytes": 80
    }
  ],
  "checks": [
    {
      "id": "build-present",
      "title": "Independent build artifact inspection",
      "type": "artifact_exists",
      "verification": "independent",
      "artifactIds": ["web-build"]
    }
  ]
}

Artifact paths, command executables, and command working directories must remain inside the project root when they are path-based. Real paths are checked as well, and symbolic links are rejected as evidence, so a parent link cannot silently redirect verification outside that boundary.

Check types

• artifact_exists: verifies file/directory kind, minimum bytes, and optional SHA-256.
• file_contains: requires one file artifact and a non-empty contains string list.
• json_match: compares an exact JSON value at an RFC 6901-style pointer.
• command: executes a reviewed argv array without a shell and enforces a timeout of at most five minutes.

Command output is capped before it enters the JSON report. Manifests do not run commands unless the CLI receives --execute-commands; treat third-party manifests as untrusted until reviewed.

Templates

• templates/web.acceptance.json covers a package manifest, source landmark, production build command, and independent build artifact inspection.
• templates/script.acceptance.json covers the implementation, automated test artifact, and an independent test command.

Copy the closest template to the target project as acceptance.json, then replace the task, paths, commands, and criteria with the project's actual contract.

CLI

Validate structure without touching artifacts or running commands:

node ./bin/agent-acceptance.js validate --manifest acceptance.json

Run non-command checks only:

node ./bin/agent-acceptance.js check --manifest acceptance.json

Run the reviewed command checks as well:

node ./bin/agent-acceptance.js check --manifest acceptance.json --execute-commands

Development

npm test
npm run check:example

Tests cover both templates, passing and failing deliveries, artifact-specific reasons, explicit command approval, root escape protection, orphan artifacts, timeouts, CLI exit codes, and JSON/Markdown reports.

License

MIT