fairladyz625/harness-anything/harness-contributing

Harness Contributing

This is the executable contribution path for this repository. Start with a public issue or a maintainer-approved scope, work in one isolated worktree, and finish with a reviewable pull request. The current `tools/gate-manifest.json`, `package.json`, and `pull_request_template.md` remain the machine-readable authorities they describe; inspect them instead of relying on remembered job names or template fields.

Boundary

Use only public repository source, public issue/PR discussion, and evidence a reviewer may see. Never copy local planning records, generated runtime state, local agent instructions, credentials, private URLs, or absolute machine paths into the branch or PR body. Before every commit, inspect the complete staged diff and confirm every path belongs to the stated public scope.

The contribution scope grants authority to change the stated files and run local checks. Push the branch or open/update its PR only when the user or maintainer asked for that external action. No contribution grants authority to push to main, bypass a gate, force-push, or merge. A maintainer owns the final merge.

中文：只使用公开仓库、公开 issue/PR 和 reviewer 可见的证据。不要把本地规划、

运行状态、凭证、私有链接或本机绝对路径放进公开 diff 或 PR。贡献者只能提交提案，

不能直推或自行合入 main。

Environment and worktree

Node.js 24 or newer and git are required. For a new checkout, run:

git clone https://github.com/FairladyZ625/harness-anything.git
cd harness-anything
git fetch origin
git status --short --branch

Run this version gate as one standalone command before npm ci; it exits nonzero and prints three common activation choices when the active Node is too old:

node -e 'const major=Number(process.versions.node.split(".")[0]); if (major < 24) { console.error([`Node.js 24+ required; found ${process.version}.`, "nvm: nvm install 24 && nvm use 24", `Homebrew node@24: brew install node@24 && export PATH="$(brew --prefix node@24)/bin:$PATH"`, "Volta: volta install node@24"].join("\n")); process.exit(1); } console.log(`Node.js ${process.version} satisfies >=24`);'

If it fails, use one printed line to activate Node 24, then rerun the same gate until it exits zero. Stop if the checkout already has changes you do not own. Do not implement on the primary checkout or shared main. From the primary checkout, create exactly one task worktree from current origin/main:

git worktree add .worktrees/<slug> -b <branch> origin/main
cd .worktrees/<slug>
git merge-base --is-ancestor origin/main HEAD
git rev-list --count origin/main..HEAD
git log --oneline origin/main..HEAD
git status --short --branch
npm ci

Replace <slug> with a short filesystem-safe scope and <branch> with the public contribution branch, such as fix/<slug> or docs/<slug>. If either name already belongs to another worktree, choose a new name; never share that worktree. git merge-base --is-ancestor must exit zero before editing. A newly created branch should print 0 from git rev-list and no commit lines from git log. Any listed commit is already part of the prospective origin/main...HEAD PR delta: continue only when it belongs to the approved public contribution, and later describe the whole branch delta while clearly distinguishing those pre-existing commits from the edits made in this run. Otherwise stop and create a clean worktree or ask the maintainer which branch scope is intended.

Read the issue and relevant source in this worktree. State, in one sentence, the problem, allowed change surface, excluded surface, and proof required. Ask for a maintainer decision rather than guessing when the public issue does not settle a load-bearing choice.

中文：先用单独的一条可执行命令确认 Node 24+，再从最新 origin/main 创建独立

worktree；每个贡献者或 agent 使用自己的 branch/worktree。编辑前列出 ahead

commit；它们会进入整个 PR diff，不能当作不存在。安装依赖并写清范围后再编辑。

Make the change and test its surface

Keep the patch to the smallest coherent solution. Inspect nearby code and tests before adding a new abstraction. Preserve unrelated changes and generated files.

Every new Node test under packages/ or tools/ must:

• have a filename ending in .test.mjs, .test.js, .test.ts, .spec.mjs,

.spec.js, or .spec.ts; and

• put exactly one of these declarations on line 1:

// harness-test-tier: fast
// harness-test-tier: contract
// harness-test-tier: integration

Choose fast for pure or near-pure behavior, contract for public API/schema or cross-package contracts, and integration for CLI, filesystem, store, migration, or other slower behavior. The rules are enforced by `tools/test-tier-manifest.mjs`; there is no central file list to edit.

Run changed or newly added fast tests through the repository runner:

node tools/run-node-tests.mjs --file <repo-relative-test-file>

Run the tests affected by the change with the repository runner. Internal server dispatch is provided by the private test-isolation skill and is not part of this public contribution skill:

node tools/run-node-tests.mjs --tier fast

--changed <base> (default origin/main) selects the test files the committed change itself edits, plus the registered test files whose imports reach a changed source; the import scan is a heuristic, so use it as the default sweep before handing off. When a change touches a shared surface — authorization, settings, construction entry points, protocol, or events — run the owning package's whole tier instead of the scan:

node tools/run-node-tests.mjs --tier integration --prefix packages/daemon/test

Exact files and the other tiers take the same selector:

node tools/run-node-tests.mjs --file tools/run-node-tests.test.mjs

For a docs-only change, run the closest docs checker or checker test if one exists; do not invent a meaningless test. Always inspect the patch:

git status --short
git diff --check
git diff --stat
git diff -- <changed-paths>

中文：测试文件名必须匹配 .test/.spec 约定，首行必须且只能声明一个

