Prepare a task evidence upload

Traceability

• Spec ID: task-evidence-upload
• Status: Implemented
• Extended by: 2026-09-01-task-evidence-upload-end-to-end, which adds upload apply, a verifiable receipt, and a local destination. The input, packet, and plan contracts below are unchanged, and preparing a plan still performs no network request.

Intent

Give a developer an explicit, reviewable local step for preparing task evidence before any organization service receives it. The command must turn a bounded task description, validation observations, and Skill/MCP usage observations into a versioned evidence packet and upload plan while preserving uncertainty and excluding high-risk raw data by default.

This is the first vertical slice between the local Builder Harness and a future Team/Org control plane. It establishes the local evidence contract and consent boundary without implying that a remote service, authentication flow, or upload receipt already exists.

Acceptance Scenarios

• AC-1 — Safe command discovery: better-harness upload, better-harness upload --help, and better-harness upload plan --help explain the local planning workflow without reading task inputs, writing files, or making network requests.
• AC-2 — Local plan preparation: Given a valid task evidence input, destination URL, organization identifier, and workspace, upload plan produces a better-harness.task-evidence-packet/v1 inside a better-harness.task-evidence-upload-plan/v1. The command performs no network request and labels the plan as prepared rather than uploaded.
• AC-3 — Allowlisted and redacted evidence: The input validator rejects unknown fields and unsupported enum values. The packet contains only the documented task, acceptance, asset-usage, and observation fields. Workspace and home paths plus common credential forms are redacted from accepted string values. Raw source bodies, prompts, transcripts, tool inputs, tool outputs, credentials, and absolute paths are named as excluded evidence classes.
• AC-4 — Honest observation state: Asset identity match states (exact, ambiguous, unresolved), execution stages, outcomes, and acceptance/validation states retain failed and unobserved values instead of being normalized into success.
• AC-5 — Reviewable integrity: The packet and plan use canonical JSON for SHA-256 digests and byte counts. A validator accepts an unchanged plan and rejects a plan whose packet or digest-bearing content was changed.
• AC-6 — Explicit local write: Without --out, the command only previews the plan. With --out, it atomically writes one JSON artifact and reports that local write. Human output and --json output both state that no network request was made.
• AC-7 — Root CLI ownership: The root CLI discovers upload as a workflow command and delegates plan to a business-named capability owner. The later end-to-end extension registers apply explicitly; every other unknown subcommand fails closed rather than performing a best-effort action.
• AC-8 — Portable behavior: Path handling, output creation, and command invocation use Node APIs and behave consistently for Windows, macOS, and Linux path semantics covered by focused tests.

Input and Output Contract

The local input is a strict JSON document with this identity:

{
  "kind": "better-harness.task-evidence-input",
  "schemaVersion": 1
}

It may contain only these evidence families:

• task: a stable task id, title, intent, scope, non-goals, and acceptance observations;
• assets: Skill, MCP, tool, hook, plugin, or Agent identities plus revision, identity-match state, observed execution stage, and outcome;
• observations: bounded validation, human-review, artifact, change, or runtime summaries with an optional non-path evidence reference.

The command output is an upload plan that embeds the allowlisted packet, destination metadata, integrity metadata, the redaction/exclusion summary, and the explicit effect state network: none. An output plan is not an upload receipt and must not be interpreted as evidence that an organization service accepted the packet.

Non-goals

Scoped to this slice. The first item was lifted by 2026-09-01-task-evidence-upload-end-to-end; the rest still hold.

• Sending network requests, implementing upload apply, or issuing remote receipts.
• Designing authentication, tenancy storage, RBAC, policy evaluation, approval workflows, dashboards, or the Team/Org service deployment.
• Automatically collecting source code, prompts, transcripts, tool request or response bodies, environment variables, credentials, or full filesystem paths.
• Changing Harness Studio UI, package boundaries, release metadata, or published package versions.
• Claiming that a configured, discovered, or selected Skill/MCP was successfully executed or that a failed task was caused by a particular asset.

Plan and Tasks

1. Add a scripts/task-evidence-upload/ capability owner with strict input and packet schemas, canonical serialization, redaction, digest calculation, plan validation, and atomic local persistence.
2. Add a side-effect-free capability CLI for plan, including human help, human preview, a single-document JSON result, stable usage errors, and an injectable clock for behavior tests.
3. Register upload plan in the root CLI as a workflow command while keeping the root dispatcher free of evidence-domain logic.
4. Add focused behavior tests for strict validation, redaction, uncertainty, tamper detection, explicit writes, root dispatch, and no-network help/preview.
5. Run the repository CLI and documentation-link checks, then perform a Review Readiness Check against this spec and the local diff.

The capability remains outside packages/harness-studio: Studio is a local workbench consumer, while preparation of portable task evidence is a CLI/domain boundary that can later be consumed by Studio or a separately deployed control plane without coupling their release lifecycles.

Test and Review Evidence

• AC-1, AC-6, AC-7: run the focused task-evidence upload CLI tests and the root CLI test suite; inspect help, preview, JSON, explicit-write, and unknown subcommand results.
• AC-2, AC-3, AC-4: construct valid and invalid fixtures, assert parsed object shapes and enum behavior, and assert that fixture secrets and native absolute paths are absent from serialized packets.
• AC-5: validate a generated plan, mutate packet content and digest-bearing metadata independently, and assert deterministic rejection.
• AC-8: exercise POSIX and Windows-style path values through the sanitizer and use temporary directories plus Node filesystem APIs for write behavior.
• Run npx vitest run test/cli/task-evidence-upload.test.mjs.
• Run npx vitest run test/cli/better-harness-cli.test.mjs.
• Run npx vitest run test/skills-docs/doc-link-graph.test.mjs.
• Run npm test if the focused suites expose shared-surface risk or before the change is proposed for merge.

Risk review must verify that serialized plans contain no fixture secret or full workspace/home path, that --help and preview mode do not write, and that no code path in this slice opens a network connection. The spec status may move to Implemented only after the mapped local evidence passes.

Observed local evidence

• npx vitest run test/cli/task-evidence-upload.test.mjs: 10 tests passed, covering AC-1 through AC-8.
• npx vitest run test/cli/better-harness-cli.test.mjs: 50 root CLI tests passed after registering the workflow command.
• npx vitest run test/skills-docs/doc-link-graph.test.mjs: 8 documentation link and routing tests passed.
• npx vitest run test/governance/scripts-refactor-contract.test.mjs test/cli/task-evidence-upload.test.mjs: 17 tests passed after review of the intentional root help, command inventory, and OpenCLI baseline changes.
• npm test: 109 test files passed; 1,629 tests passed and 2 were skipped.
• npm run pack:verify: the npm package and runtime bundle manifests passed, including the newly registered capability owner.
• git diff --check: passed. A bounded source scan found no Node network module, fetch, XHR, or WebSocket use under scripts/task-evidence-upload/.

These are local source/package checks. No remote Team/Org service, CI run, Windows runner, upload attempt, or receipt was observed or claimed.