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

2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
@@ -290,3 +290,56 @@ pre-existing and documented in this file.

 *This file is generated once (M1) and updated only when a subsequent milestone
 changes the baseline status of a check.*
+
+---
+
+## Post-M2 state
+
+Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
+
+M2 resolved all `verify:docs` violations and the `verify:pi` portability
+issue (`stat -f` BSD-ism in `scripts/verify-pi-resources.sh`).
+
+### `pnpm run check` aggregate (post-M2)
+
+```text
+FAIL  lint            (exit 1) — same 2 ESLint + 7 shellcheck pre-existing violations (§4a, §4b)
+PASS  typecheck
+PASS  test
+PASS  verify:pi
+PASS  verify:reviewers
+PASS  verify:docs      (was FAIL in M1; now clean)
+PASS  verify:generated (stub)
+```
+
+Overall exit: **1** — only `lint` still fails on pre-existing violations.
+`verify:docs` is now green (0 markdownlint errors, offline link-check clean,
+docs-flow verifier passes).
+
+### What changed in M2
+
+- `scripts/lib/portable.sh` added with `portable_stat_perms` helper.
+- `scripts/verify-pi-resources.sh` updated to use `portable_stat_perms`
+  (replaces `stat -f '%Lp'` BSD-only call).
+- `scripts/lib/run-shellcheck.mjs` updated to pass `-x --source-path=SCRIPTDIR`
+  so shellcheck follows `source` directives correctly on both platforms.
+- `skills/.markdownlint.jsonc` added to disable MD013 and MD024 for
+  agent-facing SKILL.md files.
+- All 1160 M1 markdownlint violations resolved (auto-fix + targeted edits).
+- `docs/README.md` reorganized into ordered reading flow.
+- `README.md` layout section updated to reflect actual repo tree.
+- `docs/REVIEWERS.md` added as canonical reviewer CLI matrix.
+- `docs/TELEGRAM-NOTIFICATIONS.md` extended with Pi section.
+- `docs/CREATE-PLAN.md`, `docs/IMPLEMENT-PLAN.md`, `docs/DO-TASK.md` updated
+  with REVIEWERS.md references and unique variant headings.
+- OpenCode reviewer branches added to `skills/create-plan/opencode/SKILL.md`
+  and `skills/implement-plan/opencode/SKILL.md`.
+- `scripts/verify-docs-flow.mjs` implemented and wired into `verify:docs`.
+- `pnpm run verify:docs:online` added for external link checks.
+
+### Ubuntu smoke note
+
+No Docker/Ubuntu run was available at M2 capture time. The portability
+fix (`portable_stat_perms`) replaces the only identified BSD-ism. The
+Ubuntu Docker command is documented in
+[DEVELOPMENT.md](./DEVELOPMENT.md#cross-platform-shell-support-m2).