docs(contributing): make first-contribution cost visible and smaller

[huangruiteng]

Why

The core LoopX contracts are worth their cost. But a first contribution pays several costs that are not written down anywhere, or are larger than they need to be:

• pyproject.toml says dependencies = [] and "lightweight", yet every loopx command and the test suite need a system Node.js 22.22.3+. CONTRIBUTING.md never mentioned Node.js or npm ci.
• On a fresh checkout without npm ci, 91 of 777 architecture tests fail. Each one prints its own traceback, and the remedy is buried inside them. If node is not on PATH at all, the scanner crashes with an uncaught FileNotFoundError.
• There are 14 workflows, and nothing says which ones block a merge. Only two do.
• Nothing says when a change needs an RFC. A contributor adding one additive field faces a 17-part template plus a bilingual mirror.
• Adding one observable field to a capability means reading a whole package; decision_context is 17 modules, about 6.5K lines. No README maps modules to steps.

This PR does not remove any of the rigor. It makes these costs visible up front and, where possible, smaller.

What changes

Node.js is visible before install

• pyproject.toml: the description drops "lightweight" and states "(requires Node.js 22.22.3+)". A comment next to dependencies = [] explains that pip cannot install the Node.js runtime.
• CONTRIBUTING.md: a new Prerequisites and one-time setup section covers Python 3.11+ via uv, Node.js 22.22.3+ (24 LTS recommended), and npm ci --ignore-scripts as a once-per-worktree step.

A missing npm ci produces one message, not 91

• loopx/semantics/production.py:
  • checks that node is on PATH before running the scan;
  • recognises ERR_MODULE_NOT_FOUND for typescript and raises one named error, NPM_DEV_DEPENDENCIES_MISSING. The parser's stderr is still never echoed.
• tests/conftest.py: when the typescript package cannot be resolved, pytest prints a header line. After the final totals line it prints:
  90 failure(s) share one cause: repository npm dev dependencies are not installed (the typescript package is missing); run npm ci --ignore-scripts once from the repository root.
  The remaining failure, the retrodiction baseline, is an indirect consequence and passes once npm ci has run. With dependencies installed, the architecture suite passes (777).

Which CI checks matter

• CONTRIBUTING.md gains What CI runs on a pull request:
  • only Sign-off and merge-gate block a merge, per the main ruleset;
  • it names the six Python Tests jobs that merge-gate aggregates;
  • a table lists all 14 workflows with their PR trigger, whether they block, and what they check.
• It also adds a Fast loop and full check split, so iterating does not mean running the full pre-push list every time.

When a change needs an RFC

• docs/architecture/rfcs/README.md gains When a change needs an RFC:
  • An RFC is needed for a new or moved authority, a change in default behavior, a non-additive schema change, an irreversible migration, or a contract that several capabilities must follow.
  • An RFC is not needed for an additive, compatible field, a bug fix that restores documented behavior, or tests, smokes, and docs. For those, update the reference contract or capability README, and put a design note in the PR.
  • A compact RFC marks inapplicable sections as Not applicable: <reason> and adds appendices only once they have content. The mirror keeps the same compact shape.
• To avoid conflicts with docs(rfc): generated lifecycle status index, supersession declarations, checkpoint logs moved to ledger #5078, this PR does not touch TEMPLATE.md or the bilingual-mirror policy itself.

Capability code maps

• loopx/capabilities/README.md defines an optional ## Code Map convention.
• decision_context gets the first one, in the English README and the zh-CN mirror. It has one row per module, in pipeline order, plus an add an observable field route that lists which files to touch for a per-source fact, a decision-level field, a capture-only fact, the CLI, docs, and tests.

Guards so this does not drift

• tests/test_contributing_guide.py checks three things:
  • every Node.js X.Y.Z in the README (en/zh), CONTRIBUTING, pyproject, the install guide, and the entrypoint equals MINIMUM_NODE_VERSION; package.json engines is >= that version; exact workflow pins equal it;
  • the CI table lists exactly the files in .github/workflows;
  • the section names every merge-gate dependency.
• tests/test_capability_code_maps.py requires any code map to list exactly the package's modules, and the Chinese map to name the same set.
• tests/architecture/test_semantic_production.py covers both new scanner diagnostics (Node missing, typescript missing) and checks that stderr does not leak into them.

Interaction with open PRs

• feat(decision-context): per-source freshness contract + doctor alert for silent capture hosts #5075 adds decision_context/freshness.py. Whichever PR lands second adds one Code Map row, which the new guard will point out.
• docs(rfc): generated lifecycle status index, supersession declarations, checkpoint logs moved to ledger #5078 edits TEMPLATE.md and other hunks of the RFC README.md. This PR only inserts one new subsection after the opening paragraph, with no overlapping lines.

Not in this PR

Splitting large modules, merging workflows, and relaxing the bilingual mirror policy for small RFCs are larger structural or policy decisions for maintainers.

Validation

• Full Python suite: 12206 passed, 48 skipped. The 2 failures, test_delegation_result_use [file] and [sqlite], also fail on the unmodified merge base.
• tests/architecture in a fresh worktree without node_modules: 91 failed, with a single loopx setup remedy line at the end. After npm ci --ignore-scripts: 777 passed.
• ruff on the touched Python files, mypy: clean.
• examples/docs-governance-smoke.py, examples/semantic-vocabulary-drift-smoke.py, examples/decision-context-contract-smoke.py: ok.
• loopx check --scan-path on every touched file: errors=0. git diff --check: clean.