* docs(development): add npm distribution design + audit (#800 B1)

Codex's post-stop guidance was: if continuing at all, do the #800 B1
slice—design and dry-run packaging audit, not implementation. This PR
delivers that.

Audit findings from npm pack --dry-run on v0.55.0
- private: true blocks publish.
- files: unset, so the tarball would carry 969 files / 8.3 MB unpacked.
- Top contributors that should be excluded: pages/ (158), tests/ (193),
  docs/ (31), and parts of runners/.
- engines.node: 22.x blocks Node 20 LTS installs.
- bin maps both river and river-reviewer to src/cli.mjs, which is
  correct.

Hidden risks captured (per multi-perspective review carry-over)
- CLI 境界混乱: two CLIs exist (src/cli.mjs and runners/cli/bin/river)
  with overlapping subcommand names (review, eval). Resolution: publish
  only the main CLI; document the Runner CLI as contributor-only.
- Node version: relax engines.node to >=20 before publish, since CI
  already covers 20.x.
- GitHub Action dist staleness: exclude runners/github-action/dist/
  from the npm tarball (GitHub Action users already pull from the repo
  via @v0.x.x tags, not via npm).
- Runtime .river/ path: no code change needed (A2-fix-4 #877 already
  null-safes loadRiskMap on ENOENT). Note in publish notes.

Reference patch for B2 implementation
- Exact package.json diff (private/files/engines/publishConfig).
- "files" allowlist with explicit include/exclude/borderline buckets.
- Expected size after the allowlist: 300-500 KB tarball, 1.5-2 MB
  unpacked, ~400 files.

Explicitly out of scope for B1
- npx river try (C3).
- Sample skill curation, scoped packages, automated publish workflow,
  cross-platform install testing.

No code changes. No package.json mutation.

Refs: #800.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* docs: apply gemini PR #886 review on npm distribution design

Fix two correct gemini comments on the package.json reference patch:

1. README.md / LICENSE / package.json removed from the files allowlist:
   npm auto-includes these regardless of the files field
   (npm-publish docs: "Files included"). Adding them to files was
   harmless but misleading. AGENT_LEARNINGS.md is contributor-only
   and should not ship to npm consumers; removed too.

2. Duplicate engines field corrected in the diff: the previous block
   showed both "+  engines: { node: >=20 }" and "  engines: { node:
   22.x }" without removing the latter, producing invalid JSON if
   applied verbatim. Now the diff shows a single line change from
   "node: 22.x" to "node: >=20".

No factual change to the design. The B2 implementation reference is
now applicable as-is.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>

* docs(examples): add risk-map example file + adoption guide

Codex's final-pass review (post-25-PR) flagged that docs/guides
reference .river/risk-map.yaml but the repo carries no concrete
example for adopters to copy. Add one under examples/risk-map/ with
a README explaining the three action values and the apply / verify
flow.

Contents
- examples/risk-map/risk-map.yaml — sample with 10 rules covering
  require_human_review (security-sensitive files, credentials, CI
  workflows), escalate (LLM call path, config, action dist,
  package.json), and comment_only (docs, pages, tests). Each rule
  has a reason string so adopters see the intent, not just the
  pattern.
- examples/risk-map/README.md — adoption guide pointing at
  schemas/risk-map.schema.json, the user guide
  pages/guides/repo-wide-review.md, the execution-context-contract
  doc, and PR #877 (riskAssessment forwarding on the exec path).
- examples/README.md — link to the new directory.

The example was validated end-to-end with the real loadRiskMap +
evaluateRisk implementation: 10 rules parse cleanly, sample paths
classify correctly (require_human_review hit on secret-redactor.mjs,
escalate on review-engine.mjs, comment_only on docs/, fall-through
on unknown paths).

No code or runtime change. 1087/1087 tests green.

Refs: #800 (Codex final-pass review item #2 of 3).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* docs(examples): correct risk-map verification + use absolute schema link (gemini PR #896)

Apply both gemini PR #896 comments.

