feat(M5): Final hardening, CI surface, and documentation closeout

.github/workflows/check-online.yml

@@ -0,0 +1,42 @@
+name: check-online
+
+# Runs full external link checking on a schedule and on manual trigger.
+# Kept separate from the main `check` workflow so everyday push/PR CI
+# is not slowed down or broken by transient network issues.
+
+on:
+  schedule:
+    # Every Monday at 09:00 UTC
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+jobs:
+  check-online:
+    name: check-online (ubuntu-latest)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: sudo apt-get update -q && sudo apt-get install -y -q shellcheck
+
+      - name: Install ripgrep
+        run: sudo apt-get install -y -q ripgrep
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: "10"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run full quality suite with external link checking
+        run: pnpm run verify:docs:online

.github/workflows/check.yml

@@ -0,0 +1,48 @@
+name: check
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  check:
+    name: check (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install shellcheck (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update -q && sudo apt-get install -y -q shellcheck
+
+      - name: Install shellcheck (macOS)
+        if: runner.os == 'macOS'
+        run: brew install shellcheck
+
+      - name: Install ripgrep (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get install -y -q ripgrep
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: "10"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run full quality suite (offline link-checking)
+        run: pnpm run check

CHANGELOG.md

@@ -5,6 +5,83 @@ Entries are milestone-scoped; stories within each milestone are listed for trace
 
 ---
 
+## M5 — Final hardening, CI surface, and documentation closeout
+
+### What changed in M5
+
+**S-501 — CI workflow added**
+
+`.github/workflows/check.yml` runs on every push and pull request against a
+matrix of `ubuntu-latest` and `macos-latest`. Each job:
+
+1. Installs `shellcheck` (apt on Ubuntu, brew on macOS).
+2. Installs `ripgrep` (apt on Ubuntu; pre-installed on macOS runners).
+3. Installs Node.js 22 and pnpm 10.
+4. Runs `pnpm install --frozen-lockfile`.
+5. Runs `pnpm run check` (full quality suite, offline link-checking).
+
+`.github/workflows/check-online.yml` runs `verify:docs:online` on a weekly
+schedule (Monday 09:00 UTC) and on manual `workflow_dispatch`. This keeps
+external link checking out of the push/PR critical path.
+
+**S-502 — Root README contributing section**
+
+`README.md` now includes a "Contributing / Development" section that names
+`pnpm run check` as the single quality gate, lists prerequisites, and links
+to `docs/DEVELOPMENT.md`.
+
+**S-503 — `docs/DEVELOPMENT.md` finalised**
+
+Added:
+
+- **"Adding a new agent variant"** recipe (6 steps from canonical source to CI).
+- **"Adding a new skill"** recipe (6 steps).
+- **"CI"** section describing both workflows and how to add new prerequisites.
+- **Permanent `check` contract** replacing the transitional M1 wording.
+- Cross-reference links to `.github/workflows/check.yml` and
+  `.github/workflows/check-online.yml`.
+
+**S-504 — Baseline report closed**
+
+`docs/CLEANUP-BASELINE.md` updated with a "Final state" section showing every
+baseline failure resolved, a baseline status summary table, and the
+post-M5 `pnpm run check` output.  The document is now closed.
+
+**S-505 — `package.json` file list synced**
+
+`docs/DEVELOPMENT.md` and `docs/REVIEWERS.md` added to the `files` array.
+All listed entries verified to exist in the post-M5 tree.
+
+**S-506 — Changelog extended (this entry)**
+
+**S-507 — Final green run confirmed**
+
+`pnpm run check` exits 0 on macOS 15 (arm64) with Node 22.14.0 and
+pnpm 10.18.1.  CI workflow exercises the same gate on both `ubuntu-latest`
+and `macos-latest`.
+
+### `pnpm run check` status after M5
+
+```text
+PASS  lint
+PASS  typecheck
+PASS  test
+PASS  verify:pi
+PASS  verify:reviewers
+PASS  verify:docs
+PASS  verify:generated
+```
+
+All checks green. CI enforces this on every push and PR.
+
+---
+
+## M4 — Shared-abstraction extraction and dead-code removal
+
+*See `docs/CLEANUP-BASELINE.md` § "Post-M4 state" for the full M4 delta.*
+
+---
+
 ## M3 — Shared-source generator for agent variants
 
 ### Package metadata change ⚠️

README.md

@@ -169,3 +169,20 @@ Additional pi-specific guidance lives in [docs/PI.md](docs/PI.md).
 
 For development prerequisites, quality tooling, and the `pnpm run check`
 contract, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+
+## Contributing / Development
+
+See **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** for the full development guide.
+
+Quick reference — the single quality gate every contributor must pass:
+
+```bash
+pnpm install
+pnpm run check      # lint · typecheck · test · verify:pi · verify:reviewers · verify:docs · verify:generated
+```
+
+Prerequisites: Node.js 20+, pnpm 10+, `shellcheck` (brew / apt), `ripgrep` (brew / apt).
+
+CI runs the same `pnpm run check` command on both `ubuntu-latest` and `macos-latest`
+(see `.github/workflows/check.yml`).  External link checking runs separately on a
+weekly schedule (`.github/workflows/check-online.yml`).

docs/CLEANUP-BASELINE.md

@@ -3,10 +3,9 @@
 Captured: 2026-05-03 · Platform: macOS (arm64, Apple Silicon) · Node 22.14.0 · pnpm 10.18.1
 
 This document records the as-is state of every quality check at the start of
-the refactor series.  The transitional `pnpm run check` contract allows the
-aggregate check to exit non-zero **only** on issues listed here.  Any failure
-not covered by this document represents a regression introduced by a later
-milestone.
+the refactor series.  All pre-existing failures listed here have since been
+resolved.  As of M5 `pnpm run check` exits **0** on a clean checkout.  Any
+failure now represents a regression and must be fixed before merge.
 
 ---
 
@@ -471,3 +470,89 @@ Overall exit: **0** — all checks green (no regressions from M3).
 | `pnpm run test:installer` (root scripts) | 80 |
 | `atlassian/shared/scripts` | 29 |
 | **Total** | **109** |
+
+---
+
+## Final state (post-M5) — CLOSED
+
+Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
+
+M5 added CI configuration, finalised documentation, closed out this baseline
+report, and locked in a permanently green `pnpm run check` gate.  No
+pre-existing failures remain open.
+
+### `pnpm run check` aggregate (post-M5 — macOS)
+
+```text
+PASS  lint
+PASS  typecheck
+PASS  test
+PASS  verify:pi
+PASS  verify:reviewers
+PASS  verify:docs
+PASS  verify:generated
+
+All checks passed.
+```
+
+Overall exit: **0** — all checks green (no regressions from M4).
+
+### What changed in M5
+
+- **S-501** — `.github/workflows/check.yml` added: matrix over `ubuntu-latest`
+  and `macos-latest`; installs `shellcheck` (apt/brew), `ripgrep` (apt), pnpm,
+  and Node.js 22; runs `pnpm run check`.
+- **S-501** — `.github/workflows/check-online.yml` added: weekly schedule +
+  `workflow_dispatch`; runs `verify:docs:online` for full external link checking.
+- **S-502** — Root `README.md` gained a "Contributing / Development" section
+  naming `pnpm run check` as the single quality gate and linking to
+  `docs/DEVELOPMENT.md`.
+- **S-503** — `docs/DEVELOPMENT.md` finalised: added "Adding a new agent",
+  "Adding a new skill", and "CI" sections; transitional contract replaced by
+  the permanent M5 contract; baseline links updated.
+- **S-504** — This file (`docs/CLEANUP-BASELINE.md`) closed out with the
+  "Final state" section.
+- **S-505** — Root `package.json` `files` list updated: `docs/DEVELOPMENT.md`
+  and `docs/REVIEWERS.md` added.
+- **S-506** — `CHANGELOG.md` extended with the M5 consolidated entry.
+- **S-507** — Final `pnpm run check` run confirmed green (output above).
+
+### Baseline status summary
+
+Every pre-existing failure recorded in this document is now **resolved**.
+No waivers are required.
+
+| Check | M1 status | Final status | Resolution |
+|-------|-----------|--------------|------------|
+| `lint` (ESLint) | FAIL — 2 errors | **PASS** | Fixed in M3 (S-302) |
+| `lint` (shellcheck) | FAIL — 7 findings | **PASS** | Fixed in M3 (S-302) |
+| `typecheck` | PASS | **PASS** | Never regressed |
+| `test` | PASS | **PASS** | Never regressed |
+| `verify:pi` | PASS | **PASS** | Portability hardened in M2 |
+| `verify:reviewers` | PASS | **PASS** | Never regressed |
+| `verify:docs` (markdownlint) | FAIL — 1160 errors | **PASS** | Fixed in M2 |
+| `verify:docs` (link-check) | PASS | **PASS** | Never regressed |
+| `verify:generated` | PASS (stub) | **PASS** | Real implementation in M3 |
+
+### Ubuntu smoke test
+
+The CI workflow (`.github/workflows/check.yml`) runs the same `pnpm run check`
+command on `ubuntu-latest`.  This replaces the Docker one-liner that was the
+only documented Ubuntu smoke test path in M1–M4.
+
+For local reproduction on Linux:
+
+```bash
+# Requires Docker
+docker run --rm \
+  -v "$PWD:/w" \
+  -w /w \
+  node:22-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 baseline report is now closed.  Future regressions must be caught by CI
+and fixed before merge; they should NOT reopen this document.*

docs/DEVELOPMENT.md

@@ -1,7 +1,7 @@
 # Development Guide — ai-coding-skills
 
-This document covers prerequisites, how to run checks locally, the M1 quality
-tooling, the workspace policy, and the transitional `pnpm run check` contract.
+This document covers prerequisites, how to run checks locally, the quality
+tooling, the workspace policy, and the `pnpm run check` contract.
 
 ## Prerequisites
 
@@ -154,22 +154,29 @@ 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)
+## `check` contract (final — M5)
 
-`pnpm run check` may exit non-zero in M1.  This is expected.  The contract is:
+`pnpm run check` is **fully green** on a clean checkout with the documented
+prerequisites installed.
 
-> `pnpm run check` exits non-zero **only** on issues recorded in
-> `docs/CLEANUP-BASELINE.md`.  Previously-green checks remain green.  No
-> violations are introduced by M1's own changes.
+```text
+PASS  lint
+PASS  typecheck
+PASS  test
+PASS  verify:pi
+PASS  verify:reviewers
+PASS  verify:docs
+PASS  verify:generated
+```
 
-**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.
+This is the only acceptable state for merge.  Any failure on a check not in
+`docs/CLEANUP-BASELINE.md` is a regression and must be fixed before merge.
 
-**M3 update:** `pnpm run check` is now **fully green**. All pre-existing lint
-violations have been fixed (2 ESLint errors, 7 shellcheck findings). The
-`verify:generated` check is now a real implementation (was a stub in M2).
+> **History:** In M1 the contract was transitional and allowed pre-existing
+> failures recorded in the baseline.  M2 fixed `verify:docs`.  M3 fixed
+> `lint` and promoted `verify:generated` from stub to real implementation.
+> M4 added abstractions without regressions.  M5 added CI and finalized docs.
+> The baseline is now closed out — see `docs/CLEANUP-BASELINE.md`.
 
 ## pnpm workspace policy (updated in M3)
 
@@ -210,12 +217,10 @@ config or generator is broken.
 
 ## How to interpret the baseline report
 
-See `docs/CLEANUP-BASELINE.md` for the full as-is capture.  When a CI run
-fails on a check, compare the output against the baseline:
-
-- If the failure matches a baseline entry → it is a known pre-existing issue.
-- If the failure does not appear in the baseline → it is a regression
-  introduced by recent changes and must be fixed before merge.
+See `docs/CLEANUP-BASELINE.md` for the historical as-is capture from M1.  That
+baseline is now **closed** — all pre-existing failures have been resolved.
+When a CI run fails on any check it is a regression and must be fixed before
+merge.
 
 ## How variants are generated (M3)
 
@@ -321,9 +326,114 @@ This replaces the previous non-unique `name` fields (`atlassian-skill-scripts`,
 `web-automation-scripts`).  These packages are private and are never published.
 See `CHANGELOG.md` for the full rename list.
 
+## Adding a new agent variant
+
+To add support for a brand-new agent (e.g. `mynewagent`) across all skills:
+
+1. **Create canonical source files** for every skill:
+
+   ```bash
+   mkdir -p skills/<skill>/_source/mynewagent
+   # Add SKILL.md (copy and adapt from an existing agent variant)
+   ```
+
+2. **Update the generator** (`scripts/generate-skills.mjs`):
+   - Add `"mynewagent"` to the `AGENTS` array (or the per-skill agent list).
+   - Ensure any agent-specific substitution logic is handled.
+
+3. **Regenerate all variants:**
+
+   ```bash
+   pnpm run sync:pi
+   pnpm run verify:generated     # must exit 0
+   ```
+
+4. **Update the workspace** (`pnpm-workspace.yaml`):
+   - Add entries for every `skills/<skill>/mynewagent/scripts` package that
+     has a `package.json` (e.g. atlassian and web-automation).
+
+5. **Update documentation:**
+   - Add a row to the skills table in `README.md`.
+   - Add a row to the reviewer matrix in `docs/REVIEWERS.md` if the agent
+     exposes a reviewer CLI.
+   - Add an install guide at `docs/MYNEWAGENT.md` and link it from
+     `docs/README.md`.
+   - Add the doc file to the `files` list in root `package.json`.
+
+6. **Verify the full suite:**
+
+   ```bash
+   pnpm install
+   pnpm run check
+   ```
+
+## Adding a new skill
+
+To add an entirely new skill (e.g. `my-skill`):
+
+1. **Create the canonical source tree:**
+
+   ```bash
+   mkdir -p skills/my-skill/_source/{claude-code,codex,cursor,opencode,pi}
+   # Add SKILL.md to each _source/<agent>/ directory
+   ```
+
+2. **Update the generator** (`scripts/generate-skills.mjs`):
+   - Add `"my-skill"` to the `SKILLS` array.
+   - Provide a `getSkillMeta(skill)` entry with agents list, source resolver,
+     and any extra files to copy (templates, scripts, etc.).
+
+3. **Regenerate:**
+
+   ```bash
+   pnpm run sync:pi
+   pnpm run verify:generated
+   ```
+
+4. **Add the pi-package entry** if the skill should be distributed via the
+   Pi package:
+   - Update `package.json` → `pi.skills` with the new path.
+   - Update the `files` array to include the new skill directory.
+
+5. **Write documentation** in `docs/MY-SKILL.md` and link from `docs/README.md`
+   and the skills table in `README.md`.
+
+6. **Run the full suite:** `pnpm run check`.
+
+## CI
+
+Two GitHub Actions workflows live in `.github/workflows/`:
+
+| File | Trigger | Purpose |
+|------|---------|---------|
+| `check.yml` | push, pull_request (all branches) | Full `pnpm run check` on `ubuntu-latest` **and** `macos-latest`. Offline link-checking (no network dependency). |
+| `check-online.yml` | weekly schedule (Mon 09:00 UTC) + `workflow_dispatch` | `pnpm run verify:docs:online` with full external link checking. |
+
+### What the `check` workflow does
+
+1. Checks out the repository.
+2. Installs `shellcheck` via `apt-get` (Ubuntu) or `brew` (macOS).
+3. Installs `ripgrep` via `apt-get` (Ubuntu only; pre-installed on macOS runners).
+4. Installs Node.js 22 via `actions/setup-node`.
+5. Installs pnpm 10 via `pnpm/action-setup`.
+6. Runs `pnpm install --frozen-lockfile`.
+7. Runs `pnpm run check` (the same command contributors run locally).
+
+The matrix runs both `ubuntu-latest` and `macos-latest` to guard against
+platform-specific regressions. Because M2 made all shell scripts portable
+across BSD and GNU coreutils, both runners should stay green.
+
+### Adding new prerequisites to CI
+
+If a new tool is required (e.g. a new binary called by a verify script),
+add the install step to **both** OS branches in `check.yml`. Document the
+new prerequisite in the Prerequisites table at the top of this file.
+
 ## Links
 
 - [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — as-is quality baseline
 - [README.md](../README.md) — project overview
 - [docs/README.md](./README.md) — documentation index
 - [CHANGELOG.md](../CHANGELOG.md) — milestone-by-milestone change record
+- [.github/workflows/check.yml](../.github/workflows/check.yml) — CI workflow
+- [.github/workflows/check-online.yml](../.github/workflows/check-online.yml) — weekly online link check

package.json

@@ -27,6 +27,8 @@
     "docs/PI-SUPERPOWERS.md",
     "docs/PI-COMMON-REVIEWER.md",
     "docs/WEB-AUTOMATION.md",
+    "docs/DEVELOPMENT.md",
+    "docs/REVIEWERS.md",
     "pi-package/skills",
     "skills/reviewer-runtime/pi",
     "scripts/install-pi-package.sh",