@remnic/core 9.69.54 → 9.69.56

package/src/shared-context/governance-wiring.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Regression: #1957 governance controls 2-4 wired into the REAL manager
+ * synthesis and curation paths (issue #3012).
+ *
+ * - Control 2: an expired item never appears in cross-signals sources or the
+ *   roundtable; a superseded item that still circulates is marked, not dropped.
+ * - Control 3: two agents ruling differently on the same feedback ref surface
+ *   as a disputed section citing both — neither entry is silently dropped.
+ * - Control 4: the persisted report carries curator provenance and every
+ *   synthesized overlap claim cites source item ids (lint tripwire holds).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { SharedContextManager } from "./manager.js";
+import { parseConfig } from "../config.js";
+
+async function makeManager() {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-gov-wiring-"));
+  const config = parseConfig({
+    sharedContextEnabled: true,
+    sharedContextDir: dir,
+  });
+  const manager = new SharedContextManager(config);
+  await manager.ensureStructure();
+  return { manager, dir };
+}
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/** Stored-item shape the write path cannot produce (past expiry), but the
+ *  read path must still classify: legacy or externally written items. */
+async function writeStoredItem(
+  dir: string,
+  opts: { agent: string; title: string; expiresAt?: string; supersedes?: string },
+): Promise<string> {
+  const dayDir = path.join(dir, "agent-outputs", opts.agent, today());
+  await mkdir(dayDir, { recursive: true });
+  const fp = path.join(dayDir, `000000-${opts.title.replace(/\s+/g, "-").toLowerCase()}.md`);
+  const frontmatter = [
+    "kind: agent_output",
+    `agent: ${JSON.stringify(opts.agent)}`,
+    `createdAt: ${new Date().toISOString()}`,
+    `title: ${JSON.stringify(opts.title)}`,
+    ...(opts.expiresAt ? [`expiresAt: ${JSON.stringify(opts.expiresAt)}`] : []),
+    ...(opts.supersedes ? [`supersedes: ${JSON.stringify(opts.supersedes)}`] : []),
+  ];
+  await writeFile(fp, `---\n${frontmatter.join("\n")}\n---\n\nbody text about deploy runbook\n`, "utf-8");
+  return fp;
+}
+
+test("expired items never appear in cross-signals or curation; superseded circulation is marked", async (t) => {
+  const { manager, dir } = await makeManager();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  const livePath = await writeStoredItem(dir, { agent: "agent-live", title: "live item" });
+  const expiredPath = await writeStoredItem(dir, {
+    agent: "agent-old",
+    title: "expired item",
+    expiresAt: "2020-01-01T00:00:00.000Z",
+  });
+
+  const signals = await manager.synthesizeCrossSignals({ date: today() });
+  const paths = signals.report.sources.map((source) => source.path);
+  assert.ok(paths.includes(livePath), "live item must appear in sources");
+  assert.ok(!paths.includes(expiredPath), "expired item must never appear in sources");
+  assert.equal(signals.report.staleness.expiredDropped, 1);
+  assert.deepEqual(signals.report.staleness.supersededStillCirculating, []);
+
+  const curation = await manager.curateDaily({ date: today() });
+  const roundtable = await readFile(curation.roundtablePath, "utf-8");
+  assert.ok(!roundtable.includes(expiredPath), "expired item must never appear in the roundtable");
+  assert.match(roundtable, /## Staleness/);
+  assert.match(roundtable, /Expired items dropped: 1/);
+});
+
+test("a superseded item that still circulates is marked, not dropped", async (t) => {
+  const { manager, dir } = await makeManager();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  const olderPath = await writeStoredItem(dir, { agent: "agent-a", title: "older item" });
+  await writeStoredItem(dir, { agent: "agent-b", title: "newer item", supersedes: olderPath });
+
+  const signals = await manager.synthesizeCrossSignals({ date: today() });
+  assert.deepEqual(signals.report.staleness.supersededStillCirculating, [olderPath]);
+  const paths = signals.report.sources.map((source) => source.path);
+  assert.ok(paths.includes(olderPath), "superseded item still circulates (marked, not dropped)");
+
+  const curation = await manager.curateDaily({ date: today() });
+  const roundtable = await readFile(curation.roundtablePath, "utf-8");
+  assert.match(roundtable, /Superseded items still circulating: 1/);
+});
+
+test("contradictory agent rulings on the same ref surface as disputed, both preserved", async (t) => {
+  const { manager, dir } = await makeManager();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  await manager.appendFeedback({
+    agent: "agent-a",
+    decision: "approved",
+    reason: "matches the runbook",
+    date: `${today()}T10:00:00.000Z`,
+    refs: ["out-0001"],
+  });
+  await manager.appendFeedback({
+    agent: "agent-b",
+    decision: "rejected",
+    reason: "misses the rollback step",
+    date: `${today()}T11:00:00.000Z`,
+    refs: ["out-0001"],
+  });
+
+  const signals = await manager.synthesizeCrossSignals({ date: today() });
+  assert.deepEqual(signals.report.disputed, [
+    { ref: "out-0001", agents: ["agent-a", "agent-b"], decisions: ["approved", "rejected"] },
+  ]);
+  assert.equal(signals.report.feedbackEntries.length, 2, "neither disputed entry is dropped");
+
+  const curation = await manager.curateDaily({ date: today() });
+  const roundtable = await readFile(curation.roundtablePath, "utf-8");
+  assert.match(roundtable, /## Disputed/);
+  assert.match(roundtable, /`out-0001` disputed by agent-a, agent-b/);
+  assert.match(roundtable, /agent-a\] approved/);
+  assert.match(roundtable, /agent-b\] rejected/);
+});
+
+test("curation report carries provenance and cited synthesized claims", async (t) => {
+  const { manager, dir } = await makeManager();
+  t.after(() => rm(dir, { recursive: true, force: true }));
+
+  // Two agents on one topic produce a synthesized overlap claim.
+  await manager.writeAgentOutput({ agentId: "agent-a", title: "deploy runbook notes", content: "deploy runbook steps" });
+  await manager.writeAgentOutput({ agentId: "agent-b", title: "deploy runbook review", content: "deploy runbook feedback" });
+
+  const signals = await manager.synthesizeCrossSignals({ date: today() });
+  assert.equal(signals.report.provenance.actor, "shared-context:curation");
+  assert.ok(!Number.isNaN(Date.parse(signals.report.provenance.at)), "provenance.at is a valid instant");
+  assert.ok(signals.report.overlaps.length > 0, "shared topic produces an overlap claim");
+  for (const overlap of signals.report.overlaps) {
+    assert.ok(overlap.sourcePaths.length > 0, `overlap ${overlap.token} cites source item ids`);
+  }
+
+  // The curation self-check gates the roundtable: it throws on an
+  // uncited synthesized claim and passes when every claim cites.
+  const curation = await manager.curateDaily({ date: today() });
+  const roundtable = await readFile(curation.roundtablePath, "utf-8");
+  assert.match(roundtable, /\[sources: [^\]]+\]/, "synthesized overlap claims cite their sources");
+});

