ci: add coverage enforcement script and workflow; document adaptation in README (P3-20)

Author: pidster

.github/workflows/coverage.yml

@@ -0,0 +1,39 @@
+name: Coverage Enforcement
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  enforce-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies (if package.json exists)
+        run: |
+          if [ -f package.json ]; then npm ci; fi
+
+      - name: Run tests with coverage (Node/Jest example if present)
+        run: |
+          if [ -f package.json ] && npx --yes --quiet jest --help > /dev/null 2>&1; then \
+            npx jest --coverage --coverageReporters=json-summary || true; \
+          fi
+
+      - name: Fail if no coverage output found
+        run: |
+          if [ ! -f coverage/coverage-summary.json ]; then \
+            echo "No coverage summary found; skipping enforcement (pass)."; \
+            exit 0; \
+          fi
+
+      - name: Enforce unified coverage thresholds
+        run: |
+          node scripts/enforce-coverage.js --file coverage/coverage-summary.json

README.md

@@ -270,4 +270,43 @@ flowchart LR
 - Templates (`adr-template.md`, `prd-template.md`) are referenced by both instructions and prompts
 - Directory structures are consistently referenced across multiple configuration files
 
-This hierarchy shows how the repository maintains consistency through strategic cross-referencing, with clear patterns for documentation workflows, planning processes, and configuration management.
+This hierarchy shows how the repository maintains consistency through strategic cross-referencing, with clear patterns for documentation workflows, planning processes, and configuration management.
+ 
+## Appendix: SSOT Source Map
+
+Authoritative single sources of truth (SSOT) for key policies and templates. Prefer linking to these instead of duplicating content.
+
+- Core policies and workflow
+    - Copilot instructions (SSOT): `.github/copilot-instructions.md`
+        - Quality & Coverage Policy: `.github/copilot-instructions.md#quality-policy`
+
+        ### CI Coverage Enforcement (template)
+
+        This repo includes a minimal coverage enforcement workflow (`.github/workflows/coverage.yml`) and script (`scripts/enforce-coverage.js`) aligned with the Quality & Coverage Policy:
+        - Global ≥ 90%; core modules ≥ 95%; integrations ≥ 85%; critical/hot/error/security paths 100%.
+        - The sample job looks for a Jest `coverage/coverage-summary.json`. Adapt the test step for your stack (e.g., Python `coverage.json`, Java `jacoco.xml` converted to JSON) and point the script to the generated summary.
+        - Branching & Workflow: see "Project Methodologies" in the same file
+        - Naming & Commit Conventions: see corresponding sections in the same file
+- Engineering guidelines
+    - Code review checklist (SSOT): `docs/engineering/code-review-guidelines.md#code-review-checklist`
+    - Pull request guidelines: `docs/engineering/pull-request-guidelines.md`
+- Documentation
+    - Docs authoring rules (SSOT): `.github/instructions/docs.instructions.md`
+    - Documentation flow anchor: `.github/instructions/docs.instructions.md#documentation-process-flow`
+- Testing
+    - BDD feature guidance (SSOT): `.github/instructions/bdd-tests.instructions.md`
+    - Tester chat mode (enforces policy): `.github/chatmodes/Tester.chatmode.md`
+- Backend
+    - Backend instructions (SSOT): `.github/instructions/backend.instructions.md`
+    - Architecture: `.github/instructions/backend.instructions.md#backend-architecture`
+    - Error handling: `.github/instructions/backend.instructions.md#backend-error-handling`
+    - Observability: `.github/instructions/backend.instructions.md#backend-observability`
+    - Security: `.github/instructions/backend.instructions.md#backend-security`
+- Planning
+    - Plan template (SSOT): `plans/plan-template.md`
+    - Small plan example: `plans/examples/plan-small.md`
+    - TODO (work queue): `plans/TODO.md`
+
+Notes:
+- Chat modes and prompts should reference these SSOT files. Avoid duplicating numeric thresholds, templates, or process steps in multiple places.
+- CI tasks (if added) should validate adherence to SSOT anchors where practical.

scripts/enforce-coverage.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/*
+Simple coverage enforcement script.
+- Reads a JSON summary from stdin or a file (istanbul/nyc, jest --coverage, etc.)
+- Enforces global >= 90%
+- Enforces core modules >= 95% (by path includes /src/core or /core/)
+- Enforces integrations/adapters >= 85% (by path includes /adapters or /integrations/)
+- Enforces 100% for files matched as hot paths or error/security (by filename hints)
+Exit non-zero on failure with a readable summary.
+*/
+
+const fs = require('fs');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const params = { file: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--file' && args[i + 1]) {
+      params.file = args[i + 1];
+      i++;
+    }
+  }
+  return params;
+}
+
+function loadSummary(file) {
+  const input = file ? fs.readFileSync(file, 'utf8') : fs.readFileSync(0, 'utf8');
+  return JSON.parse(input);
+}
+
+function pct(n) { return Math.round(n * 10000) / 100; }
+
+function classifyFile(path) {
+  const p = path.toLowerCase();
+  if (p.includes('/core/') || p.includes('/src/core/')) return 'core';
+  if (p.includes('/adapters/') || p.includes('/integrations/')) return 'integration';
+  return 'other';
+}
+
+function isCritical(path) {
+  const p = path.toLowerCase();
+  return (
+    p.includes('hot') ||
+    p.includes('critical') ||
+    p.includes('auth') ||
+    p.includes('security') ||
+    p.includes('error') ||
+    p.includes('exception')
+  );
+}
+
+function check(summary) {
+  const metrics = summary.total || summary;
+  const globalLines = metrics.lines.pct || metrics.lines.covered / metrics.lines.total * 100;
+  const globalPass = globalLines >= 90;
+
+  const failures = [];
+  if (!globalPass) failures.push(`Global lines coverage ${pct(globalLines)}% < 90%`);
+
+  // Per-file checks if available
+  if (summary && typeof summary === 'object') {
+    for (const [file, m] of Object.entries(summary)) {
+      if (file === 'total' || !m || !m.lines) continue;
+      const filePct = m.lines.pct || (m.lines.covered / m.lines.total * 100);
+      const cls = classifyFile(file);
+      if (isCritical(file) && filePct < 100) {
+        failures.push(`Critical path not fully covered: ${file} ${pct(filePct)}% < 100%`);
+        continue;
+      }
+      if (cls === 'core' && filePct < 95) {
+        failures.push(`Core module below 95%: ${file} ${pct(filePct)}%`);
+      } else if (cls === 'integration' && filePct < 85) {
+        failures.push(`Integration below 85%: ${file} ${pct(filePct)}%`);
+      }
+    }
+  }
+
+  return failures;
+}
+
+function main() {
+  try {
+    const { file } = parseArgs();
+    const summary = loadSummary(file);
+    const failures = check(summary);
+    if (failures.length) {
+      console.error('Coverage enforcement failed:\n- ' + failures.join('\n- '));
+      process.exit(1);
+    }
+    console.log('Coverage enforcement passed.');
+  } catch (e) {
+    console.error('Error running coverage enforcement:', e.message);
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main();
+}