@clear-capabilities/agentic-security-scanner 0.143.0 → 0.144.0

package/src/posture/encryption-provider.js

@@ -0,0 +1,205 @@
+// FR-705 (assurance-hardening PRD): "Encrypt state classes marked
+// confidential when an encryption provider is configured or required |
+// Required encryption absence fails before sensitive state is written."
+//
+// SCOPE (Phase 1 of a deliberately staged rollout — see this module's own
+// header for what is and is not covered, and D-0039-style honesty about
+// what remains):
+//
+//   - Confidentiality is a NEW `confidential: true` field on specific
+//     artifact-registry.js entries (see that module for the exact list and
+//     the reasoning for each). `last-scan.json`/`findings.json` are
+//     DELIBERATELY EXCLUDED from Phase 1: dozens of commands read them
+//     directly as plain JSON, so encrypting them is a much larger,
+//     separate migration (every reader needs a decrypt-on-read hook) —
+//     doing that alongside a handful of narrow, low-traffic audit/evidence
+//     artifacts in one pass would repeat exactly the "large, structurally-
+//     coupled epic attempted in one unplanned cycle" mistake this session
+//     has deliberately avoided elsewhere (see D-0028, D-0039).
+//   - ONE provider is implemented: 'local-key' — AES-256-GCM with a
+//     per-install key generated the first time encryption is actually
+//     used, stored at the same $XDG_CONFIG_HOME/agentic-security/ directory
+//     integrity.js already uses for its own signing key (a SEPARATE key
+//     file — never reuse one key across different cryptographic purposes).
+//     A KMS/envelope-encryption provider is a real future extension point
+//     (the provider interface is already shaped to allow one) but is out
+//     of scope here: this codebase makes no runtime cloud calls, and a KMS
+//     call is unavoidably a network call.
+//   - "Configured or required" is a per-project opt-in policy file
+//     (.agentic-security/encryption-policy.yml: `provider: local-key`,
+//     `required: true|false`). No file means "not configured, not
+//     required" — every confidential artifact keeps writing exactly as it
+//     always has, so this feature is inert until an operator opts in,
+//     matching every other policy surface in this codebase
+//     (retention-policy.yml, risk-config.yml, sca-policy.yml, ...).
+//   - The FAIL-CLOSED half of the acceptance criterion is
+//     `maybeEncryptForWrite`'s own contract: when `required: true` is set
+//     for a confidential artifact but no working provider is available,
+//     it returns `{ok:false}` — the caller must not write ANYTHING in that
+//     case, plaintext or otherwise. This is checked BEFORE any bytes touch
+//     disk, per the literal "fails before sensitive state is written"
+//     wording.
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as yaml from '../util/yaml.js';
+import { statePath } from './state-dir.js';
+import { confidentialOf } from './artifact-registry.js';
+
+export const ENCRYPTION_POLICY_FILE = 'encryption-policy.yml';
+export const ENCRYPTION_MARKER = '__agentic_security_encrypted_v1__';
+const KEY_FILE_NAME = 'encryption-key';
+const ALGORITHM = 'aes-256-gcm';
+const IV_BYTES = 12;
+
+function _keyDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.length ? xdg : path.join(os.homedir(), '.config');
+  return path.join(base, 'agentic-security');
+}
+function _keyPath() { return path.join(_keyDir(), KEY_FILE_NAME); }
+
+// Same atomic-publish shape as integrity.js's _publishKeyAtomically — a
+// hard-link into place is atomic and fails EEXIST rather than clobbering,
+// closing the same first-writer-wins race a plain exclusive-create alone
+// leaves open on filesystems without hard-link support (documented in
+// integrity.js's own header; reproduced here rather than imported, since
+// this is a genuinely separate key with its own purpose and no reason to
+// couple the two modules' internals together).
+function _publishKeyAtomically(fp, contents) {
+  const dir = _keyDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `${KEY_FILE_NAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, contents, { mode: 0o600 });
+    try {
+      fs.linkSync(tmp, fp);
+      return 'created';
+    } catch (e) {
+      if (e.code === 'EEXIST') return 'exists';
+      try {
+        fs.writeFileSync(fp, contents, { mode: 0o600, flag: 'wx' });
+        return 'created';
+      } catch (e2) {
+        if (e2.code === 'EEXIST') return 'exists';
+        throw e2;
+      }
+    }
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+  }
+}
+
+function _readOrGenerateKey() {
+  const fromEnv = process.env.AGENTIC_SECURITY_ENCRYPTION_KEY;
+  if (fromEnv && /^[0-9a-fA-F]{64}$/.test(fromEnv.trim())) return Buffer.from(fromEnv.trim(), 'hex');
+  const fp = _keyPath();
+  try {
+    if (fs.existsSync(fp)) {
+      const hex = fs.readFileSync(fp, 'utf8').trim();
+      if (/^[0-9a-fA-F]{64}$/.test(hex)) return Buffer.from(hex, 'hex');
+    }
+  } catch { /* fall through to generate */ }
+  const buf = crypto.randomBytes(32);
+  try {
+    const outcome = _publishKeyAtomically(fp, buf.toString('hex') + '\n');
+    if (outcome === 'created') return buf;
+    const hex = fs.readFileSync(fp, 'utf8').trim();
+    return Buffer.from(hex, 'hex');
+  } catch {
+    return buf; // ephemeral — a write can proceed this run, but nothing encrypted with it will ever decrypt again. Degraded, not blocked.
+  }
+}
+
+/**
+ * Read `.agentic-security/encryption-policy.yml`. Never throws; a missing
+ * or malformed file is "not configured, not required" (the safe,
+ * inert-by-default state every other policy file in this codebase uses).
+ */
+export function loadEncryptionPolicy(scanRoot) {
+  let fp;
+  try { fp = statePath(scanRoot, ENCRYPTION_POLICY_FILE); } catch { return null; }
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); } catch { return null; }
+  try {
+    const doc = yaml.load(raw);
+    if (!doc || typeof doc !== 'object') return null;
+    const provider = doc.provider === 'local-key' ? 'local-key' : null;
+    return { provider, required: doc.required === true };
+  } catch { return null; }
+}
+
+function _encryptBuffer(plaintext, key) {
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return { iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ciphertext: ciphertext.toString('base64') };
+}
+
+function _decryptBuffer(envelope, key) {
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, Buffer.from(envelope.iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
+  return Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, 'base64')), decipher.final()]);
+}
+
+/**
+ * Is `parsed` (an already-JSON.parsed value) an encryption envelope this
+ * module produced?
+ */
+export function isEncryptedEnvelope(parsed) {
+  return !!(parsed && typeof parsed === 'object' && parsed[ENCRYPTION_MARKER] === true);
+}
+
+/**
+ * The fail-closed gate. `artifactName` is matched against
+ * artifact-registry.js's `confidential` flag — an artifact not marked
+ * confidential is always {ok:true, content} unchanged, regardless of
+ * policy, so this function is a safe no-op to call for every write site
+ * without needing to duplicate the confidentiality check at each caller.
+ *
+ * @returns {{ok:true, content:string, encrypted:boolean} | {ok:false, reason:string}}
+ */
+export function maybeEncryptForWrite(scanRoot, artifactName, content) {
+  if (!confidentialOf(artifactName)) return { ok: true, content, encrypted: false };
+
+  const policy = loadEncryptionPolicy(scanRoot);
+  if (!policy || !policy.provider) {
+    if (policy && policy.required) {
+      return { ok: false, reason: `encryption is required for confidential artifact "${artifactName}" but no provider is configured (.agentic-security/${ENCRYPTION_POLICY_FILE})` };
+    }
+    return { ok: true, content, encrypted: false };
+  }
+
+  try {
+    const key = _readOrGenerateKey();
+    const envelope = _encryptBuffer(Buffer.from(content, 'utf8'), key);
+    return { ok: true, content: JSON.stringify({ [ENCRYPTION_MARKER]: true, provider: 'local-key', ...envelope }), encrypted: true };
+  } catch (e) {
+    if (policy.required) return { ok: false, reason: `encryption required but failed for "${artifactName}": ${e.message}` };
+    return { ok: true, content, encrypted: false };
+  }
+}
+
+/**
+ * Transparent decrypt-on-read: if `rawContent` parses as an envelope this
+ * module produced, decrypt and return the original plaintext string;
+ * otherwise return `rawContent` unchanged (a plaintext file, or a file
+ * from before encryption was ever configured). Never throws — a corrupt
+ * or undecryptable envelope degrades to returning the raw envelope JSON
+ * back (a caller expecting markdown/plaintext will visibly get neither,
+ * which is the correct, honest failure mode for a decrypt this module
+ * cannot perform, rather than silently returning empty content).
+ */
+export function maybeDecryptForRead(rawContent) {
+  let parsed;
+  try { parsed = JSON.parse(rawContent); } catch { return rawContent; }
+  if (!isEncryptedEnvelope(parsed)) return rawContent;
+  try {
+    const key = _readOrGenerateKey();
+    return _decryptBuffer(parsed, key).toString('utf8');
+  } catch { return rawContent; }
+}
+
+export const _internals = { _readOrGenerateKey, _encryptBuffer, _decryptBuffer, _keyPath };

package/src/posture/evidence-grade-wording.js

@@ -0,0 +1,71 @@
+// Canonical evidence-grade wording (assurance-hardening PRD FR-507).
+//
+// Every compliance-adjacent artifact this engine emits needs to disclaim
+// the same thing, and four of them had already drifted into hand-rolled,
+// SLIGHTLY WRONG phrasings before this module existed: compliance-policy.js
+// and auditor-walkthrough.js both said "A licensed assessor... is
+// responsible for the final attestation" — which conflates two DIFFERENT
+// things the PRD (and the standards this tooling maps to) treat as
+// distinct:
+//
+//   - An ATTESTATION is the ORGANIZATION'S OWN management formally
+//     asserting that stated controls are in place and operating (SOC 2's
+//     "management assertion" is the canonical example). This tool has no
+//     visibility into organizational process, personnel, or intent, so it
+//     cannot produce one.
+//   - A CERTIFICATION is a formal opinion or certificate issued by an
+//     ACCREDITED, INDEPENDENT third party (an ISO 27001 certification
+//     body, a SOC 2 auditor, a PCI DSS QSA) after their own examination.
+//     A "licensed assessor" produces a certification/independent
+//     assessment, not an attestation — the exact word swap the old
+//     wording got backwards.
+//
+// This tool produces neither. It produces the third, distinct tier:
+//
+//   - AUTOMATED TECHNICAL ASSESSMENT — deterministic, code-derived
+//     evidence for a bounded, disclosed set of controls. Real evidence,
+//     scoped honestly, but not a judgment about the organization.
+//
+// Naming all three, every time, is what FR-507 asks for ("UI and docs
+// distinguish automated technical assessment, management attestation, and
+// independent certification") — not just a generic "this isn't
+// certification" caveat, which is necessary but not sufficient: a reader
+// who has never heard the word "attestation" used correctly has no way to
+// know a real management attestation is a DIFFERENT, valid artifact they
+// might separately need.
+//
+// Every artifact quoting from here keeps the exact substring "does not
+// certify compliance" — several existing tests (world-class-batch2.test.js's
+// CMP-5 cases) already pin that phrase, and there's no reason to break a
+// correct, if incomplete, assertion while fixing the incompleteness.
+
+export const ASSURANCE_TIERS = Object.freeze({
+  automatedTechnicalAssessment:
+    'Automated technical assessment — what THIS TOOL produces: deterministic, ' +
+    'code-derived evidence for a bounded, disclosed set of controls.',
+  managementAttestation:
+    'Management attestation — the ORGANIZATION\'S OWN leadership formally ' +
+    'asserting that stated controls are in place and operating. This tool ' +
+    'cannot produce one; only the organization\'s management can.',
+  independentCertification:
+    'Independent certification — a formal opinion or certificate issued by an ' +
+    'ACCREDITED, INDEPENDENT third party (e.g. an ISO 27001 certification body, ' +
+    'a SOC 2 auditor, a PCI DSS QSA) after their own examination. This tool ' +
+    'cannot produce one; only an accredited independent party can.',
+});
+
+/** One-paragraph disclaimer for machine-consumed / GRC-ingested artifacts. */
+export const EVIDENCE_GRADE_DISCLAIMER =
+  'This artifact organizes automated technical assessment evidence produced by this scanner. ' +
+  'It does not certify compliance, and it is not a management attestation: only the ' +
+  'organization\'s own leadership can formally assert that stated controls are in place ' +
+  'and operating. It is also not an independent certification: only an accredited, ' +
+  'independent third party (an auditor, assessor, or certification body) examining the ' +
+  'organization directly can issue one.';
+
+/** Shorter inline variant for a markdown blockquote or narrow UI surface. */
+export const EVIDENCE_GRADE_DISCLAIMER_SHORT =
+  'This is automated technical assessment evidence — it does not certify compliance. ' +
+  'It is neither a management attestation (the organization\'s own sign-off) nor an ' +
+  'independent certification (an accredited third party\'s opinion); a licensed assessor ' +
+  'or the organization\'s management, not this tool, is responsible for either.';

package/src/posture/fix-history.js

@@ -58,10 +58,6 @@ export function fixAcceptanceRate(scanRoot) {
   return acceptanceFromEntries(readLog(scanRoot));
 }
 
-function writeLog(scanRoot, log) {
-  ensure(scanRoot);
-  fs.writeFileSync(logPath(scanRoot), JSON.stringify(log, null, 2));
-}
 function sha(s) { return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16); }
 
 // Premortem 3R-12: cross-check helpers for last-scan.json. We look up
@@ -242,7 +238,16 @@ function _countPriorAttempts(log, stableId, findingId) {
   return n;
 }
 
-export async function applyFix({ scanRoot, file, originalContent, newContent, findingId, ruleId, vuln, stableId }) {
+// @param {boolean} [fileExisted] - did `file` exist on disk before this call?
+//   Determines what "restore" means on rollback: write `originalContent`
+//   back for a file that existed (default, for backward compatibility with
+//   callers that don't pass it — safer to assume "existed" than to risk
+//   deleting a real file), or delete the file entirely for one that did not
+//   (a fix that created a NEW file, which is `originalContent: ''`'s only
+//   real-world meaning in this codebase's callers — writing '' back would
+//   leave a phantom empty file where none existed before, not a true
+//   rollback).
+export async function applyFix({ scanRoot, file, originalContent, newContent, findingId, ruleId, vuln, stableId, fileExisted = true }) {
   return _withLogLock(scanRoot, async () => {
     ensure(scanRoot);
     const absFile = path.resolve(scanRoot, file);
@@ -260,8 +265,10 @@ export async function applyFix({ scanRoot, file, originalContent, newContent, fi
         MAX_ATTEMPTS_PER_KEY,
       );
     }
-    // Phase 1: backup + fsync.
-    await _writeAndSync(bakPath, originalContent);
+    // Phase 1: backup + fsync. Atomic for the same reason the target write
+    // is below — a corrupted backup is worse than no backup, because it
+    // silently defeats rollback.
+    await _writeAtomicAndSync(bakPath, originalContent);
     const entry = {
       id,
       findingId,
@@ -269,6 +276,7 @@ export async function applyFix({ scanRoot, file, originalContent, newContent, fi
       ruleId: ruleId || null,
       vuln: vuln || null,
       file,
+      fileExisted,
       backupPath: path.relative(scanRoot, bakPath),
       originalSha: sha(originalContent),
       newSha: sha(newContent),
@@ -281,10 +289,38 @@ export async function applyFix({ scanRoot, file, originalContent, newContent, fi
     const log = priorLog;
     log.push(entry);
     await _writeLogAndSync(scanRoot, log);
-    // Phase 3: write the new content to the target file + fsync.
+    // Phase 3: atomic write of the new content, then FR-306's post-write
+    // hash verification — read the file back and confirm it genuinely
+    // contains what was just written, not merely that the write call
+    // returned without throwing (a write can "succeed" against a
+    // corrupting filesystem, a truncated disk-full write that still exits
+    // 0, or a concurrent external modification landing between our write
+    // and the read-back proving it).
     try {
-      await _writeAndSync(absFile, newContent);
+      await _writeAtomicAndSync(absFile, newContent);
+      const writtenBack = await fsp.readFile(absFile, 'utf8');
+      if (sha(writtenBack) !== entry.newSha) {
+        throw new Error(`post-write hash verification failed for ${file}: on-disk content does not match what was written`);
+      }
     } catch (e) {
+      // FR-306: "injected write failure restores all files" — a failure at
+      // this point (the write itself, or the verification catching a
+      // corrupted write) must not leave the target in a partial or wrong
+      // state. Restore it now, synchronously with the failure, not as a
+      // later manual `recover()` step.
+      try {
+        if (fileExisted) {
+          await _writeAtomicAndSync(absFile, originalContent);
+        } else {
+          await fsp.unlink(absFile).catch(() => {}); // the failed write may not have landed at all
+        }
+        entry.rolledBack = true;
+      } catch (restoreErr) {
+        // Genuinely worse case (e.g. the filesystem itself is unwritable) —
+        // recorded honestly rather than silently claimed as rolled back.
+        entry.rolledBack = false;
+        entry.restoreError = restoreErr.message;
+      }
       entry.status = 'failed';
       entry.error = e.message;
       await _writeLogAndSync(scanRoot, log);
@@ -308,6 +344,33 @@ async function _writeAndSync(fp, content) {
   }
 }
 
+// FR-306: "atomic replacement". `_writeAndSync` above opens the TARGET path
+// directly in truncate mode — a crash or thrown error between the truncate
+// and the write completing leaves the file partially written, not atomically
+// replaced. This writes to a sibling temp file first, fsyncs it, then
+// renames it over the target — `rename()` is atomic on the same filesystem,
+// so the target is either the old content or the new content in full, never
+// a partial mix. The temp file is cleaned up on any failure before the
+// rename so a crash never leaves an orphaned `.tmp-*` file behind.
+async function _writeAtomicAndSync(fp, content) {
+  const dir = path.dirname(fp);
+  await fsp.mkdir(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(fp)}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    const handle = await fsp.open(tmp, 'w');
+    try {
+      await handle.writeFile(content);
+      if (typeof handle.sync === 'function') await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fsp.rename(tmp, fp);
+  } catch (e) {
+    try { await fsp.unlink(tmp); } catch { /* never existed, or already gone — fine either way */ }
+    throw e;
+  }
+}
+
 async function _writeLogAndSync(scanRoot, log) {
   ensure(scanRoot);
   const fp = logPath(scanRoot);
@@ -369,22 +432,37 @@ async function _recoverInner(scanRoot) {
   return recovered;
 }
 
+// Shared revert primitive. `fileExisted === false` means the fix created a
+// file that did not exist beforehand — reverting deletes it rather than
+// writing the empty-string sentinel back, which would leave a phantom empty
+// file where none existed (see applyFix's `fileExisted` doc comment for why
+// that distinction matters). Entries logged before FR-306 have no
+// `fileExisted` field at all; `undefined !== false` so they fall through to
+// the pre-existing "write original content back" behavior, unchanged.
+async function _revertEntryInner(scanRoot, entry) {
+  const bak = path.resolve(scanRoot, entry.backupPath);
+  const absFile = path.resolve(scanRoot, entry.file);
+  if (!fs.existsSync(bak)) return { error: `backup missing: ${bak}` };
+  const original = await fsp.readFile(bak, 'utf8');
+  if (entry.fileExisted === false) {
+    await fsp.unlink(absFile).catch(() => {}); // may already be gone; deletion is the goal either way
+  } else {
+    await _writeAtomicAndSync(absFile, original);
+  }
+  entry.reverted = true;
+  entry.revertedAt = new Date().toISOString();
+  return entry;
+}
+
 // Revert the most recent un-reverted fix. Returns the entry or null.
 export async function undoLast(scanRoot) {
   return _withLogLock(scanRoot, async () => {
     const log = readLog(scanRoot);
     for (let i = log.length - 1; i >= 0; i--) {
       if (!log[i].reverted) {
-        const entry = log[i];
-        const bak = path.resolve(scanRoot, entry.backupPath);
-        const absFile = path.resolve(scanRoot, entry.file);
-        if (!fs.existsSync(bak)) return { error: `backup missing: ${bak}` };
-        const original = await fsp.readFile(bak, 'utf8');
-        await fsp.writeFile(absFile, original);
-        entry.reverted = true;
-        entry.revertedAt = new Date().toISOString();
-        writeLog(scanRoot, log);
-        return entry;
+        const result = await _revertEntryInner(scanRoot, log[i]);
+        if (!result.error) await _writeLogAndSync(scanRoot, log);
+        return result;
       }
     }
     return null;
@@ -399,6 +477,22 @@ export async function undoAll(scanRoot) {
   return reverted;
 }
 
+// FR-306: revert ONE specific entry by id, regardless of its position in the
+// log. The building block for same-batch rollback — a multi-file apply that
+// fails partway through must undo only the files THIS batch itself wrote,
+// not every unrelated pending entry `undoAll` would touch.
+export async function revertEntryById(scanRoot, entryId) {
+  return _withLogLock(scanRoot, async () => {
+    const log = readLog(scanRoot);
+    const entry = log.find(e => e.id === entryId);
+    if (!entry) return { error: `no such history entry: ${entryId}` };
+    if (entry.reverted) return entry;
+    const result = await _revertEntryInner(scanRoot, entry);
+    if (!result.error) await _writeLogAndSync(scanRoot, log);
+    return result;
+  });
+}
+
 export function listHistory(scanRoot) { return readLog(scanRoot); }
 
 // Premortem 3R-17: fix-history/log.json grows monotonically. A long-running

package/src/posture/fix-honesty-gate.js

@@ -141,23 +141,64 @@ export function computeFixTier(signals) {
 }
 
 /**
- * Compose the three gates for a single fix's output.
+ * FR-308: cross-check a fix-completeness TIER against MECHANICAL evidence,
+ * when any is available. `signals` (computeFixTier's input) is agent-
+ * self-reported — this module cannot compute sinkSignatureChanged /
+ * allCallersRouted / testDiscriminates itself (see the header above: "the
+ * gate can only run against claims the AGENT self-reports... nothing here
+ * is server-computable"). `pocLeg` is different: fix-verify.js's PoC leg is
+ * a REAL execution result (posture/CLAUDE.md's execution-proof tiers), not
+ * a claim. When it is available and shows the proof-of-concept STILL
+ * demonstrates the vulnerability against the patch, a self-reported FULL
+ * tier is not merely internally inconsistent — it is REFUTED by fact. This
+ * is the literal "a mitigation or workaround cannot be represented as a
+ * full fix" acceptance criterion, now backed by mechanical evidence where
+ * it exists rather than by self-report consistency alone.
  *
- * ok = residual-honesty ok AND evidence-citation ok, further constrained by the
- * tier/residual consistency invariant:
+ * A `pocLeg` of `not-requested` or `inconclusive` carries no mechanical
+ * signal either way and is a no-op here — this check can only ever ADD a
+ * violation on real contrary evidence, never manufacture one from absence.
+ *
+ * @param {string} tier
+ * @param {{status: string, reason?: string}|null} pocLeg
+ * @returns {{ ok: boolean, violations: string[] }}
+ */
+export function checkMechanicalTierEvidence(tier, pocLeg) {
+  if (!pocLeg || typeof pocLeg !== 'object') return { ok: true, violations: [] };
+  if (tier === 'FULL' && pocLeg.status === 'still-exploitable') {
+    return {
+      ok: false,
+      violations: [`tier 'FULL' is refuted by mechanical evidence: the proof-of-concept still demonstrates the vulnerability against the patch${pocLeg.reason ? ` (${pocLeg.reason})` : ''}`],
+    };
+  }
+  return { ok: true, violations: [] };
+}
+
+/**
+ * Compose the four gates for a single fix's output.
+ *
+ * ok = residual-honesty ok AND evidence-citation ok AND mechanical-tier-
+ * evidence ok, further constrained by the tier/residual consistency
+ * invariant:
  *   - a FULL tier must NOT carry a residual (a full fix has nothing left);
  *   - a non-FULL tier MUST document a residual (say what's still open).
  *
  * @param {{ residual?: string, verdict?: string, evidence?: any, signals?: object }} input
+ * @param {{ pocLeg?: object|null }} [mechanical] - FR-308: optional real
+ *   execution evidence (fix-verify.js's pocLeg) to cross-check the
+ *   self-reported tier against. Omitted entirely by any caller that has no
+ *   PoC leg to offer — this parameter never REQUIRES mechanical evidence,
+ *   it only USES it when present.
  * @returns {{ ok: boolean, tier: string, violations: string[] }}
  */
-export function gateFixOutput({ residual, verdict, evidence, signals } = {}) {
+export function gateFixOutput({ residual, verdict, evidence, signals } = {}, { pocLeg = null } = {}) {
   const tier = computeFixTier(signals);
   const residualCheck = checkResidualHonesty(residual);
   const evidenceCheck = requireCitedEvidence(verdict, evidence);
+  const mechanicalCheck = checkMechanicalTierEvidence(tier, pocLeg);
 
-  const violations = [...residualCheck.violations, ...evidenceCheck.violations];
-  let ok = residualCheck.ok && evidenceCheck.ok;
+  const violations = [...residualCheck.violations, ...evidenceCheck.violations, ...mechanicalCheck.violations];
+  let ok = residualCheck.ok && evidenceCheck.ok && mechanicalCheck.ok;
 
   const residualEmpty = typeof residual !== 'string' || residual.trim() === '';
   if (tier === 'FULL' && !residualEmpty) {

package/src/posture/fix-verify.js

@@ -187,12 +187,6 @@ export async function verifyFix({
   // and on the result so a caller cannot mistake it for a verified patch.
   const _testedPrePatch = !tests.skipped && _candidateDiffersFromDisk(scanRoot, files);
   const testsOk = tests.skipped ? true : tests.passed === true;
-  let honesty = null;
-  if (fixMeta && typeof fixMeta === 'object') {
-    try { honesty = gateFixOutput(fixMeta); } catch { honesty = null; }
-  }
-  _lap('honesty');
-
   // R5 — the PoC leg. Re-run the finding's proof-of-concept against the
   // CANDIDATE patch inside R1's sandbox. A patch that still lets the PoC
   // demonstrate the predicted effect has not fixed anything, however green the
@@ -204,6 +198,11 @@ export async function verifyFix({
   // to run, or a sandbox that could not start, is recorded as `inconclusive`
   // and left out of the verdict entirely. Treating "could not prove it" as
   // "fixed" is exactly the false confidence this leg exists to prevent.
+  //
+  // Computed BEFORE the honesty gate (FR-308): a still-exploitable PoC is
+  // MECHANICAL evidence, not a self-report, and gateFixOutput cross-checks a
+  // self-reported FULL tier against it below — the ordering matters, not
+  // just the value.
   let pocLeg = { status: 'not-requested', reason: null, tier: null };
   if (poc?.code) {
     try {
@@ -222,7 +221,54 @@ export async function verifyFix({
   _lap('poc');
   const pocOk = pocLeg.status !== 'still-exploitable';
 
+  // FR-308: "a mitigation or workaround cannot be represented as a full
+  // fix" — gateFixOutput's tier/residual check is a pure self-consistency
+  // check (fixMeta.signals is agent-self-reported; see fix-honesty-gate.js's
+  // header for why nothing there is server-computable). pocLeg IS
+  // server-computable — a real execution result, not a claim — so it is
+  // passed through as the one MECHANICAL cross-check available: a
+  // self-reported FULL tier is refuted, not just internally inconsistent,
+  // when the PoC still demonstrates the vulnerability against the patch.
+  // D-0024: `fixMeta` is a shared envelope — FR-307/FR-1002's `approval`
+  // key lives alongside FR-308's completeness self-report (`residual`/
+  // `verdict`/`evidence`/`signals`). Gating on mere object-truthiness meant
+  // a caller supplying ONLY `approval` (a real, common shape once the CLI's
+  // --approved-by flag and the MCP schema fix made that reachable) got
+  // silently gated on an UNRELATED FR-308 self-consistency check it never
+  // engaged with — computeFixTier(undefined) defaults to MITIGATION, which
+  // then demands a `residual` nobody was ever asked to supply, blocking an
+  // otherwise-genuine, approved fix for a reason that has nothing to do
+  // with completeness honesty. Scope the gate to fixMeta shapes that
+  // actually make a completeness-adjacent claim.
+  const hasHonestyClaim = fixMeta && typeof fixMeta === 'object' &&
+    (fixMeta.residual !== undefined || fixMeta.verdict !== undefined ||
+     fixMeta.evidence !== undefined || fixMeta.signals !== undefined);
+  let honesty = null;
+  if (hasHonestyClaim) {
+    try { honesty = gateFixOutput(fixMeta, { pocLeg }); } catch { honesty = null; }
+  }
+  _lap('honesty');
+
   const ok = rescan.ok && (lint.ok || lint.skipped) && testsOk && pocOk && (honesty ? honesty.ok : true);
+
+  // FR-305 (assurance-hardening PRD): `ok` alone conflates "every leg
+  // genuinely ran and passed" with "passed, but a required leg was skipped
+  // or unavailable" — `lint.ok`/`testsOk` are both true in the skipped case
+  // by design (this codebase does not fail-closed just because a repo has
+  // no linter or no detected test runner), so a caller checking only `ok`
+  // cannot tell the difference. `lint.skipped` is only ever true when a
+  // linter WAS configured but its binary could not be run (missing config
+  // entirely returns `runner: 'none'` with no `skipped` field at all — that
+  // is a genuine N/A, nothing was required, not a degradation). `verifiedFull`
+  // is the honest label: true only when nothing that WAS required was
+  // skipped. A caller must never present `ok: true, verifiedFull: false` as
+  // "fully verified" — `degradedLegs` names exactly what was skipped so a
+  // report can say so plainly instead of a bare pass.
+  const degradedLegs = [];
+  if (lint.skipped) degradedLegs.push(`lint: ${lint.runner} not installed`);
+  if (tests.skipped) degradedLegs.push(`tests: skipped (${tests.reason})`);
+  const verifiedFull = ok && degradedLegs.length === 0;
+
   const durations = { ...stages, totalMs: Date.now() - t0 };
   const summary = [
     `re-scan: ${rescan.ok ? 'PASS' : 'FAIL — ' + rescan.reason}`,
@@ -244,6 +290,8 @@ export async function verifyFix({
       : pocLeg.status === 'still-exploitable' ? `poc:     FAIL — the proof-of-concept still demonstrates the vulnerability against the patch`
       : pocLeg.status === 'no-longer-proven' ? 'poc:     PASS (ran against the patch and no longer demonstrates the vulnerability)'
       : `poc:     inconclusive — not counted either way (${pocLeg.reason || 'no detail reported'})`,
+    // FR-305: never let a degraded pass read the same as a full one.
+    ok && !verifiedFull ? `NOTE:    PASSED, but NOT fully verified — ${degradedLegs.join('; ')}` : null,
   ].filter(Boolean).join('\n');
   // Persist the attempt so the distribution can be reported from real runs.
   // `testsRan` is the load-bearing field: it is what keeps "verified with no
@@ -256,6 +304,7 @@ export async function verifyFix({
       at: new Date().toISOString(),
       stableId: originalFindingStableId || null,
       ok,
+      verifiedFull,
       testsRan: !tests.skipped,
       testsPassed: tests.skipped ? null : tests.passed === true,
       testedPrePatch: _testedPrePatch,
@@ -268,5 +317,5 @@ export async function verifyFix({
     });
   }
 
-  return { ok, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, poc: pocLeg, durations, summary };
+  return { ok, verifiedFull, degradedLegs, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, poc: pocLeg, durations, summary };
 }