Add CI build check and stale-preview detection

Adds an always-runs ci-build.yml workflow that runs npm run build on
every PR, providing a meaningful required status check that catches
broken builds before merge. Unlike deploy.yml's build job (which only
runs on push to main) and pr-preview.yml (which is path-conditional),
this workflow fires on every PR and is therefore safe to mark as a
required check.

Updates pr-preview.yml to (1) include the head commit SHA in the
success comment so reviewers can verify which commit they are seeing,
and (2) on build failure, append a 'preview is stale' warning to the
sticky comment so reviewers cannot unknowingly click through to
outdated content. If no previous successful preview exists, post a
fresh 'preview build failed' comment instead.

Documents the new workflow in planning/01-repo-implementation.md and
adds an architectural note about which checks are appropriate as
required status checks on main.

Author: AdamGohs

.github/workflows/ci-build.yml

@@ -0,0 +1,21 @@
+name: CI Build
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: CI Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build

.github/workflows/pr-preview.yml

@@ -50,12 +50,33 @@ jobs:
           script: |
             const prNumber = context.issue.number;
             const url = `https://usace-rmc.github.io/RMC-Software-Documentation-Previews/pr-${prNumber}/`;
+            const sha = context.payload.pull_request.head.sha.substring(0, 7);
             const marker = '<!-- pr-preview-bot-comment -->';
-            const body = `${marker}\n\n📄 **Preview deployed**\n\n${url}\n\n_This preview updates automatically when new commits are pushed. Deleted when the PR closes._`;
+            const body = `${marker}\n\n📄 **Preview deployed** for commit \`${sha}\`\n\n${url}\n\n_This preview updates automatically when new commits are pushed. Deleted when the PR closes._`;
             const comments = await github.rest.issues.listComments({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber });
             const existing = comments.data.find(c => c.user.type === 'Bot' && c.body.includes(marker));
             if (existing) {
               await github.rest.issues.updateComment({ owner: context.repo.owner, repo: context.repo.repo, comment_id: existing.id, body });
             } else {
               await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber, body });
             }
+      - name: Mark preview as stale on failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const prNumber = context.issue.number;
+            const sha = context.payload.pull_request.head.sha.substring(0, 7);
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const marker = '<!-- pr-preview-bot-comment -->';
+            const comments = await github.rest.issues.listComments({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber });
+            const existing = comments.data.find(c => c.user.type === 'Bot' && c.body.includes(marker));
+            if (existing) {
+              // Strip any prior stale warning before appending a fresh one
+              const cleanBody = existing.body.split('\n\n⚠️')[0];
+              const newBody = `${cleanBody}\n\n⚠️ **Preview build failed on commit \`${sha}\`** — the preview URL above is **stale** and reflects an earlier successful build. Do not rely on it as an accurate representation of this PR's current state. [View workflow logs](${runUrl}).`;
+              await github.rest.issues.updateComment({ owner: context.repo.owner, repo: context.repo.repo, comment_id: existing.id, body: newBody });
+            } else {
+              const body = `${marker}\n\n❌ **Preview build failed** on commit \`${sha}\`\n\nThe site failed to build for this PR, so there is no preview to view. [View workflow logs](${runUrl}).`;
+              await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber, body });
+            }

planning/01-repo-implementation.md

@@ -31,6 +31,7 @@ This document describes every structural change to the `usace-rmc/rmc-software-d
 - The AI technical edit stage advances when the author checks a task list checkbox in the PR description, not when a reviewer clicks approve.
 - The stage progression workflow only auto-processes PRs whose branch name starts with `docs/`. PRs from any other branch (infrastructure, tooling, dependency bumps, etc.) are silently ignored — no labels, no comments, no review-process noise. A site admin can still pull any PR into the review process by manually applying a `lane:*` label, which is the escape hatch for mis-named branches or one-off cases.
 - The PR preview workflow (`pr-preview.yml`) uses a broader path-based trigger and will build a preview for any PR that touches doc-relevant files, regardless of branch prefix. This is intentional: previews are useful for verifying non-doc changes (e.g., a config tweak) even when no formal review is required.
+- The required-status-checks list on `main` should contain only checks that always run on PRs. The right checks to require are `CI Build` (from `ci-build.yml`, runs on every PR) and `Manage review stage` (from `stage-progression.yml`, runs on every PR and silent-exits on non-`docs/` branches). **Do not add `Build site` (from `deploy.yml`) or `Build and deploy preview` (from `pr-preview.yml`) as required checks** — the former never runs on PRs and the latter only runs on path-matching PRs, so requiring them blocks PRs forever waiting for results that aren't coming.
 
 ## Scope
 
@@ -316,7 +317,35 @@ jobs:
           fi
 ```
 
-### 3.6 `.github/workflows/stage-progression.yml`
+### 3.6 `.github/workflows/ci-build.yml`
+
+Required-status-check workflow that runs on every PR. Builds the site with `npm run build` to catch broken builds before merge. Unlike `deploy.yml` (which only runs on push to main and therefore can't be a meaningful PR check) and `pr-preview.yml` (which is path-conditional and skips non-content PRs), this workflow always runs and is therefore safe to mark as a required check on `main`.
+
+```yaml
+name: CI Build
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: CI Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+```
+
+### 3.7 `.github/workflows/stage-progression.yml`
 
 ```yaml
 name: Stage Progression
@@ -631,9 +660,11 @@ For each finding, produce:
 - [ ] `.github/CODEOWNERS`
 - [ ] `.github/pull_request_template.md` — includes technical edit checkbox
 - [ ] `.github/workflows/deploy.yml` — with `workflow_dispatch` + `ref` input
-- [ ] `.github/workflows/pr-preview.yml`
+- [ ] `.github/workflows/pr-preview.yml` — with stale-marker on build failure
 - [ ] `.github/workflows/pr-preview-cleanup.yml`
+- [ ] `.github/workflows/ci-build.yml` — always-runs PR build check
 - [ ] `.github/workflows/stage-progression.yml` — Lead Civil + AI editor + checkbox detection
+- [ ] Branch protection on `main` requires `CI Build` and `Manage review stage` (not `Build site` or `Build and deploy preview` — those are not appropriate as required PR checks)
 - [ ] `.github/ai-review/technical-editor-prompt.md`
 - [ ] `.claude/skills/new-revision/SKILL.md`
 - [ ] `.claude/skills/technical-edit/SKILL.md`