Skill: web-build-artifact-evidence

Purpose

Define an evidence-first pattern for web Task Packs that claim a build (or packaging) contract.

This skill ensures that “build succeeded” is proven via:

•deterministic, local commands, and
•small, reviewable artifacts stored under the Task Pack artifacts/ directory.

This is contract-safe and does not change orchestrator behavior.

When to use

Use this skill when a Task Pack:

•introduces or changes a web build pipeline,
•needs to prove “we can build/package this project,”
•must provide human-reviewable evidence in PR artifacts.

Common examples:

•frontend build (npm run build)
•server build/package (python -m build)
•static export or bundle step

When NOT to use

Do not use this skill to:

•store large binary artifacts in the repo or taskpack artifacts directory
•introduce deployment outputs (containers, images, published packages)
•depend on network access during acceptance unless explicitly allowed by constraints
•treat logs as the only evidence (logs are helpful but not sufficient)

Contract framing

A “build artifact contract” in this system means:

•Acceptance runs a local build command successfully
•The Task Pack emits a small evidence file that summarizes the result
•The evidence file is stable enough to validate in CI and review in PRs

The evidence is not the build output itself — it is a contract record.

Evidence artifact layout

For Task Packs with build evidence, use:

txt

taskpacks/<TASK-ID>-<slug>/
├── artifacts/
│ ├── README.md
│ └── build-contract.txt

`artifacts/README.md` should include

•What contract is being proven
•What commands were run (names, not full logs)
•What files are evidence
•Any known limitations (e.g., “does not validate deploy”)

`build-contract.txt` should include

Keep it short and grep-friendly:

•Project identifier (if relevant)
•Build command executed
•Toolchain versions (where easy)
•Output summary (high-level)
•Optional: a small, stable fingerprint

Avoid:

•full build logs
•megabytes of console output
•environment-specific paths that cause churn

Evidence content guidelines

Recommended fields (example)

•contract: human-readable identifier
•cmd: exact command used
•status: success
•tool_versions: key tools only
•outputs: brief list of produced directories/files (names only)
•notes: optional, short

Stable fingerprint (optional)

If you need a “deterministic” marker, prefer:

•hash of a small manifest file generated by the build (if stable), or
•version string + command + target, rather than hashing a full dist directory.

Do not:

•hash large directories
•hash files that include timestamps or non-deterministic bundling output

How to generate evidence (pattern)

Pattern A: command output redirected to evidence file

Good when output is small and stable.

Example:

•npm run build > taskpacks/<TASK-ID>/artifacts/build-contract.txt

Only use if output is not noisy.

Pattern B: curated summary (recommended)

Run build normally, then write a curated summary file.

Example approach:

•run build
•capture tool versions
•list output directory names
•write a small build-contract.txt

This produces stable, reviewable evidence.

Minimal example: build-contract.txt

Example (text-only):

txt

contract: web build proof
cmd: npm run build
status: success
tool_versions: node=v20.x npm=10.x
outputs: dist/ .next/ (as applicable)
notes: evidence file only; does not include full build output

Keep this file under ~2–10 KB.

Acceptance integration

If the Task Pack claims build evidence, acceptance should include:

•the build command
•(optionally) a follow-up command that verifies the evidence file exists or is non-empty

Example acceptance excerpt (conceptual):

•build step succeeds
•artifact presence is validated by existing acceptance checks

Do not add new orchestrator logic. Evidence is validated using:

•existing acceptance commands, and/or
•existing artifact validators.

Common failure modes and fixes

Evidence file is too large / unstable

Symptom: PR churn, huge diffs, CI flakiness
Fix: curate a summary file; avoid full logs

Artifact includes machine-specific paths

Symptom: different output per OS/user path
Fix: remove absolute paths; only include stable names

Build output is non-deterministic

Symptom: hashes change per run
Fix: avoid hashing outputs; record versions + command + target instead

“Evidence” is only a screenshot or manual note

Symptom: not machine-checkable
Fix: store textual contract evidence under artifacts/

Non-goals

•Publishing packages
•Deploying builds
•Producing or storing large build outputs
•Introducing new validation tooling or orchestrator behavior
•Requiring plugins