chore(pai): make the PR review procedure shared and executable

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @Soushi888.

Intent

Our review workflow works, but its method is not legible to anyone but the person running it. That is a fair objection independent of trust: a step that gates a merge should be something either maintainer can read and run, not a judgement whose procedure lives in one person's own tooling.

This makes the review procedure a repo artifact, adds the conflict-resolution rule we were missing, and cleans up pai/ so shared content and per-tool packaging stop being tangled.

Changes

1. A shared review procedure

pai/shared/skills/nondominium-review/ defines the order the six REVIEW.md areas get walked, the CONTRIBUTING.md merge criteria, the conflict-resolution check, and a fixed verdict block (APPROVE / CHANGES REQUESTED / BLOCKED) with per-area results, so two reviewers produce comparable output. It restates nothing: REVIEW.md stays the single home for what gets flagged.

Invocable as /nondominium-review on every tool we use, with nothing installed from anywhere else:

Tool	How
Cursor	Type /, pick nondominium-review. Skills are Cursor's slash-command mechanism; the skill lands in .cursor/skills/ and .agents/skills/.
Claude Code	/nondominium-review [PR], from .claude/commands/.
Any Agent Skills client	The skill in .agents/skills/ is the command.

One rule in it has already cost us something: no approval while the pipeline is running. Our CI stages are chained, so early green says nothing about e2e. An approval posted on partial green had to be retracted on #132. That is now written down rather than remembered.

2. Merge conflict resolution policy (CONTRIBUTING.md)

The governing question is which side was trying to change meaning, and which was only trying to restate it. Presentational changes yield to semantic ones, always. When both sides are semantic it is a decision between two authors, not a merge mechanic. A resolution is backed by evidence (the Sweettest target passes, or the resolved doc is re-read against its REQ-*), not asserted.

Names what counts as fundamental here: REQ-* meaning, enforced validation and permitted state transitions, Valueflows field names, NDO layer boundaries.

The sharpest case is in the hotspot table: #[hdk_entry_types] derives type indices from declaration order, so tidying an integrity enum alphabetically while resolving invalidates every entry already on the DHT. The cosmetically nicer resolution is the one that breaks the data.

3. pai/ split into shared sources and harness adapters

pai/shared/ holds everything describing the project: conventions.md, rules/ (was cursor-rules/, whose content was never Cursor-specific), and skills/ (was claude/skills/, though every skill already fanned out to all three trees). pai/harnesses/ holds only what one tool needs of its own, today Claude Code's settings.json and commands/. Cursor gets no directory because its adapter is a pure transform in nix/cursor-pai.nix.

The test for where a file belongs: would its content change if we dropped support for a tool? If no, it is shared.

4. Supporting changes

• .github/workflows/lint.yml reports rustfmt status on every PR. Non-blocking on purpose, explained below.
• bun run pai:sync copies pai/shared/skills/ from the working tree for the inner loop. Nix only sees git-tracked files, so a new skill silently does not materialize until committed, and nothing errors. Nix stays the authority; this is for iteration.
• pai/README.md rewritten for the new structure. It also removes a description of a LoadProjectDocs.hook.ts SessionStart hook: a full section, two diagrams and a file-map entry for a file that does not exist and that settings.json never wired. The @ mentions in .rules are the whole mechanism.
• REVIEW.md §4 correction. It told reviewers to check for await_consistency(&[&cell_a, &cell_b]). That does not compile: 0.6.0 needs the timeout wrapper and the array by value.
• CONTRIBUTING.md CI section corrected. It said tests were "non-blocking while the test suite is being stabilized", which stopped being true once sweettest and e2e became chained required jobs.

Decisions

Option	Rejected because
Blocking cargo fmt --check	37 of 62 Rust files are unformatted, several touched by every open branch. A blocking gate fails on day one and forces a workspace reformat that conflicts with in-flight work. Advisory now; flipping it is uncommenting one line, once a dedicated formatting PR lands with nothing else open.
continue-on-error: true on the lint job	Keeps the workflow green but still marks the job failed, so the PR shows a red X and gh pr checks reports a failure. Our own review procedure treats a failing check as a merge blocker, so the advisory job would have blocked reviews it was never meant to gate. The step now always exits 0.
Adding cargo clippy here	Never run against this workspace. Adding a gate whose output nobody has seen is how CI starts getting ignored. Its own PR, results read first.
Copying the review checks into the skill	Two copies of a checklist drift apart within a month. Procedure in the skill, content in REVIEW.md.
A separate Cursor command file	Unnecessary. Cursor has no .cursor/commands/; skills are its slash-command surface, and we already distribute there.
Leaving pai/human_ai_collaboration.md at the pai/ root	It arrived from #132 and is harness-agnostic reference material, so it classifies as shared by the same test as everything else. Moved into pai/shared/ with no edits to the document. @TiberiusB, say the word if you want it elsewhere.
Moving pai/nondominium.code-workspace	Editors resolve a workspace file by its path. Listed in the README tree instead.

How to test

nix develop
ls .cursor/skills/nondominium-review .agents/skills/nondominium-review .claude/skills/nondominium-review
ls .claude/commands/          # nondominium-review.md
ls .cursor/rules/             # all 12 .mdc still generate from the new paths
bun run pai:sync              # copies shared skills from the working tree

Then run /nondominium-review 143 on this PR and check the verdict block renders.

Note that nix only sees git-tracked files, so a locally added skill must be committed before nix develop picks it up.

Documentation

• pai/README.md — rewritten: architecture, per-tool invocation, two skill sources, the one-home rule, editing workflow
• CONTRIBUTING.md — review procedure and invocation table, merge conflict policy, corrected CI description, updated source table
• REVIEW.md — content/procedure split noted; §4 signature corrected
• pai/shared/skills/nondominium-review/SKILL.md — new

Related

• Follow-up: chore/rustfmt to clear the formatting backlog, then make lint.yml blocking
• Follow-up: clippy in its own PR once its output has been reviewed
• Follow-up: sweettest (person) flaked on run 33278757427 (get_hrea_agents_returns_matching_rea_agent, person_create_populates_hrea_agent_hash, both panicking in holochain's sweet_conductor_handle.rs). The same job passed on an earlier run against identical Rust; every commit here is markdown, nix and config. Worth its own issue: a flaky gate is the first thing that will make someone override the wait-for-green rule.
• pai/human_ai_collaboration.md moved into pai/shared/ (move only, no content edits)