feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

docs/DEVELOPMENT.md

@@ -40,7 +40,8 @@ pnpm run check
 | `pnpm run lint:fix` | Auto-fix ESLint + Prettier (do not run on pre-existing code until M2) |
 | `pnpm run typecheck` | TypeScript `tsc --noEmit` in workspace packages |
 | `pnpm run test` | Run all tests (root + workspace packages) |
-| `pnpm run verify:docs` | markdownlint + offline link-check |
+| `pnpm run verify:docs` | markdownlint + offline link-check + docs-flow verifier |
+| `pnpm run verify:docs:online` | Same as `verify:docs` but with full external link checking |
 | `pnpm run verify:generated` | Assert generated output freshness (stub; fleshed out in M3) |
 | `pnpm run check` | Aggregate: run every gate above and report a summary |
 
@@ -100,6 +101,59 @@ agent-variant directories) and runs shellcheck on each.
 The wrapper exits with code **2** (not 1) when shellcheck is missing, so CI
 can distinguish "shellcheck absent" from "shellcheck found violations".
 
+## Cross-platform shell support (M2)
+
+All shell scripts under `scripts/` and `skills/reviewer-runtime/` that are
+exercised by `verify:pi`, `verify:reviewers`, `sync:pi`, and `test:installer`
+must work on both **macOS** (BSD userland) and **Ubuntu/Debian** (GNU
+userland) without modification.
+
+### BSD vs GNU differences encountered
+
+| Feature | macOS (BSD) | Linux (GNU) | Portable form |
+|---------|-------------|-------------|---------------|
+| `stat` permissions | `stat -f '%Lp' <path>` | `stat -c '%a' <path>` | `portable_stat_perms` helper |
+| herestrings (`<<<`) | supported (bash) | supported (bash) | OK (scripts use `#!/usr/bin/env bash`) |
+| `find -E` (extended regex) | macOS-only | not available | use `grep` or POSIX `-name` |
+| `sed -i ''` | macOS form | use `sed -i` on Linux | detect or avoid in-place sed |
+| `date -j` (date arithmetic) | macOS-only | use `date -d` on Linux | Node helper or `date +%s` |
+| `readlink -f` | not on macOS by default | GNU standard | `realpath` or `cd && pwd` |
+
+### `scripts/lib/portable.sh`
+
+A shared helper that abstracts the two known BSD/GNU divergences hit in
+this repo:
+
+```bash
+# Source from any script that needs portable stat
+# shellcheck source=lib/portable.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/portable.sh"
+
+# Returns octal permission string: e.g. "755"
+portable_stat_perms "$path"
+```
+
+The `shellcheck` wrapper passes `-x --source-path=SCRIPTDIR` so source
+directives resolve relative to the script file, not the working directory.
+
+### How to run the Ubuntu smoke test locally
+
+```bash
+# Requires Docker
+docker run --rm \
+  -v "$PWD:/w" \
+  -w /w \
+  node:20-bookworm \
+  bash -lc 'apt-get update -q && apt-get install -y -q shellcheck ripgrep python3 \
+            && corepack enable \
+            && pnpm install --frozen-lockfile \
+            && pnpm run check'
+```
+
+This runs the full `pnpm run check` suite (lint, typecheck, test, verify:pi,
+verify:reviewers, verify:docs, verify:generated) inside a clean Debian Bookworm
+container with Node 20.
+
 ## Transitional `check` contract (M1)
 
 `pnpm run check` may exit non-zero in M1.  This is expected.  The contract is:
@@ -108,18 +162,10 @@ can distinguish "shellcheck absent" from "shellcheck found violations".
 > `docs/CLEANUP-BASELINE.md`.  Previously-green checks remain green.  No
 > violations are introduced by M1's own changes.
 
-The current baseline failures are:
-
-1. `lint` — 2 ESLint violations in existing root scripts; 7 shellcheck
-   findings in existing `.sh` files.
-2. `verify:docs` — 1160 markdownlint violations in pre-existing docs and
-   `SKILL.md` files.
-
-All other checks (`typecheck`, `test`, `verify:pi`, `verify:reviewers`,
-`verify:generated`) pass with EXIT 0.
-
-Once later milestones fix the baseline violations, `pnpm run check` will
-reach EXIT 0 and the transitional contract expires.
+**M2 update:** `verify:docs` is now green. `lint` still fails on the same
+2 pre-existing ESLint violations and 7 pre-existing shellcheck findings
+documented in `docs/CLEANUP-BASELINE.md`. Those will be fixed in a dedicated
+cleanup pass. No violations were introduced by M2.
 
 ## pnpm workspace policy (M1 exclusion-only)