chore(dx): unify local and CI verify pipeline

.github/pull_request_template.md

@@ -8,11 +8,10 @@
 
 ## Validation
 
-- [ ] `npm run lint`
-- [ ] `npm run typecheck`
-- [ ] `npm test`
+- [ ] `npm run verify`
+- [ ] `npm run verify:ci`
 - [ ] `npm test -- test/documentation.test.ts`
-- [ ] `npm run build`
+- [ ] if triaging failures, validated component gates: `npm run lint`, `npm run verify:repo`, `npm run verify:quality`, `npm run typecheck`, `npm test`, `npm run build`
 
 ## Docs and Governance Checklist
 

.github/workflows/ci.yml

@@ -8,12 +8,16 @@ on:
 
 jobs:
   test:
-    name: Test on Node.js ${{ matrix.node-version }}
-    runs-on: ubuntu-latest
+    name: Test on Node.js ${{ matrix.node-version }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
 
     strategy:
       matrix:
         node-version: [20.x, 22.x]
+        os: [ubuntu-latest]
+        include:
+          - node-version: 20.x
+            os: windows-latest
 
     steps:
       - name: Checkout code
@@ -28,28 +32,13 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Repository hygiene check
-        run: npm run clean:repo:check
-
-      - name: Security audit (CI policy)
-        run: npm run audit:ci
-
-      - name: Lockfile floor guard
-        run: npm run test -- test/lockfile-version-floor.test.ts
+      - name: Run CI verify pipeline
+        run: npm run verify:ci
 
       - name: Security audit (full dependency tree, non-blocking)
         continue-on-error: true
         run: npm run audit:all
 
-      - name: Run type check
-        run: npm run typecheck
-
-      - name: Run tests with coverage
-        run: npm run coverage
-
-      - name: Build
-        run: npm run build
-
   lint:
     name: Lint
 

CONTRIBUTING.md

@@ -23,14 +23,15 @@ If a proposal conflicts with OpenAI policy boundaries, it will be declined.
 
 ```bash
 npm ci
-npm run typecheck
-npm run lint
-npm test
-npm run build
+npm run verify
 ```
 
 Node requirement: `>=18`.
 
+`npm run verify` runs the full local gate: `npm run lint`, `npm run verify:repo`, and
+`npm run verify:quality` (`npm run typecheck` + `npm run coverage`, where coverage already
+runs `npm run build`).
+
 ---
 
 ## Development Standards
@@ -56,10 +57,15 @@ Documentation requirements for behavior changes:
 1. Create a focused branch from `main`.
 2. Keep commits atomic and reviewable.
 3. Run full local gate:
-   - `npm run typecheck`
-   - `npm run lint`
-   - `npm test`
-   - `npm run build`
+   - `npm run verify`
+   - `npm run test -- test/documentation.test.ts`
+   - if triaging failures, run component gates directly:
+     - `npm run lint`
+     - `npm run verify:repo`
+     - `npm run verify:quality`
+     - `npm run typecheck`
+     - `npm test`
+     - `npm run build`
 4. Include command output evidence in the PR description.
 5. Document behavior changes and migration notes when needed.
 6. Ensure no secrets or local runtime data are committed.
@@ -116,4 +122,4 @@ Unacceptable behavior:
 
 ## License
 
-By contributing, you agree contributions are licensed under the project license in [LICENSE](LICENSE).
+By contributing, you agree contributions are licensed under the project license in [LICENSE](LICENSE).

docs/development/TESTING.md

@@ -19,6 +19,13 @@ Coverage thresholds in `vitest.config.ts`: statements/branches/functions/lines >
 
 ## Core Commands
 
+```bash
+npm run verify
+npm run verify:ci
+```
+
+Component commands:
+
 ```bash
 npm run typecheck
 npm run lint
@@ -39,11 +46,9 @@ npm run bench:edit-formats:smoke
 
 ## Recommended Local Gate Before PR
 
-1. `npm run typecheck`
-2. `npm run lint`
-3. `npm test`
-4. `npm run build`
-5. run docs command checks for newly documented command paths
+1. `npm run verify`
+2. `npm run test -- test/documentation.test.ts`
+3. run docs command checks for newly documented command paths
 
 * * *
 

package.json

@@ -61,6 +61,10 @@
     "bench:runtime-path:quick": "node scripts/benchmark-runtime-path.mjs",
     "test:coverage": "vitest run --coverage",
     "coverage": "npm run build && vitest run --coverage",
+    "verify:repo": "npm run clean:repo:check && npm run audit:ci && npm run test -- test/lockfile-version-floor.test.ts",
+    "verify:quality": "npm run typecheck && npm run coverage",
+    "verify": "npm run lint && npm run verify:repo && npm run verify:quality",
+    "verify:ci": "npm run verify:repo && npm run verify:quality",
     "audit:prod": "npm audit --omit=dev --audit-level=high",
     "audit:all": "npm audit --audit-level=high",
     "audit:dev:allowlist": "node scripts/audit-dev-allowlist.js",

test/documentation.test.ts

@@ -254,6 +254,18 @@ describe('Documentation Integrity', () => {
     expect(changelog).not.toContain('## [4.');
   });
 
+  it('keeps verify script contract aligned across package scripts and CI wiring', () => {
+    const pkg = JSON.parse(read('package.json')) as { scripts?: Record<string, string> };
+    const scripts = pkg.scripts ?? {};
+
+    expect(scripts['verify']).toBe('npm run lint && npm run verify:repo && npm run verify:quality');
+    expect(scripts['verify:repo']).toBe(
+      'npm run clean:repo:check && npm run audit:ci && npm run test -- test/lockfile-version-floor.test.ts',
+    );
+    expect(scripts['verify:quality']).toBe('npm run typecheck && npm run coverage');
+    expect(scripts['verify:ci']).toBe('npm run verify:repo && npm run verify:quality');
+  });
+
   it('keeps legacy pre-0.1 archive headings in descending semver order', () => {
     const archive = read('docs/releases/legacy-pre-0.1-history.md');
     const versions = [...archive.matchAll(/^## \[(\d+\.\d+\.\d+)\] - /gm)].map((match) => match[1]);
@@ -325,6 +337,8 @@ describe('Documentation Integrity', () => {
 
     const prBody = read(prTemplate);
     expect(prBody).toContain('npm run lint');
+    expect(prBody).toContain('npm run verify:repo');
+    expect(prBody).toContain('npm run verify:quality');
     expect(prBody).toContain('npm run typecheck');
     expect(prBody).toContain('npm test');
     expect(prBody).toContain('npm test -- test/documentation.test.ts');
@@ -339,6 +353,8 @@ describe('Documentation Integrity', () => {
     expect(contributing).toContain('pull request process');
     expect(contributing).toContain('npm run typecheck');
     expect(contributing).toContain('npm run lint');
+    expect(contributing).toContain('npm run verify:repo');
+    expect(contributing).toContain('npm run verify:quality');
     expect(contributing).toContain('npm test');
     expect(contributing).toContain('npm run build');
   });