devharness-contributing

Contributing to devharness

Read CONTRIBUTING.md first. It owns the mechanics — build and test commands, running your build as devharness-dev, hot-reload and how to tell whether it took, stress:suspend, the release sequence, and the doc-sync list. It is the single source for all of that; this skill does not repeat it.

What follows is what CONTRIBUTING.md does not say: the code conventions, and the release habits an agent specifically gets wrong.

Releasing: what an agent gets wrong

The sequence is in CONTRIBUTING.md. Three things about it change how you should behave, not just what you type:

• npm run build:verify before bumping, always. Skipping it once put out a tag whose publish failed on a stale plugin/.mcp.json pin, while notify-marketplace had already opened a PR pinning a version npm never received. After the tag, it is too late.
• postversion pushes the branch and the tag with no confirmation. Every local commit on main ships. Nothing is "committed but held back locally" once someone bumps — never describe a commit that way, and make main exactly what should ship before bumping.
• Don't offer to push afterwards, and don't say a release "wasn't published". Both already happened. Check rather than guess: gh run list --workflow=publish.yml, npm view devharness version.

Never run npm publish by hand — a second unverified path to the registry that collides with the run the tag already started.

Tool failures are THROWN, not returned

executeToolCall (src/index.ts) converts any isError response into a thrown ToolError (src/tool-error.ts) carrying that response. Downstream code branching on result.isError is dead, and a fake executeToolCall that returns isError responses covers that dead branch while the live path goes untested. That mismatch shipped absent-element conditions failing whole runs, LAUNCH_FAILED never reaching the user, and a leaked verification tab.

• Wrap every fake executeToolCall in productionShaped() (src/test-support/fake-execute-tool-call.ts). Import the real ToolError rather than re-declaring its shape.
• Classify failures by _errorId, not message text. createErrorResponse attaches it and ToolError carries the response, so err.response._errorId is available in-process. isElementNotFoundFailure() in messages.ts is the worked example.
• Build fixtures with the real helpers (createErrorResponse, getErrorMessage, formatCodeBlock, webStorageMeta). Hand-written text drifts: fixtures asserted Element not found: ... for a year while MessageManager emitted Error: Element not found: ....