[mikestankavich]

The trakrf/docs share of TRA-1219. Two commits.

Why this repo's share is only item 3

The ticket names three things. Verified against this tree rather than inherited from the ticket:

Item	Applies here?
1 — platform's dead cp commands	No. Other repo, and already fixed in platform#623
2 — ble-mcp-test's dead branch form	No. Other repo, other org
3 — give CONTRIBUTING.md a consumer	Yes — this is the whole docs share

Docs' CONTRIBUTING.md is genuinely clean today: every pnpm script it names exists in package.json, and every path it references (docs/, static/img/, docs/api/changelog.md, docs/release-notes.md, CODE_OF_CONDUCT.md) exists. That was checked here, not taken from the ticket's "checked, nothing broken."

But clean today is exactly the state the other repos were in once. The ticket's own diagnosis is that CONTRIBUTING.md did not rot through carelessness — it rotted because nothing ever contradicted it. Platform's README.md stayed correct while its CONTRIBUTING.md three directories away did not: same repo, same vintage, different consumers. This repo's copy being correct is luck, not structure.

What this adds

scripts/check-contributing.mjs — parses CONTRIBUTING.md and asserts every pnpm script and repo path it names still resolves. Exits 1 with a list naming each one.

Wired into pnpm lint, which is inside the validate command declared in .claude/csw.json. A checker nothing invokes is the problem it was written to solve.

CONTRIBUTING.md gains one line saying it is checked, so the next editor learns that from the file rather than from a failing build.

Two false positives, found by running it

Both would have made the gate untrustworthy, and neither was predictable from reading the file:

• docs/tra-0000-update-getting-started — a branch-name example, matched by a naive a/b path pattern. A path claim now has to end in a known file extension or a trailing slash; branch examples have neither.
• /api/v1/ — an API route, not a file. A leading slash now marks a span as absolute rather than repo-relative.

A check that fails on a correct file is a check someone turns off. Worth naming because the ticket that produced this one exists partly because a check was recommended without being run.

Verification

Proven by planting a breakage rather than trusting a green run — a pnpm nonexistent-script reference and a docs/not-a-real-file.md path:

CONTRIBUTING.md references things that no longer exist:
  - pnpm script "nonexistent-script" is referenced but not in package.json
  - path `docs/not-a-real-file.md` is referenced but does not exist
exit 1

Breakage removed, then the full chain:

pnpm lint       PASS   (prettier + the new checker)
pnpm typecheck  PASS
pnpm build      PASS
csw-gates       exit 0 (none configured)

Scope, stated plainly

This is one repo's answer to item 3, not a ruling on it. The ticket weighs two options — a CI job that runs the documented quickstart, or folding what must stay true into a file something already reads — and deliberately picks neither. This takes the second shape, for this repo only, because docs' quickstart is pnpm install and pnpm dev, which CI already exercises; what can actually drift here is the references, so those are what get checked.

It does not settle whether platform, infra or ble-mcp-test want the same mechanism. If the estate later converges on a shared approach, this is revertible in one commit.

What is worth a human eye

The heuristic for "is this inline code span a path claim?" is the judgment call. It is deliberately conservative — extension or trailing slash — so it will miss an extensionless directory reference written without a trailing slash. That trade is on purpose: a missed check is recoverable, a gate that cries wolf gets removed.

Refs TRA-1219

🤖 Generated with Claude Code

https://claude.ai/code/session_01RWAqULDa91P8QxVD6hRaer

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	4f044d9
Status:	✅  Deploy successful!
Preview URL:	https://6b59c233.docs-4n7.pages.dev
Branch Preview URL:	https://chore-tra-1219-contributing.docs-4n7.pages.dev

View logs