Raise the engineering baseline before the compiler lands #21

Why

The compiler is about to arrive in this repository. Before its first module lands, the repository needs the gates, the test harness, the rule ledger and the agent instructions that keep it honest, so the compiler is written against them rather than retrofitted to them.

Decisions

Taken in a design session on 2026-09-11. Each ticket carries the decisions it needs; this is the whole set in one place.

Delivery

• One pull request per ticket, squash-merged, each leaving Pipeline Complete green and wiring its own CI job.
• Each pull request is drafted with the pr-composer skill and opened only after the maintainer approves the draft. It is merged once every check is green, and the next ticket starts from the updated main.

Toolchain

• npm stays. .nvmrc pins an exact Node 24.x, and CI reads it.
• Tests move from node:test and c8 to Vitest 4 with V8 coverage.
• Scripts and tests become TypeScript, run directly by Node's type stripping, with no build step for tooling.
• TypeScript is pinned to an exact 6.0.x. ESLint 10 runs strictTypeChecked with type information. Prettier stays.
• Coverage thresholds are a ratchet: set from what the suite reaches, and only ever raised.
• Until the compiler exists, the npm package ships docs/adr and spec only.
• (Amended 2026-09-14.) The repository root stays TypeScript. The coursework implementation under emf/ brings its own Maven build on JDK 21, entirely inside emf/, and is never shipped in the npm package.

CI

• One job per gate, aggregated by Pipeline Complete, which fails when any job fails, is cancelled or is skipped. The repository is public, so per-job billing does not apply.
• Every action and reusable workflow is pinned by commit SHA with a version comment.
• A validation workflow checks each pull request title and commit against the conventional-commit types release-please reads. CodeQL runs outside the gate.
• A non-gating job comments each pull request's shape and coverage. Every pull request from a branch of this repository publishes a release candidate under the rc dist-tag.
• Mutation testing is a required job, with a break score set from a measurement.
• (Amended 2026-09-14.) One emf job runs mvn verify inside emf/ and is required by Pipeline Complete; it is deleted with emf/. Mutation testing, the coverage ratchet and the rule ledger cover the TypeScript tree only.

Rules

• Every enforced rule has a greppable ID, a row in a new docs/architecture-rules.md, and a fixture that proves it fires. A meta test holds the document and the enforcement together, and a rule not enforced yet is listed as pending with a reason.
• Families: layering, external dependencies, graph hygiene, naming, purity and seams, tests, toolchain, CLI conventions, registry contracts, diagnostics, and the existing gates.
• Ambient capabilities (environment, clock, randomness, console, spawning, synchronous filesystem) are allowed only in the infrastructure and CLI rings. Exiting the process and writing to stdout or stderr are allowed only in src/cli/boundary.ts, the one file excluded from coverage.
• A dependency denylist, grounded in the architecture ADRs.
• Every E_ code the specification defines is proved by a test, or listed as pending with a reason.
• Generated artifacts (JSON Schema, a diagnostic catalogue, and later the rendered example trees) are committed, and CI fails on a diff, from the pull request that brings their generator.
• No em-dashes in tracked text outside docs/mde and CHANGELOG.md.

Decision records

• Gate and test decisions become ADRs in docs/adr/architecture/, numbered from 0100 in the estate-wide sequence. Agent routing, CI shape and the pull request report are documented in AGENTS.md and CONTRIBUTING.md instead.

Agents

• AGENTS.md is the one instruction file for every agent. CLAUDE.md imports it and adds only Claude-specific notes. The estate pointer to workspace/CLAUDE.md moves into AGENTS.md.
• Repository skills (adr, spec-change, gate-triage, new-rule) live in .agents/skills, and .claude/skills is a symlink to it.
• .claude/settings.json (a permission allowlist and the plugins this repository uses) and .mcp.json are committed.
• Matt Pocock's engineering skills are configured through docs/agents/. Two labels, status: ready-for-agent and status: ready-for-human, join the estate taxonomy.

Out of scope

• A workflow that applies the branch ruleset (the estate script covers it), a separate link checker (lint:links already checks files and anchors), and repository-specific issue or pull request templates (the organisation defaults apply).
• Anything that needs the compiler to exist: the golden tree, the system and end-to-end tiers, the generators, and mutation targets beyond the gate scripts. Each arrives as a pending entry and lands with the code.

Tickets

The sub-issues of this issue, in dependency order. Each one lists the tickets that block it.