fast|contract|integration tier。本机先跑改动面的精确测试；交给测试服务器用

node tools/run-node-tests.mjs --tier fast 运行通用本机测试。改动碰到

授权、settings、构造入口、协议、事件这类共享路径时，改用

node tools/run-node-tests.mjs --tier integration --prefix packages/<包>/test 跑所在包整层。docs-only 改动若没有

对应行为测试，不要为了凑数新增无意义测试。

Run local static gates before you push

Do not use npm run check:local as the contribution loop, and do not run the full aggregate merely to approximate GitHub. GitHub CI is authoritative. But a boundary/vocabulary/dead-export/write-path/complexity red costs an ~11 minute CI round trip, and those gates read only repository source. Run them locally before the commit:

npm run check:static              # the whole static set, ~75s
npm run check:static -- --changed # only gates whose localPathGlobs match the working-tree diff

The set is derived from tools/gate-manifest.json, not a second checklist: a gate qualifies when it is deterministic: true, PR-visible, pr-required, and neither a test tier, a smoke, nor a release-policy gate. That deliberately leaves out three things a worker must not run here:

• Gates that need inputs this machine does not own. deterministic: false

gates read external APIs, so on a clean worktree they fail with e.g. repository must be provided as owner/name. Selecting them is what made the old local gate command red on unmodified code.

• Test tiers and smokes. test:fast, test:contract, test:integration,

test:gui and the package smokes run whole tiers or boot a packaged artifact; run only the tests your change affects instead (see above), and let CI own the full tiers.

• Release-policy gates. check-package-tarball-exports alone spends ~99s

packing tarballs for a verdict a static read cannot give.

--changed narrowing is a convenience, not a licence to skip: a gate that declares no localPathGlobs cannot be narrowed and always runs. When the diff touches a shared surface (protocol, events, authorization, construction entry points), run the full set and the affected integration files through the isolated test dispatcher.

To reproduce a specific CI job instead, list its gates and run the job with the manifest runner. --workflow-job runs every selected gate and reports all failures together; CI omits --changed and still runs every command:

node -e 'const m=require("./tools/gate-manifest.json"); for (const g of m.gates.filter(g=>!g.aggregate)) for (const job of g.executionSurfaces?.rewriteCi?.pullRequestJobs??[]) console.log(`${job}\t${g.id}\t${g.command}\t${(g.consumerScope??[]).join("; ")}`)'
node tools/run-manifest-gates.mjs --workflow-job <job> --changed origin/main

boundaries is the usual job for public source, tool, and documentation boundaries. Use the manifest's other current PR jobs when the patch touches their surface—for example tests, package policy, dependencies/supply chain, or the GUI. Job-level path selection is conservative: it narrows only when every changed path matches explicit localPathGlobs; an unclassified or mixed surface runs the complete job. Record every command and result in the PR body, including a scoped reason for anything not run.

If a --workflow-job run reaches check-github-required-contexts, the only failure that may be excluded locally is the exact error repository must be provided as owner/name when no GitHub repository/token context is available. Preserve that output and rerun with only that gate excluded:

node tools/run-manifest-gates.mjs --workflow-job boundaries --changed origin/main --exclude check-github-required-contexts

If that exact message is not the sole failure, do not exclude the gate. Never treat the exclusion as a CI waiver; the required GitHub context must still pass on the PR. npm run check:static needs no such exception because it excludes every non-deterministic gate by declaration.

中文：推送前跑 npm run check:static（全套约 75s）或加 --changed 只跑与改动

相关的门。集合由 tools/gate-manifest.json 派生：deterministic: true、PR 可见、

pr-required，且不是测试层、smoke 或 release-policy 门。刻意不含三类——需要本机

没有的外部输入的 deterministic: false 门（它们会在干净 worktree 上报

repository must be provided as owner/name）、整层测试与 smoke、以及打包类

release-policy 门（仅 check-package-tarball-exports 就要约 99s）。--changed

是便利不是豁免：未声明 localPathGlobs 的门无法收窄，永远运行。触碰协议、事件、

授权、构造入口这类共享面时跑全套，并按隔离入口点名受影响的 integration 文件。

这是 worker 的本地静态门，不是 check:local；CI 仍是完整权威。

Commit with the contributor identity

Confirm the author identity before committing:

git config --get user.name
git config --get user.email

If either is empty or wrong, the contributor must set their own identity before continuing:

git config user.name "<your name>"
git config user.email "<your email>"

Stage only named contribution paths, recheck the staged patch, and commit:

git add <changed-paths>
git diff --cached --check
git diff --cached --stat
git diff --cached -- <changed-paths>
git commit -m "<feat|fix|refactor|docs|test|ci>: <concise English summary>"

Do not mention an AI author in the commit message. Use the actual human or agent operator's configured git identity.

Prepare the PR body

Do this after all contribution commits and after ha task submit freezes the delivery cut. Refresh and synchronize first, then rerun affected tests and resubmit if a rebase changes the branch:

git fetch origin
date -u '+%Y-%m-%d %H:%M:%S UTC'
git rebase origin/main
git rev-parse origin/main
git merge-base origin/main HEAD
git status --short --branch

If the initial worktree check found approved pre-existing commits, describe the complete origin/main...HEAD delta in the PR body and explicitly separate those commits from the changes authored in the current run.