FAQ

Is the harness tied to TypeScript or Cloudflare Workers?

No. Those are the default *_CMD implementations, and they are overridable. The target *names* (lint, test, build, …) are language-agnostic. Point the variables at your toolchain and the contract is unchanged. See Makefile Interface.

Why is CLAUDE.md a symlink to AGENTS.md?

So both tools read one source of truth. harness-check invariant #1 fails if CLAUDE.md is missing or is a real file instead of a symlink. Fix: rm -f CLAUDE.md && ln -s AGENTS.md CLAUDE.md.

What exactly does make check run?

lint, format, typecheck, test, deadcode, build, and harness-check — in that order, convergence test last. It is the single gate and must finish in under ~5 minutes.

make harness-check is failing. What do I do?

Read it top to bottom. Every failure prints a To fix: line with the exact remediation. It runs all invariants in one pass (not fail-fast) so you can fix them all at once.

Do trivial changes need OpenSpec and a reviewer?

No. A typo, a log line, or a one-liner you can describe in a sentence skips both. Match the process to the risk — see Workflow.

/versions returned just ["0.1.0"]. Is that a bug?

That is the graceful-degradation fallback: when the GitHub releases API is unreachable and the KV cache is empty, /versions serves a static list rather than failing. Once real releases are published and cached, it returns them.

Can I adopt the harness into a big legacy repo?

Yes — adoption is non-destructive and supports baselining the checks that fail on legacy code, tracked as an honest ledger in AGENTS.md. See Adoption Guide.