snipara-companion 3.0.7 → 3.0.8

package/README.md

@@ -43,7 +43,7 @@ These commands are useful without hosted Snipara:
 | ------------------------------------------------------------ | ------------------------------------------------------------ |
 | `source init` / `source sync` / `source status`              | Local source snapshot, document preview, and code overlay    |
 | `impact` / `code impact`                                     | File-level blast-radius from the local code overlay          |
-| `reality-check`                                              | Intent/verification checks for local or supplied changes     |
+| `reality-check`                                              | Intent Ledger, Unknown Registry, and verification checks     |
 | `code callers` / `imports` / `neighbors` / `shortest-path`   | Structural repo questions from local files                   |
 | `workflow start` / `phase-start` / `phase-commit` / `resume` | Agent continuity that survives compaction                    |
 | `context-pack`                                               | Reversible local packs for long logs, diffs, and tool output |

package/dist/index.js

@@ -19687,6 +19687,8 @@ var PROJECT_INTELLIGENCE_ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES = [
   "unknown"
 ];
 var PROJECT_REALITY_CHECK_VERSION = "project-reality-check-v0";
+var PROJECT_INTENT_LEDGER_VERSION = "intent-ledger-v1";
+var PROJECT_UNKNOWN_REGISTRY_VERSION = "unknown-registry-v1";
 var SENSITIVE_SURFACES = [
   {
     key: "billing_atomicity",
@@ -19796,6 +19798,444 @@ function decisionText(decision) {
     ...decision.constraints ?? []
   ].filter(Boolean).join(" ");
 }
+function confidenceBand(score) {
+  if (score >= 0.8) return "high";
+  if (score >= 0.55) return "medium";
+  return "low";
+}
+function normalizeConfidenceScore(value, fallback) {
+  if (typeof value !== "number" || Number.isNaN(value)) return fallback;
+  return Math.max(0, Math.min(1, value));
+}
+function intentStatusFromDecision(decision) {
+  const status = normalizeText(decision.status);
+  if (/contradict|conflict/.test(status)) return "contradicted";
+  if (/supersed|replac/.test(status)) return "superseded";
+  if (/stale|expired|deprecated/.test(status)) return "stale";
+  if (/approved|accepted|active|confirmed/.test(status)) return "approved";
+  return "review_pending";
+}
+function intentConfidence(score, status, reasonCodes) {
+  return {
+    score,
+    band: confidenceBand(score),
+    state: status === "approved" ? "confirmed" : status === "stale" ? "stale" : status === "contradicted" ? "conflicted" : score < 0.55 ? "weak" : "review_pending",
+    reasonCodes
+  };
+}
+function stalenessFromStatus(status) {
+  if (status === "stale" || status === "superseded") {
+    return {
+      state: "stale",
+      reason: status === "superseded" ? "The source decision is marked as superseded." : "The source decision is marked as stale."
+    };
+  }
+  if (status === "review_pending") {
+    return {
+      state: "unknown",
+      reason: "The intent has not been reviewed as current project truth."
+    };
+  }
+  return { state: "fresh", horizonDays: 90 };
+}
+function anchorMatchesFile(anchor, file) {
+  const normalizedAnchor = anchor.replace(/^\.\//, "").trim();
+  const normalizedFile = file.replace(/^\.\//, "").trim();
+  return normalizedAnchor.length > 0 && normalizedFile.length > 0 && (normalizedFile.includes(normalizedAnchor) || normalizedAnchor.includes(normalizedFile));
+}
+function intentEntryMatchesFile(entry, file) {
+  return entry.affectedAnchors.some((anchor) => anchorMatchesFile(anchor, file));
+}
+function inferDecisionAnchors(decision, changedFiles) {
+  const explicitAnchors = uniqueStrings8(decision.affectedAnchors ?? []);
+  if (explicitAnchors.length > 0) return explicitAnchors;
+  const text = normalizeText(decisionText(decision));
+  const inferred = SENSITIVE_SURFACES.flatMap(
+    (surface) => matchesAnyText(text, surface.patterns) ? surfaceFiles(surface, changedFiles) : []
+  );
+  return uniqueStrings8(inferred);
+}
+function splitIntentPhrases(value) {
+  if (!value) return [];
+  return uniqueStrings8(
+    value.split(/[;\n]/g).map((item) => item.replace(/^[-*]\s*/, "").trim()).filter(Boolean)
+  ).slice(0, 6);
+}
+function extractAntiGoals(text) {
+  const matches = [...text.matchAll(/\b(?:avoid|forbid|prevent|do not|don't)\b[^.;\n]*/gi)].map(
+    (match) => match[0].trim()
+  );
+  return uniqueStrings8(matches).slice(0, 5);
+}
+function extractRejectedAlternatives(text) {
+  const matches = [
+    ...text.matchAll(/\b(?:rejected|instead of|rather than|not use|not using)\b[^.;\n]*/gi)
+  ].map((match) => match[0].trim());
+  return uniqueStrings8(matches).slice(0, 5);
+}
+function documentLooksLikeIntent(doc) {
+  const text = normalizeText([doc.path, doc.title, doc.contentPreview, doc.kind].join(" "));
+  return /\b(adr|decision|intent|rationale|constraint|architecture|runbook)\b/.test(text);
+}
+function buildDecisionIntentEntry(decision, changedFiles) {
+  const status = intentStatusFromDecision(decision);
+  const anchors = inferDecisionAnchors(decision, changedFiles);
+  const fullText = decisionText(decision);
+  const confidenceScore = normalizeConfidenceScore(
+    decision.confidenceScore,
+    status === "approved" ? 0.86 : 0.66
+  );
+  const reasonCodes = uniqueStrings8([
+    "decision_intent",
+    status === "approved" ? "reviewed_source" : "review_needed",
+    anchors.length > 0 ? "affected_anchors_present" : "affected_anchors_missing"
+  ]);
+  return {
+    id: `intent:${decision.id}`,
+    title: decision.title,
+    status,
+    source: "decision",
+    sourceDecisionId: decision.id,
+    sourceDocumentPath: null,
+    intent: {
+      goal: decision.rationale || decision.decision || decision.title,
+      constraints: uniqueStrings8([
+        ...decision.constraints ?? [],
+        ...splitIntentPhrases(decision.scope)
+      ]).slice(0, 8),
+      antiGoals: extractAntiGoals(fullText),
+      rejectedAlternatives: extractRejectedAlternatives(fullText)
+    },
+    affectedAnchors: anchors,
+    owner: null,
+    evidence: decision.evidence && decision.evidence.length > 0 ? decision.evidence : [
+      {
+        kind: "decision",
+        label: `${decision.id}: ${decision.title}`,
+        sourceRef: decision.id,
+        strength: confidenceScore
+      }
+    ],
+    confidence: intentConfidence(confidenceScore, status, reasonCodes),
+    staleness: stalenessFromStatus(status),
+    reasonCodes,
+    recommendedActions: status === "approved" ? ["Keep this intent linked when changing its affected anchors."] : ["Review this intent candidate before treating it as governing project truth."],
+    caveats: [
+      "Intent Ledger V1 preserves source-backed intent; it does not infer unstated architecture rules."
+    ]
+  };
+}
+function buildDocumentIntentEntry(doc) {
+  const preview4 = doc.contentPreview || doc.title || doc.path;
+  const reasonCodes = ["document_intent_candidate", "review_needed"];
+  const confidenceScore = doc.kind && /adr|decision/i.test(doc.kind) ? 0.66 : 0.58;
+  return {
+    id: `intent:doc:${doc.path}`,
+    title: doc.title || doc.path,
+    status: "review_pending",
+    source: "document",
+    sourceDecisionId: null,
+    sourceDocumentPath: doc.path,
+    intent: {
+      goal: preview4,
+      constraints: splitIntentPhrases(doc.contentPreview).slice(0, 4),
+      antiGoals: extractAntiGoals(preview4),
+      rejectedAlternatives: extractRejectedAlternatives(preview4)
+    },
+    affectedAnchors: [doc.path],
+    owner: null,
+    evidence: [
+      {
+        kind: "document",
+        label: doc.title ? `${doc.path}: ${doc.title}` : doc.path,
+        sourceRef: doc.sourceRef ?? doc.path,
+        strength: confidenceScore
+      }
+    ],
+    confidence: intentConfidence(confidenceScore, "review_pending", reasonCodes),
+    staleness: {
+      state: "unknown",
+      reason: "Document-derived intent candidates need review before becoming governing truth."
+    },
+    reasonCodes,
+    recommendedActions: ["Promote, reject, or link this document intent candidate to a decision."],
+    caveats: [
+      "Document candidates are weaker than reviewed decisions until authority is confirmed."
+    ]
+  };
+}
+function buildProjectIntentLedger(input, changedFilesOverride) {
+  const changedFiles = uniqueStrings8(changedFilesOverride ?? input.changedFiles);
+  const decisionEntries = (input.decisions ?? []).map(
+    (decision) => buildDecisionIntentEntry(decision, changedFiles)
+  );
+  const decisionDocumentPaths = new Set(
+    decisionEntries.flatMap(
+      (entry) => entry.evidence.map((evidence) => evidence.sourceRef).filter(Boolean)
+    )
+  );
+  const documentEntries = (input.documents ?? []).filter(documentLooksLikeIntent).filter((doc) => !decisionDocumentPaths.has(doc.path)).map(buildDocumentIntentEntry);
+  const entries = [...decisionEntries, ...documentEntries];
+  const linkedIntentIds = new Set(
+    entries.filter((entry) => changedFiles.some((file) => intentEntryMatchesFile(entry, file))).map((entry) => entry.id)
+  );
+  const missingAnchors = changedFiles.filter(
+    (file) => !entries.some((entry) => intentEntryMatchesFile(entry, file))
+  );
+  const coverage = changedFiles.length === 0 || entries.length > 0 && missingAnchors.length === 0 ? "linked" : entries.length === 0 ? "missing" : "partial";
+  const reasonCodes = uniqueStrings8([
+    coverage === "linked" ? "intent_coverage_linked" : void 0,
+    coverage === "partial" ? "intent_coverage_partial" : void 0,
+    coverage === "missing" ? "intent_coverage_missing" : void 0,
+    entries.some((entry) => entry.status === "review_pending") ? "intent_review_pending" : void 0,
+    entries.some((entry) => entry.staleness.state !== "fresh") ? "intent_freshness_unknown" : void 0
+  ]);
+  return {
+    version: PROJECT_INTENT_LEDGER_VERSION,
+    coverage,
+    totalIntentCount: entries.length,
+    linkedIntentCount: linkedIntentIds.size,
+    missingAnchorCount: missingAnchors.length,
+    entries: entries.slice(0, 20),
+    missingAnchors: missingAnchors.slice(0, 20),
+    evidence: entries.flatMap((entry) => entry.evidence).slice(0, 10),
+    reasonCodes,
+    caveats: [
+      "Intent Ledger V1 is a deterministic projection from supplied decisions and documents.",
+      coverage === "missing" ? "Missing intent means no linked source was supplied for this scope, not that no governing intent exists." : void 0
+    ].filter((item) => Boolean(item))
+  };
+}
+function unknownId(category, key, scope) {
+  return makeFindingId("decision_vs_code", `${category}:${key}`, scope).replace(
+    "reality:decision-vs-code",
+    "unknown"
+  );
+}
+function unknownStatusFromSeverity(unknowns) {
+  if (unknowns.some(
+    (unknown) => unknown.severity === "blocking" || unknown.severity === "review_required"
+  )) {
+    return "risk";
+  }
+  if (unknowns.some((unknown) => unknown.severity === "watch")) return "watch";
+  return "clear";
+}
+function unknownConfidence(score, state, reasonCodes) {
+  return {
+    score,
+    band: confidenceBand(score),
+    state,
+    reasonCodes
+  };
+}
+function makeUnknown(input) {
+  return {
+    id: unknownId(input.category, input.title, input.scope),
+    category: input.category,
+    severity: input.severity,
+    title: input.title,
+    summary: input.summary,
+    scope: input.scope.slice(0, 12),
+    ownerCandidate: input.ownerCandidate ?? null,
+    confidence: unknownConfidence(
+      input.confidenceScore,
+      input.confidenceState ?? "review_pending",
+      input.reasonCodes
+    ),
+    linkedFindingIds: input.linkedFindingIds ?? [],
+    linkedIntentIds: input.linkedIntentIds ?? [],
+    evidence: (input.evidence ?? []).slice(0, 8),
+    reasonCodes: input.reasonCodes,
+    resolutionActions: input.resolutionActions,
+    closureEvidenceRequired: input.closureEvidenceRequired,
+    caveats: input.caveats ?? []
+  };
+}
+function buildProjectUnknownRegistry(input) {
+  const unknowns = [];
+  if (input.intentLedger.missingAnchors.length > 0) {
+    unknowns.push(
+      makeUnknown({
+        category: "missing_intent",
+        severity: input.findings.some((finding) => finding.severity === "review_required") ? "review_required" : "watch",
+        title: "Governing intent is not linked for part of this scope",
+        summary: "At least one changed anchor has no linked reviewed decision or document intent. This is an unknown, not proof that no constraint exists.",
+        scope: input.intentLedger.missingAnchors,
+        confidenceScore: 0.86,
+        linkedFindingIds: input.findings.filter((finding) => finding.reasonCodes.includes("missing_intent")).map((finding) => finding.id),
+        evidence: input.intentLedger.evidence,
+        reasonCodes: ["missing_intent", "unknown_governing_decision"],
+        resolutionActions: [
+          "Link an existing decision, approve a review-pending intent, or create a new decision candidate."
+        ],
+        closureEvidenceRequired: [
+          "Reviewed decision, ADR, issue, PR Answer Pack, or final workflow commit linked to the changed anchor."
+        ],
+        caveats: [
+          "Retrieval/index freshness can make linked intent appear missing until context is refreshed."
+        ]
+      })
+    );
+  }
+  for (const entry of input.intentLedger.entries) {
+    if (entry.status === "review_pending") {
+      unknowns.push(
+        makeUnknown({
+          category: "intent_review_pending",
+          severity: "watch",
+          title: `Intent needs review: ${entry.title}`,
+          summary: "A source-backed intent candidate exists, but it is not reviewed enough to act as governing project truth.",
+          scope: entry.affectedAnchors,
+          confidenceScore: entry.confidence.score,
+          linkedIntentIds: [entry.id],
+          evidence: entry.evidence,
+          reasonCodes: ["intent_review_pending"],
+          resolutionActions: ["Approve, reject, supersede, or link this intent candidate."],
+          closureEvidenceRequired: ["Review receipt or approved ProjectDecision authority state."],
+          caveats: entry.caveats
+        })
+      );
+    }
+    if (entry.status === "stale" || entry.status === "superseded") {
+      unknowns.push(
+        makeUnknown({
+          category: "stale_intent",
+          severity: "review_required",
+          title: `Intent may be stale: ${entry.title}`,
+          summary: "A linked intent is stale or superseded; current implementation may no longer match the original rationale.",
+          scope: entry.affectedAnchors,
+          confidenceScore: 0.78,
+          confidenceState: "stale",
+          linkedIntentIds: [entry.id],
+          evidence: entry.evidence,
+          reasonCodes: ["stale_intent", entry.status],
+          resolutionActions: [
+            "Refresh, supersede, or archive the stale intent before relying on it."
+          ],
+          closureEvidenceRequired: ["Updated decision or explicit supersession evidence."],
+          caveats: entry.caveats
+        })
+      );
+    }
+  }
+  for (const finding of input.findings) {
+    if (finding.reasonCodes.includes("verification_missing")) {
+      unknowns.push(
+        makeUnknown({
+          category: "missing_verification",
+          severity: finding.severity,
+          title: `Verification gap: ${finding.title}`,
+          summary: "The change touches a sensitive surface but no matching verification evidence was supplied.",
+          scope: finding.changedFiles,
+          confidenceScore: 0.82,
+          linkedFindingIds: [finding.id],
+          linkedIntentIds: finding.decisionIds.map((id) => `intent:${id}`),
+          evidence: finding.evidence,
+          reasonCodes: ["missing_verification", ...finding.reasonCodes],
+          resolutionActions: finding.recommendedActions,
+          closureEvidenceRequired: [
+            "Focused test, smoke check, review proof, or verification checklist item linked to the changed behavior."
+          ],
+          caveats: finding.caveats
+        })
+      );
+    }
+    if (finding.type === "architecture_drift") {
+      unknowns.push(
+        makeUnknown({
+          category: "architecture_drift",
+          severity: finding.severity,
+          title: finding.title,
+          summary: "A boundary-spanning change needs architecture-intent confirmation before treating the current dependency shape as intended.",
+          scope: finding.changedFiles,
+          confidenceScore: 0.72,
+          linkedFindingIds: [finding.id],
+          evidence: finding.evidence,
+          reasonCodes: ["architecture_drift_unknown", ...finding.reasonCodes],
+          resolutionActions: finding.recommendedActions,
+          closureEvidenceRequired: [
+            "Architecture rule, reviewed decision, or code graph evidence proving the boundary is intentional."
+          ],
+          caveats: finding.caveats
+        })
+      );
+    }
+    if (finding.reasonCodes.includes("risk_term_in_diff") || finding.reasonCodes.includes("no_linked_decision") && finding.severity === "review_required") {
+      unknowns.push(
+        makeUnknown({
+          category: "heuristic_calibration",
+          severity: "watch",
+          title: `Heuristic signal needs calibration: ${finding.title}`,
+          summary: "Reality Check V1 used regex/path/free-text signals for this finding. Keep it advisory or narrow-scope until project-specific thresholds are calibrated.",
+          scope: finding.changedFiles,
+          confidenceScore: 0.68,
+          confidenceState: "weak",
+          linkedFindingIds: [finding.id],
+          evidence: finding.evidence,
+          reasonCodes: ["heuristic_calibration_needed", ...finding.reasonCodes],
+          resolutionActions: [
+            "Confirm the finding against structured intent, tests, or reviewed project-specific rules before broad CI gating."
+          ],
+          closureEvidenceRequired: [
+            "Reviewed calibration decision or false-positive/true-positive outcome history for this surface."
+          ],
+          caveats: [
+            "--enforce should remain opt-in for this finding family until calibration evidence exists."
+          ]
+        })
+      );
+    }
+  }
+  if (input.dirtyFiles.length > 0) {
+    unknowns.push(
+      makeUnknown({
+        category: "dirty_local_evidence",
+        severity: "watch",
+        title: "Local dirty evidence is not hosted truth",
+        summary: "The local scan included dirty files that hosted PR checks and code graph indexes cannot see until committed.",
+        scope: input.dirtyFiles,
+        confidenceScore: 0.9,
+        linkedFindingIds: input.findings.filter((finding) => finding.reasonCodes.includes("dirty_working_tree")).map((finding) => finding.id),
+        evidence: input.dirtyFiles.map((file) => ({
+          kind: "repository",
+          label: file,
+          sourceRef: file,
+          strength: 0.5
+        })),
+        reasonCodes: ["dirty_local_evidence", "hosted_context_gap"],
+        resolutionActions: [
+          "Commit, stash, or exclude dirty files before relying on hosted checks."
+        ],
+        closureEvidenceRequired: ["Clean git status or explicit review of dirty files."],
+        caveats: ["Dirty-file unknowns are local-only and should not be treated as PR evidence."]
+      })
+    );
+  }
+  const deduped = Array.from(
+    new Map(unknowns.map((unknown) => [unknown.id, unknown])).values()
+  ).slice(0, 24);
+  const status = unknownStatusFromSeverity(deduped);
+  return {
+    version: PROJECT_UNKNOWN_REGISTRY_VERSION,
+    status,
+    unknownCount: deduped.length,
+    riskCount: deduped.filter(
+      (unknown) => unknown.severity === "review_required" || unknown.severity === "blocking"
+    ).length,
+    watchCount: deduped.filter((unknown) => unknown.severity === "watch").length,
+    categories: uniqueStrings8(
+      deduped.map((unknown) => unknown.category)
+    ),
+    unknowns: deduped,
+    evidence: deduped.flatMap((unknown) => unknown.evidence).slice(0, 12),
+    reasonCodes: uniqueStrings8(deduped.flatMap((unknown) => unknown.reasonCodes)).slice(0, 24),
+    caveats: [
+      "Unknown Registry V1 records evidence-backed gaps; closing an unknown requires source-backed evidence.",
+      deduped.some((unknown) => unknown.category === "heuristic_calibration") ? "Heuristic calibration unknowns prevent regex/path findings from masquerading as fully calibrated truth." : void 0
+    ].filter((item) => Boolean(item))
+  };
+}
 function surfaceFiles(surface, changedFiles) {
   return changedFiles.filter((file) => surface.patterns.some((pattern) => pattern.test(file)));
 }
@@ -19836,6 +20276,7 @@ function buildProjectRealityCheck(input) {
   const findings = [];
   const decisions = input.decisions ?? [];
   const contextEvidence2 = [...docEvidence(input), ...symbolEvidence(input)];
+  const intentLedger = buildProjectIntentLedger(input, changedFiles);
   for (const surface of SENSITIVE_SURFACES) {
     const files = surfaceFiles(surface, changedFiles);
     if (files.length === 0) continue;
@@ -19896,7 +20337,7 @@ function buildProjectRealityCheck(input) {
       ]
     });
   }
-  if (changedFiles.length > 0 && decisions.length === 0 && (input.source === "pull_request" || findings.length > 0)) {
+  if (changedFiles.length > 0 && intentLedger.linkedIntentCount === 0 && (input.source === "pull_request" || findings.length > 0)) {
     findings.push({
       id: makeFindingId("decision_vs_code", "missing_intent", changedFiles),
       type: "decision_vs_code",
@@ -19961,6 +20402,13 @@ function buildProjectRealityCheck(input) {
     0,
     20
   );
+  const unknownRegistry = buildProjectUnknownRegistry({
+    realityCheck: input,
+    changedFiles,
+    dirtyFiles,
+    findings,
+    intentLedger
+  });
   const caveats = uniqueStrings8([
     "Project Reality Check V0 is advisory and evidence-backed; it is not deterministic repository simulation.",
     input.source === "local" ? "Local results may include dirty files that hosted PR checks cannot see." : "PR results are scoped to GitHub-provided PR files and indexed Snipara context."
@@ -19975,9 +20423,15 @@ function buildProjectRealityCheck(input) {
     changedFileCount: changedFiles.length,
     findingCount: findings.length,
     findings,
+    intentLedger,
+    unknownRegistry,
     requiredActions,
     watchItems,
-    reasonCodes,
+    reasonCodes: uniqueStrings8([
+      ...reasonCodes,
+      ...intentLedger.reasonCodes,
+      ...unknownRegistry.reasonCodes
+    ]).slice(0, 30),
     caveats
   };
 }
@@ -19987,6 +20441,45 @@ function renderProjectRealityCheckMarkdown(result) {
     `- Scope: ${result.changedFileCount} changed file(s), ${result.findingCount} finding(s).`,
     `- Summary: ${result.summary}`
   ];
+  lines.push(
+    "",
+    "Intent Ledger:",
+    `- Coverage: ${result.intentLedger.coverage}; ${result.intentLedger.linkedIntentCount}/${result.intentLedger.totalIntentCount} intent(s) linked to this scope.`
+  );
+  for (const entry of result.intentLedger.entries.slice(0, 5)) {
+    lines.push(
+      `- ${entry.status.toUpperCase()} ${entry.id}: ${entry.title}`,
+      `  Intent: ${entry.intent.goal}`,
+      `  Confidence: ${entry.confidence.band} (${Math.round(entry.confidence.score * 100)}%).`
+    );
+    if (entry.affectedAnchors.length > 0) {
+      lines.push(`  Anchors: ${entry.affectedAnchors.slice(0, 5).join(", ")}`);
+    }
+  }
+  if (result.intentLedger.missingAnchors.length > 0) {
+    lines.push(
+      `- Missing linked intent for: ${result.intentLedger.missingAnchors.slice(0, 8).map((file) => `\`${file}\``).join(", ")}`
+    );
+  }
+  lines.push(
+    "",
+    "Unknown Registry:",
+    `- Status: ${result.unknownRegistry.status}; ${result.unknownRegistry.unknownCount} unknown(s), ${result.unknownRegistry.riskCount} risk item(s).`
+  );
+  for (const unknown of result.unknownRegistry.unknowns.slice(0, 6)) {
+    lines.push(
+      `- ${unknown.severity.toUpperCase()} ${unknown.category}: ${unknown.title}`,
+      `  ${unknown.summary}`
+    );
+    if (unknown.scope.length > 0) {
+      lines.push(
+        `  Scope: ${unknown.scope.slice(0, 5).map((item) => `\`${item}\``).join(", ")}`
+      );
+    }
+    if (unknown.resolutionActions.length > 0) {
+      lines.push(`  Resolve: ${unknown.resolutionActions[0]}`);
+    }
+  }
   if (result.findings.length > 0) {
     lines.push("", "Findings:");
     for (const finding of result.findings.slice(0, 8)) {

package/docs/FULL_REFERENCE.md

@@ -195,8 +195,13 @@ snipara-companion workflow resume --include-session-context
 - `brief` is the short alias for `intelligence brief`.
 - `reality-check` compares changed files, linked intent, context docs, symbols,
   and verification hints to flag contradiction-to-reality risks before commit or
-  merge. Use `--enforce` in local hooks when review-required findings should
-  fail the hook.
+  merge. Output includes an Intent Ledger section with source-backed intent
+  coverage, confidence, affected anchors, and missing intent anchors, plus an
+  Unknown Registry section that ranks missing intent, missing verification,
+  dirty local evidence, architecture drift, stale/review-pending intent, and
+  heuristic-calibration gaps. Keep `--enforce` opt-in for narrow hooks or
+  calibrated CI adapters; the V1 heuristics are advisory and can produce false
+  positives on broad text/path matches.
 - `timeline` is the Git-style log for workflow starts, phase starts, phase
   commits, final commits, and Team Sync handoffs.
 - `workflow impact-gate` audits committed local workflow phases that are ahead
@@ -951,7 +956,9 @@ snipara-companion reality-check \
 The command reads the local Git scope by default, includes dirty files unless
 `--no-include-dirty` is set, and also accepts explicit `--changed-files` for
 hooks or CI collectors. `--enforce` exits non-zero for `review_required` or
-`blocking` findings; JSON output is available with `--json`.
+`blocking` findings, but should stay opt-in until the matched surfaces,
+verification signals, and project-specific thresholds have been calibrated.
+JSON output is available with `--json`.
 
 Use `intelligence ledger-export` when an agent run, review, or replay benchmark
 needs a portable Coding Intelligence Ledger instead of a raw transcript:
@@ -1028,7 +1035,7 @@ Semantics:
 - `snipara-companion status` = top-level agentic work status across local workflow state, git dirtiness, and Team Sync carryover
 - `snipara-companion source init|sync|status|snapshot|watch` = automatic local source activation for folders with or without Git metadata; writes `.snipara/source/latest.json`, previews document sync, and refreshes the local code overlay cache
 - `snipara-companion brief` = short alias for `snipara-companion intelligence brief`
-- `snipara-companion reality-check` = local Project Reality Check for supplied or Git-derived changed files; `--enforce` makes review-required contradiction-to-reality findings fail hooks
+- `snipara-companion reality-check` = local Project Reality Check plus Intent Ledger and Unknown Registry coverage for supplied or Git-derived changed files; `--enforce` is an opt-in strict mode for calibrated hooks
 - `snipara-companion timeline` = local timeline of workflow starts, phase starts, phase commits, final commits, and Team Sync handoffs
 - `snipara-companion handoff` = top-level agent-ready Markdown/JSON handoff artifact plus the same local/hosted Team Sync handoff persistence
 - `snipara-companion intelligence brief` = one local Project Intelligence brief that combines resume context, memory health, and code impact for a task

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.0.7",
+  "version": "3.0.8",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {