@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/audit-tolerance.cjs

@@ -0,0 +1,77 @@
+// deliver-great-systems/bin/lib/audit-tolerance.cjs
+// REL-10: cross-reference matrix for /dgs:audit-milestone status determination.
+// Extends the existing 5d matrix with soft-tolerance for empty requirements_completed
+// when VERIFICATION explicitly lists the ID and status: passed.
+//
+// Soft-warning channel: 'summary-frontmatter-empty-but-verified' — distinct from
+// real partials. Surfaces under audit JSON `soft_warnings.summary_frontmatter_empty_but_verified`,
+// NOT under `gaps.requirements`. Removal trigger: 3 consecutive milestones ship
+// with zero soft-warnings → drop the tolerance row, restore strict default.
+
+const SOFT_WARNING_EMPTY_BUT_VERIFIED = 'summary-frontmatter-empty-but-verified';
+
+function applyMatrix(input) {
+  const {
+    verificationStatus,
+    requirementsClaimed = [],
+    summaryRequirementsCompleted = [],
+    reqId,
+    strictAudit = false,
+  } = input;
+
+  if (!reqId) {
+    return { status: 'unsatisfied', softWarning: null };
+  }
+
+  // gaps_found short-circuits everything — VERIFICATION explicitly failed.
+  if (verificationStatus === 'gaps_found') {
+    return { status: 'unsatisfied', softWarning: null };
+  }
+
+  const summaryListsId = summaryRequirementsCompleted.includes(reqId);
+  const verificationListsId = requirementsClaimed.includes(reqId);
+
+  // Happy path: VERIFICATION passed AND SUMMARY explicitly populated.
+  if (verificationStatus === 'passed' && summaryListsId) {
+    return { status: 'satisfied', softWarning: null };
+  }
+
+  // Tolerance path: VERIFICATION passed AND lists ID, SUMMARY empty/missing, NOT strict.
+  if (
+    verificationStatus === 'passed' &&
+    !summaryListsId &&
+    verificationListsId &&
+    !strictAudit
+  ) {
+    return { status: 'satisfied', softWarning: SOFT_WARNING_EMPTY_BUT_VERIFIED };
+  }
+
+  // Strict path: same input as tolerance path but --strict-audit forces partial.
+  if (
+    verificationStatus === 'passed' &&
+    !summaryListsId &&
+    verificationListsId &&
+    strictAudit
+  ) {
+    return { status: 'partial', softWarning: null };
+  }
+
+  // VERIFICATION passed but does NOT list the ID, SUMMARY empty → real partial.
+  // (Tolerance must NOT mask this — the safety net per spec.)
+  if (verificationStatus === 'passed' && !summaryListsId && !verificationListsId) {
+    return { status: 'partial', softWarning: null };
+  }
+
+  // VERIFICATION missing → unsatisfied (orphan-style).
+  if (verificationStatus === 'missing') {
+    if (summaryListsId) {
+      return { status: 'partial', softWarning: null };
+    }
+    return { status: 'unsatisfied', softWarning: null };
+  }
+
+  // Default fallthrough.
+  return { status: 'unsatisfied', softWarning: null };
+}
+
+module.exports = { applyMatrix, SOFT_WARNING_EMPTY_BUT_VERIFIED };

package/deliver-great-systems/bin/lib/audit-tolerance.test.cjs

@@ -0,0 +1,101 @@
+// deliver-great-systems/bin/lib/audit-tolerance.test.cjs
+// REL-10 regression test scaffold — initially RED. Turns GREEN after plan 03
+// extends the audit cross-reference matrix with soft-tolerance + adds
+// --strict-audit flag handling.
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+// REL-10 surfaces a function applyMatrix(input) -> { status, softWarning? }
+// in a new module bin/lib/audit-tolerance.cjs. Plan 03 implements it.
+// applyMatrix input shape:
+//   { verificationStatus: 'passed'|'gaps_found'|'missing',
+//     requirementsClaimed: string[],   // from VERIFICATION.md frontmatter
+//     summaryRequirementsCompleted: string[], // from SUMMARY.md frontmatter (canonical key)
+//     reqId: string,                   // requirement ID under evaluation
+//     strictAudit: boolean             // --strict-audit flag
+//   }
+// applyMatrix output:
+//   { status: 'satisfied'|'partial'|'unsatisfied',
+//     softWarning: 'summary-frontmatter-empty-but-verified' | null
+//   }
+
+function getApplyMatrix() {
+  try {
+    return require('./audit-tolerance.cjs').applyMatrix;
+  } catch (err) {
+    assert.fail('REL-10 audit-tolerance module not yet implemented: bin/lib/audit-tolerance.cjs (plan 03 task)');
+  }
+}
+
+test('REL-10: empty SUMMARY + VERIFICATION lists ID + status passed → satisfied + soft-warning', () => {
+  const applyMatrix = getApplyMatrix();
+  const result = applyMatrix({
+    verificationStatus: 'passed',
+    requirementsClaimed: ['TEST-01'],
+    summaryRequirementsCompleted: [],
+    reqId: 'TEST-01',
+    strictAudit: false,
+  });
+
+  assert.strictEqual(result.status, 'satisfied');
+  assert.strictEqual(result.softWarning, 'summary-frontmatter-empty-but-verified');
+});
+
+test('REL-10: --strict-audit preserves old strict behaviour (empty SUMMARY → partial)', () => {
+  const applyMatrix = getApplyMatrix();
+  const result = applyMatrix({
+    verificationStatus: 'passed',
+    requirementsClaimed: ['TEST-01'],
+    summaryRequirementsCompleted: [],
+    reqId: 'TEST-01',
+    strictAudit: true,
+  });
+
+  assert.strictEqual(result.status, 'partial');
+  // soft-warning may be null OR may still flag; spec is silent; canonical: null under strict
+  assert.strictEqual(result.softWarning || null, null);
+});
+
+test('REL-10: tolerance does NOT mask real partials (VERIFICATION not listing ID still partial)', () => {
+  const applyMatrix = getApplyMatrix();
+  const result = applyMatrix({
+    verificationStatus: 'passed',
+    requirementsClaimed: ['OTHER-01'], // does NOT list TEST-01
+    summaryRequirementsCompleted: [],
+    reqId: 'TEST-01',
+    strictAudit: false,
+  });
+
+  assert.strictEqual(result.status, 'partial');
+  assert.strictEqual(result.softWarning || null, null);
+});
+
+test('REL-10: gaps_found VERIFICATION → unsatisfied regardless of SUMMARY shape', () => {
+  const applyMatrix = getApplyMatrix();
+  const result = applyMatrix({
+    verificationStatus: 'gaps_found',
+    requirementsClaimed: ['TEST-01'],
+    summaryRequirementsCompleted: ['TEST-01'],
+    reqId: 'TEST-01',
+    strictAudit: false,
+  });
+
+  assert.strictEqual(result.status, 'unsatisfied');
+});
+
+test('REL-10: SUMMARY explicitly populated + VERIFICATION passed → satisfied (no soft-warning)', () => {
+  const applyMatrix = getApplyMatrix();
+  const result = applyMatrix({
+    verificationStatus: 'passed',
+    requirementsClaimed: ['TEST-01'],
+    summaryRequirementsCompleted: ['TEST-01'],
+    reqId: 'TEST-01',
+    strictAudit: false,
+  });
+
+  assert.strictEqual(result.status, 'satisfied');
+  assert.strictEqual(result.softWarning || null, null);
+});
+
+// REL-10 sentinel — flag this file as a Wave-0 RED scaffold for plan 03.