HIGH: the README's verify step claimed
"jq .plan.riskAssessment /tmp/r.json"
would show aggregateAction / escalatedFiles. End-to-end test against
the real runReviewPlan + loadRiskMap confirmed this is wrong: the
artifact's `plan` schema only carries selectedSkills / skippedSkills /
plannerMode. riskAssessment is computed internally and only forwarded
to generateReview's prompt context. Rewrite step 4 to (a) verify file
parses by any river review command succeeding and (b) state honestly
that risk classification is not echoed on the artifact.

MEDIUM: the YAML header comments referenced ../../schemas/...
relative paths that break the moment an adopter copies this file to
.river/risk-map.yaml. Replace with absolute GitHub URLs so the
references stay resolvable after the copy.

No code change; user-facing accuracy fix only.

Refs: PR #896 (gemini review).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>

#898)

Capture the 5-day sprint (35 PR, 6 release, 1 production CVE close)
as durable record before starting the next session. Codex consultation
was the foundation; the primary takeaway is:

  > 最大の問題は速度ではなく、停止条件の弱さ。次は「作る量」
  > より「どこから保留に戻すか」を先に設計すべき。

Sections
- Numerical summary
- What worked (5 items: multi-perspective review, silent-skip thread,
  memory persistence, gh-api recovery, dogfood detection)
- What didn't work (6 items: overproduction past Codex stop, eval-less
  skill increase, manual release-please kick x4, AGENTS.md pollution,
  reviewer mis-suggestions, single-shot multi-perspective)
- Surprises (npm pack audit findings, CLI boundary, fs-loss recovery)
- 5 pivot points (timeline of where direction should have changed)
- Codex 100-char summary on the sprint
- Improvement priorities split into Skills / Agents / Workflow with
  P0/P1/P2 ranking
- Stop-on-stop-judge operational rule with Continue / Consult / Park
  buckets, plus post-hoc classification of this sprint's 35 PRs
  (Continue: A2-fix and CVE-class items; Consult: skill registry
  decisions; Park: ~13 PRs of docs-about-docs / marginal polish)
- Next sprint opening checklist

No code change. Foundation for two follow-up PRs (S3 registry section,
W1+W5 release-please kick automation).

Refs: Codex consultations during the 5-day sprint (PR #860 78→91,
PR #864 dogfood, PR #877 riskAssessment, post-stop 13 PRs).

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>

…3-runners) (#933)

Per docs/development/a2-3-replay-execution-design.md A2-3-runners slice:
populate the carry-over snapshot in buildExecutionPlan output so a future
A2-3-impl slice can attach it to artifact.debug.execution.snapshot for
--plan replay execution.

Additive shape:
- New top-level `snapshot: { fileTypes, relatedADRs, reviewMode, riskAssessment }`
- New top-level `riskAssessment` (was previously computed but never returned,
  silently breaking `plan.riskAssessment` consumers; #877 silent-skip
  taxonomy applies)

The empty-selection early return now also carries the snapshot (with
relatedADRs: [], reviewMode: null) so consumers can record the audit trail
even when no skills run.

Action bundle rebuilt (npm run build:action on Node 22) since cli.mjs
transitively imports review-runner.

Next slice: A2-3-impl wires src/lib/review-plan.mjs to copy plan.snapshot
into artifact.debug.execution.snapshot AND the replay path (runReviewExecReplay)
to read it back. That requires src/lib/ change; AGENTS.md "Ask before editing"
gate applies.

…on (#939)

The 2026-05-25..28 retrospective was written mid-session (#930). This addendum
captures the remaining arc (#878 epic, #868/#921/#929 closeout) and the one
durable lesson worth persisting:

"completed" report ≠ wired-through. #877 claimed to fix the riskAssessment
silent-skip but only wired the consumer side; the producer never emitted the
value, so plan.riskAssessment was always undefined. Found during A2-3-runners
(#933).

New P1 rule: a silent-skip fix needs a test asserting the value is RETURNED by
the producer AND consumed — not just "forwarded if present". A "forwards X"
test passes whether X is real or undefined.

Also records: the 4-slice design-doc-first delivery shape (#878) and the
design-only discipline held twice (#910, #938).

Full session totals: 38 PRs / 13 releases / 4 issues closed / 5 opened.