Build Project Harness

Build Project Harness

Build a project-specific verification entrypoint without replacing native test or build systems. Separate evidence-producing checks from hardware, proprietary, or visual claims that require an explicit prerequisite or human decision.

Workflow

1. Resolve the target project and requested harness tasks from the request, repository instructions, source boundaries, and current working-tree state. Do not assume that the current directory or every detected source tree is in scope.
2. Run scripts/inspect_project.py read-only against the target. Put --output in the system temporary directory, not the project. Do not import project code or execute discovered project commands during inspection.
3. Read references/harness-contract.md every time. Read only the stack references supported by inspection evidence:
   • Read references/python-patterns.md for Python or pytest.
   • Read references/embedded-patterns.md for firmware, native builds, proprietary toolchains, serial devices, or HIL.
   • Read references/document-patterns.md for document, PDF, Office, rendering, or visual checks.
   • Read references/github-actions-patterns.md only when CI or GitHub Actions is in scope.
4. Ask one material question at a time when the answer changes scope, commands, dependencies, writes, or safety. Continue with evidence-backed choices when no material ambiguity remains.
5. Propose the harness before editing. Name its tiers, files, exact commands, prerequisites, allowed writes, expected results, and manual or HIL limits. Preserve native runners and explain how the harness delegates to them.
6. Wait for explicit approval of the proposal. Do not treat a request to inspect, discuss, or diagnose as approval to create files.
7. Preview every addition and modification, existing-file conflict, and ignore-rule change. Stop and ask again if the preview reveals a material conflict or scope expansion.
8. Implement the approved design. Adapt the templates under assets/harness-template/; replace every token and keep generated reports out of version control. Do not leave template markers in the project harness.
9. Run scripts/validate_harness.py <target> and fix contract errors. Then execute every safe required check whose prerequisites are available. Do not execute unsafe, hardware-dependent, proprietary, destructive, or externally mutating checks without the necessary approval and environment.
10. Report each check as PASS, FAIL, SKIP, or BLOCKED under the contract. Name changed files, commands run, passed and failed checks, skipped hardware or optional checks, blockers, and remaining ambiguity. Do not commit or push unless separately requested.

Proposal shape

Present a compact plan containing:

• target and source boundaries;
• harness files to add or modify;
• check ID, tier, native command, prerequisite, timeout, allowed writes, and success criterion;
• local runner command and, when requested, the identical command CI will call;
• report locations and ignore changes;
• checks requiring hardware, licenses, network access, flashing, serial access, rendering, or human approval.

Prefer the smallest useful set of tiers. Do not invent a build, artifact, or HIL claim merely to fill every tier.

Safety rules

• Preserve repository instructions, dirty user work, native runners, and source-of-truth boundaries.
• Keep inspection read-only and place smoke-test or render output in a system temporary directory unless an approved manifest names another allowed write.
• Do not install dependencies, change lockfiles, edit global configuration, start services, access secrets, or make network changes without explicit approval.
• Do not flash devices, change addresses or fuses, open serial ports, energize hardware, or run HIL automatically. Treat HIL as opt-in even when hardware appears connected.
• Do not call a static inspection a build, a package check a render, or an automated render a human visual approval.
• Do not hide missing hardware, licenses, tools, or credentials behind passing wrappers. Record the affected check as SKIP or BLOCKED according to the contract.
• Do not overwrite an existing harness or broaden ignore rules without showing the conflict and receiving approval.
• Do not commit, push, open a pull request, or publish artifacts unless the user separately requests it.

Completion gate

Complete only after the manifest and file layout pass scripts/validate_harness.py, every safe required check has been attempted, result statuses and exit behavior agree with the contract, and the final report distinguishes automated evidence from manual or hardware-dependent evidence.