package/src/shared-context/manager.ts

@@ -15,6 +15,10 @@ import {
   resolveWriteOrigin,
 } from "./envelope-io.js";
 import type { SharedAuthority, SharedEnvelope } from "./governance.js";
+import { detectContradictionPair } from "./contradictions.js";
+import { lintCuratedClaims } from "./curation-lint.js";
+import { stampProvenance } from "./provenance.js";
+import { filterLiveEnvelopes, markSupersededCirculation } from "./staleness.js";
 
 export const SharedFeedbackEntrySchema = z.object({
   agent: z.string().min(1),
@@ -341,6 +345,15 @@ interface SharedCrossSignalReport {
   feedbackEntries: SharedFeedbackEntry[];
   sources: SharedCrossSignalSource[];
   overlaps: SharedCrossSignalOverlap[];
+  /** Control 2 (issue #1957): expiry drops and supersession circulation. */
+  staleness: {
+    expiredDropped: number;
+    supersededStillCirculating: string[];
+  };
+  /** Control 3 (issue #1957): refs two agents ruled on differently. */
+  disputed: Array<{ ref: string; agents: string[]; decisions: string[] }>;
+  /** Control 4 (issue #1957): who synthesized this report and when. */
+  provenance: { actor: string; at: string };
   semantic: {
     enabled: boolean;
     applied: boolean;
@@ -418,6 +431,23 @@ function formatOverlapLine(entry: SharedCrossSignalOverlap): string {
   return `- \`${entry.token}\` (${entry.agentCount} agents: ${markdownLineList(entry.agents)}) [sources: ${markdownLineList(entry.sourcePaths)}]`;
 }
 
+function formatStalenessLines(report: SharedCrossSignalReport): string[] {
+  const circulating = report.staleness.supersededStillCirculating;
+  return [
+    `- Expired items dropped: ${report.staleness.expiredDropped}`,
+    circulating.length === 0
+      ? "- Superseded items still circulating: 0"
+      : `- Superseded items still circulating: ${circulating.length} (${markdownLineList(circulating)})`,
+  ];
+}
+
+function formatDisputedLines(report: SharedCrossSignalReport): string[] {
+  if (report.disputed.length === 0) return ["- No contradictory agent judgments recorded."];
+  return report.disputed.map((entry) =>
+    `- \`${entry.ref}\` disputed by ${markdownLineList(entry.agents)} (decisions: ${markdownLineList(entry.decisions)})`
+  );
+}
+
 async function writeFileAtomic(filePath: string, content: string): Promise<void> {
   await mkdir(path.dirname(filePath), { recursive: true });
   const tempPath = path.join(
@@ -730,6 +760,20 @@ export class SharedContextManager {
         || a.title.localeCompare(b.title),
     );
 
+    // Control 2 (issue #1957): expired items never enter the working set;
+    // items another live item supersedes are marked while they circulate.
+    const liveOutputs = filterLiveEnvelopes(
+      outputs.map((output) => ({ output, expiresAt: output.envelope.expiresAt })),
+      Date.now(),
+    ).map((entry) => entry.output);
+    const expiredDropped = outputs.length - liveOutputs.length;
+    const supersededStillCirculating = markSupersededCirculation(
+      liveOutputs.map((output) => ({ id: output.path, supersedes: output.envelope.supersedes })),
+    )
+      .filter((item) => item.circulating === true)
+      .map((item) => item.id)
+      .sort();
+
     // Collect feedback entries for the day.
     const feedback: SharedFeedbackEntry[] = [];
     try {
@@ -749,7 +793,7 @@ export class SharedContextManager {
       // ignore
     }
 
-    const sources: SharedCrossSignalSource[] = outputs.map((output) => {
+    const sources: SharedCrossSignalSource[] = liveOutputs.map((output) => {
       const body = stripYamlFrontmatter(output.raw);
       return {
         agent: output.agent,
@@ -828,15 +872,44 @@ export class SharedContextManager {
       feedbackByDecision[entry.decision] += 1;
     }
 
-    const report: SharedCrossSignalReport = {
+    // Control 3 (issue #1957): feedback refs are claim keys; two agents
+    // ruling differently on the same ref surface as disputed, never silently
+    // averaged. Pairwise scan is bounded by one day's feedback entries.
+    const claimItems = feedback.map((entry, index) => ({
+      id: `${entry.agent}#${index}`,
+      claims: Object.fromEntries((entry.refs ?? []).map((ref) => [ref, entry.decision])),
+    }));
+    const disputedByRef = new Map<string, { agents: Set<string>; decisions: Set<string> }>();
+    for (let i = 0; i < claimItems.length; i++) {
+      for (let j = i + 1; j < claimItems.length; j++) {
+        const pair = detectContradictionPair(claimItems[i]!, claimItems[j]!);
+        if (pair.kind !== "conflict") continue;
+        for (const ref of pair.keys) {
+          const slot = disputedByRef.get(ref) ?? { agents: new Set<string>(), decisions: new Set<string>() };
+          slot.agents.add(feedback[i]!.agent);
+          slot.agents.add(feedback[j]!.agent);
+          slot.decisions.add(feedback[i]!.decision);
+          slot.decisions.add(feedback[j]!.decision);
+          disputedByRef.set(ref, slot);
+        }
+      }
+    }
+    const disputed = [...disputedByRef.entries()]
+      .map(([ref, slot]) => ({ ref, agents: [...slot.agents].sort(), decisions: [...slot.decisions].sort() }))
+      .sort((a, b) => a.ref.localeCompare(b.ref));
+
+    const generatedAt = new Date().toISOString();
+    const baseReport = {
       date,
-      generatedAt: new Date().toISOString(),
+      generatedAt,
       sourceCount: sources.length,
       feedbackCount: feedback.length,
       feedbackByDecision,
       feedbackEntries: [...feedback].sort(compareFeedbackPriority),
       sources,
       overlaps: mergedOverlaps,
+      staleness: { expiredDropped, supersededStillCirculating },
+      disputed,
       semantic: {
         enabled: semanticEnabled,
         applied: semanticApplied,
@@ -846,6 +919,8 @@ export class SharedContextManager {
         addedOverlapCount: semanticAddedOverlapCount,
       },
     };
+    // Control 4 (issue #1957): stamp who synthesized the report and when.
+    const report = stampProvenance(baseReport, { actor: "shared-context:curation", at: generatedAt });
 
     const crossSignalsPath = path.join(this.crossSignalsDir, `${date}.json`);
     await writeFileAtomic(crossSignalsPath, `${JSON.stringify(report, null, 2)}\n`);
@@ -879,6 +954,12 @@ export class SharedContextManager {
       `- Semantic enhancer: ${semanticEnabled ? (semanticTimedOut ? "enabled (timed out, fail-open)" : semanticApplied ? "enabled (applied)" : "enabled (no additional overlaps)") : "disabled"}`,
       `- JSON report: ${crossSignalsPath}`,
       "",
+      "## Staleness",
+      ...formatStalenessLines(report),
+      "",
+      "## Disputed",
+      ...formatDisputedLines(report),
+      "",
       "## Recurring Themes",
       ...recurringThemeLines,
       "",
@@ -916,6 +997,19 @@ export class SharedContextManager {
     const date = opts.date;
     const maxChars = Math.max(2_000, opts.maxChars ?? 20_000);
     const crossSignals = await this.synthesizeCrossSignalsUnlocked({ date });
+    // Control 4 (issue #1957): every synthesized claim must cite at least one
+    // item this run actually had. Overlaps are built from sources, so this is
+    // a tripwire — it fires only if a synthesized section stops citing.
+    const lintFindings = lintCuratedClaims({
+      claims: crossSignals.report.overlaps.map((overlap) => ({
+        claimId: `overlap:${overlap.token}`,
+        citedItemIds: overlap.sourcePaths,
+      })),
+      availableItemIds: crossSignals.report.sources.map((source) => source.path),
+    });
+    if (lintFindings.length > 0) {
+      throw new Error(`shared-context curation self-check failed: ${JSON.stringify(lintFindings)}`);
+    }
     const feedbackLines = crossSignals.report.feedbackEntries.length === 0
       ? ["- (none)"]
       : crossSignals.report.feedbackEntries.map((entry) => formatFeedbackLine(entry));
@@ -944,8 +1038,15 @@ export class SharedContextManager {
       `- Cross-signals markdown: ${crossSignals.crossSignalsMarkdownPath}`,
       ...overlapBullets,
       "",
+      "## Staleness",
+      ...formatStalenessLines(crossSignals.report),
+      "",
+      "## Disputed",
+      ...formatDisputedLines(crossSignals.report),
+      "",
     ];
 
+
     const out = md.join("\n");
     const trimmed = out.length > maxChars ? out.slice(0, maxChars) + "\n\n...(trimmed)\n" : out;
 

package/src/shared-context/staleness.ts

@@ -27,7 +27,7 @@ export function filterLiveEnvelopes<T extends { expiresAt?: string }>(
  */
 export function markSupersededCirculation<T extends SharedStalenessItem>(
   items: readonly T[],
-): T[] {
+): (T & { circulating?: boolean })[] {
   const supersededIds = new Set<string>();
   for (const item of items) {
     if (item.supersedes) supersededIds.add(item.supersedes);