docs(v2): add parity matrix, launch order, behaviour-spec schema, and #748 design

[tomdps]

Planning artifacts for epics #643 and #665, produced 2026-07-29 against Node baseline 50c5b00. Docs only — no code, no behaviour change.

What lands

File	Purpose
docs/v2/parity-matrix.md	281 capability rows (183 control + 98 engine), each classified implemented/replaced/excluded/absent-in-node and mapped to an owning #665 issue. Input artifact for #691.
docs/v2/m1-launch-order.md	Wave structure and launch rule for milestone M1 — Certified embeddable backend.
docs/v2/behavior-spec-schema.md	Scenario schema for the dual-binary suite run against both zeroshot and zeroshot-rust.
docs/v2/748-typescript-client-design.md	Ownership design gating #748.

Why the parity matrix matters

The Node test suite cannot serve as the V2 regression net: 159 of 214 test files require() a src/lib/cli module directly, and only tests/e2e (10 files) drives the real binary. #665 additionally forbids the Rust product from importing Node, so no shared harness is possible. This matrix plus the protocol conformance vectors are the actual net.

It is provisional, not pinned — Node keeps shipping and freezes later, so §9 carries a delta log that every Node feature PR must append to until the freeze.

Findings worth reviewing

• §7 records 71 unowned capabilities, tiered by risk. Deliberately not filed as individual issues; this document is the record. Tier 1 includes that the V2 product currently has no configuration write path at all — feat(zeroshot-rust): add native export and configuration inspection CLI commands #766's non-goals forbid writes and feat(zeroshot-rust): parse isolated native configuration and named profiles #689 is read-only, so a user cannot set a default provider.
• §3.3 separates excluded by decision from excluded by consequence. The second kind is the dangerous one: nobody decided, it fell out of another constraint, and no owner recorded the loss.
• §3.4 lists two contradictions to resolve before rows can be certified, plus two Node behaviours recorded as do-not-reproduce.

CLAUDE.md corrections

Four claims were false and are fixed: the enforce-main-pr-source CI job does not exist in .github/workflows/; dev was deleted in e94b6c2 so PRs target main; .husky/pre-commit does not validate that a test file exists; and conductor classification does not live in src/conductor-bootstrap.js. The "Where to Look" table re-pads because one entry got longer — prettier reflow, not a content change.

🤖 Generated with Claude Code

https://claude.ai/code/session_0133YEUjbWi2sNj85gmqt4hm

[greptile-apps]

Example violates override constraint

When a conformance-suite implementer copies or validates this canonical example, it combines class: "implemented" with overrides, even though the field rules allow overrides only for replaced scenarios, causing a conforming validator to reject the scenario or requiring the harness to relax the documented contract.

[greptile-apps]

Parity row key cannot resolve

When the dual-binary harness validates the required parityRow linkage, isolation.worktree cannot resolve because the matrix exposes descriptive capability cells rather than this stable identifier, causing scenario validation to fail or leaving the coverage claim untraceable.

[greptile-apps]

Unowned capability totals diverge

When maintainers use §7 as the ownership record, its total of 74 does not reconcile with the 46 control rows and 35 engine rows reported as touching UNOWNED; the explanation accounts for only three of the seven-item difference, causing capabilities to be omitted from ownership triage and the downstream parity audit.

[greptile-apps]

Greptile Summary

This PR adds V2 planning and design documentation and corrects repository guidance.

• Adds the Node-to-Rust parity matrix and M1 dependency-wave launch plan.
• Defines the dual-binary behavior-spec scenario schema.
• Proposes ownership, lifecycle, packaging, and CI decisions for the TypeScript cluster client.
• Updates V2 navigation and corrects stale branch, hook, CI, and conductor guidance in CLAUDE.md.

Confidence Score: 3/5

The PR should not merge until the behavior-spec contradictions and the parity matrix's unreconciled ownership total are corrected.

The canonical behavior scenario cannot satisfy its own override rule or resolve its parity-row reference, and the consolidated ownership count can omit capabilities from the planning record.

Files Needing Attention: docs/v2/behavior-spec-schema.md, docs/v2/parity-matrix.md

Important Files Changed

Filename	Overview
docs/v2/behavior-spec-schema.md	Defines the dual-binary scenario format, but its canonical example violates the override rule and references a parity-row key that the matrix does not expose.
docs/v2/parity-matrix.md	Catalogs control and engine parity ownership, but the consolidated unowned total does not reconcile with the two surface tallies.
docs/v2/m1-launch-order.md	Adds an explicit milestone launch rule, dependency waves, and known sequencing hazards.
docs/v2/748-typescript-client-design.md	Specifies request ownership, bounded subscriptions, connection lifecycle, package boundaries, and verification gates consistently with the cited protocol and Rust-client behavior.
docs/v2/README.md	Adds navigation entries for the new V2 planning artifacts.
CLAUDE.md	Corrects stale trunk, CI-enforcement, pre-commit, and conductor-routing guidance.

_{Reviews (1): Last reviewed commit: "docs(v2): add parity matrix, launch orde..." | Re-trigger Greptile}