@jenga-ai/agent 3.4.0 → 3.6.0

package/scripts/populate-knowledge-graph.entity-resolution.test.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * @file scripts/populate-knowledge-graph.entity-resolution.test.js
+ * Plain Node `assert`-based unit tests for E20_S10_T04's canonical-key entity-resolution
+ * merge-on-write logic in scripts/populate-knowledge-graph.js (canonicalKey, resolveNodeIdentity,
+ * mergeGraph's key-based merge branch). No test-framework dependency — same convention as
+ * project/app/api/parsers/knowledge-graph.test.js.
+ *
+ * Why a unit-level test file rather than only CLI-level bats coverage (tests/populate-knowledge-graph.bats):
+ * this populator currently only ever computes `source: 'board'` nodes from board frontmatter, whose
+ * `id` IS already the canonical key input (an Epic/Story's own stable board id) — so there is no
+ * live producer of a "different id, same key" scenario to exercise end-to-end through the CLI yet.
+ * The merge machinery is general-purpose infrastructure ahead of its real caller (a future
+ * `human`/`ast` writer) — exercising it directly against synthetic node fixtures is the correct
+ * level for that, per E20_S10_T04-plan.md.
+ *
+ * Run directly:
+ *   node scripts/populate-knowledge-graph.entity-resolution.test.js
+ */
+
+import assert from 'node:assert';
+import {
+  canonicalKey,
+  resolveNodeIdentity,
+  mergeGraph,
+} from './populate-knowledge-graph.js';
+
+async function main() {
+
+  const tests = [];
+  function test(name, fn) {
+    tests.push({ name, fn });
+  }
+
+  // -----------------------------------------------------------------------------------------
+  // canonicalKey()
+  // -----------------------------------------------------------------------------------------
+
+  test('canonicalKey: epic/story key on their own normalized id', () => {
+    assert.strictEqual(canonicalKey({ id: 'E90', type: 'epic' }), 'epic:e90');
+    assert.strictEqual(canonicalKey({ id: 'E90_S01', type: 'story' }), 'story:e90_s01');
+  });
+
+  test('canonicalKey: epic/story ids are case- and whitespace-normalized', () => {
+    assert.strictEqual(canonicalKey({ id: '  E90  ', type: 'epic' }), canonicalKey({ id: 'e90', type: 'epic' }));
+  });
+
+  test('canonicalKey: other node types key on normalized label', () => {
+    assert.strictEqual(
+      canonicalKey({ id: 'svc-1', type: 'service', label: 'Billing Worker' }),
+      canonicalKey({ id: 'svc-2', type: 'service', label: '  billing   worker ' })
+    );
+  });
+
+  test('canonicalKey: distinct labels never collide (conservative, exact-normalized match only)', () => {
+    assert.notStrictEqual(
+      canonicalKey({ id: 'svc-1', type: 'service', label: 'Billing Worker' }),
+      canonicalKey({ id: 'svc-2', type: 'service', label: 'Billing Workers' })
+    );
+  });
+
+  test('canonicalKey: a node with no usable key returns null (never over-merges)', () => {
+    assert.strictEqual(canonicalKey({ id: 'x', type: 'service' }), null); // no label
+    assert.strictEqual(canonicalKey(null), null);
+    assert.strictEqual(canonicalKey({ id: 'x' }), null); // no type
+  });
+
+  test('canonicalKey: different types with the same label never collide', () => {
+    assert.notStrictEqual(
+      canonicalKey({ id: 'a', type: 'service', label: 'Auth' }),
+      canonicalKey({ id: 'b', type: 'module', label: 'Auth' })
+    );
+  });
+
+  // -----------------------------------------------------------------------------------------
+  // resolveNodeIdentity() — genuine merge case
+  // -----------------------------------------------------------------------------------------
+
+  test('resolveNodeIdentity: a computed node matching an existing key under a DIFFERENT id merges into the existing id', () => {
+    const nodeMap = new Map([
+      ['svc-existing', { id: 'svc-existing', type: 'service', label: 'Billing Worker', description: 'old desc', source: 'ast' }],
+    ]);
+    const keyIndex = new Map([[canonicalKey({ type: 'service', label: 'Billing Worker' }), 'svc-existing']]);
+    const mergeLog = [];
+
+    resolveNodeIdentity(
+      nodeMap,
+      'svc-new',
+      { id: 'svc-new', type: 'service', label: 'Billing Worker', description: 'new desc', source: 'ast' },
+      keyIndex,
+      mergeLog
+    );
+
+    assert.strictEqual(nodeMap.size, 1, 'no second node should be created for the same entity');
+    assert.ok(!nodeMap.has('svc-new'), 'the incoming id must not become a new map entry');
+    const merged = nodeMap.get('svc-existing');
+    assert.strictEqual(merged.id, 'svc-existing', 'the existing (target) id must remain stable');
+    assert.strictEqual(merged.description, 'new desc', 'fields update from the incoming node');
+    assert.strictEqual(mergeLog.length, 1);
+    assert.strictEqual(mergeLog[0].targetId, 'svc-existing');
+    assert.strictEqual(mergeLog[0].mergedFromId, 'svc-new');
+    assert.ok(mergeLog[0].changedFields.includes('description'));
+  });
+
+  test('resolveNodeIdentity: merging never downgrades an existing human/ast source via a lower-precedence board write', () => {
+    const nodeMap = new Map([
+      ['svc-existing', { id: 'svc-existing', type: 'service', label: 'Billing Worker', source: 'human' }],
+    ]);
+    const keyIndex = new Map([[canonicalKey({ type: 'service', label: 'Billing Worker' }), 'svc-existing']]);
+    const mergeLog = [];
+
+    resolveNodeIdentity(
+      nodeMap,
+      'svc-new',
+      { id: 'svc-new', type: 'service', label: 'Billing Worker', source: 'board' },
+      keyIndex,
+      mergeLog
+    );
+
+    assert.strictEqual(nodeMap.get('svc-existing').source, 'human', 'source must not be downgraded by a board write');
+  });
+
+  test('resolveNodeIdentity: merging upgrades a board source to human/ast when the incoming write is verified', () => {
+    const nodeMap = new Map([
+      ['svc-existing', { id: 'svc-existing', type: 'service', label: 'Billing Worker', source: 'board' }],
+    ]);
+    const keyIndex = new Map([[canonicalKey({ type: 'service', label: 'Billing Worker' }), 'svc-existing']]);
+    const mergeLog = [];
+
+    resolveNodeIdentity(
+      nodeMap,
+      'svc-new',
+      { id: 'svc-new', type: 'service', label: 'Billing Worker', source: 'ast' },
+      keyIndex,
+      mergeLog
+    );
+
+    assert.strictEqual(nodeMap.get('svc-existing').source, 'ast');
+    assert.ok(mergeLog[0].changedFields.includes('source'));
+  });
+
+  // -----------------------------------------------------------------------------------------
+  // resolveNodeIdentity() — legitimate near-miss (must NOT merge)
+  // -----------------------------------------------------------------------------------------
+
+  test('resolveNodeIdentity: a near-miss (distinct canonical key) creates a separate node, no merge', () => {
+    const nodeMap = new Map([
+      ['svc-existing', { id: 'svc-existing', type: 'service', label: 'Billing Worker', source: 'ast' }],
+    ]);
+    // keyIndex reflects only the existing node's own key — "Billing Workers" (plural) has a
+    // distinct canonical key and is absent from the index, so no match is possible.
+    const keyIndex = new Map([[canonicalKey({ type: 'service', label: 'Billing Worker' }), 'svc-existing']]);
+    const mergeLog = [];
+
+    resolveNodeIdentity(
+      nodeMap,
+      'svc-other',
+      { id: 'svc-other', type: 'service', label: 'Billing Workers', source: 'ast' },
+      keyIndex,
+      mergeLog
+    );
+
+    assert.strictEqual(nodeMap.size, 2, 'a legitimately distinct entity must get its own node');
+    assert.ok(nodeMap.has('svc-other'));
+    assert.strictEqual(mergeLog.length, 0, 'no merge should be logged for a near-miss');
+  });
+
+  test('resolveNodeIdentity: a computed node whose key matches an existing node under the SAME id is a no-op merge (not logged as a key-based merge)', () => {
+    const nodeMap = new Map([
+      ['E90', { id: 'E90', type: 'epic', label: 'Test Epic', description: 'old', source: 'board' }],
+    ]);
+    const keyIndex = new Map([[canonicalKey({ id: 'E90', type: 'epic' }), 'E90']]);
+    const mergeLog = [];
+
+    resolveNodeIdentity(
+      nodeMap,
+      'E90',
+      { id: 'E90', type: 'epic', label: 'Test Epic', description: 'new', source: 'board' },
+      keyIndex,
+      mergeLog
+    );
+
+    assert.strictEqual(nodeMap.size, 1);
+    assert.strictEqual(nodeMap.get('E90').description, 'new', 'plain id-keyed update still applies');
+    assert.strictEqual(mergeLog.length, 0, 'matching under the same id is the pre-existing idempotent case, not a key-based merge');
+  });
+
+  // -----------------------------------------------------------------------------------------
+  // mergeGraph() — end-to-end through the public merge entrypoint
+  // -----------------------------------------------------------------------------------------
+
+  test('mergeGraph: existing idempotent-on-id behavior (E20_S09) is not regressed', () => {
+    const existing = {
+      nodes: [{ id: 'E90', type: 'epic', label: 'Test Epic', description: 'd', source: 'board' }],
+      edges: [],
+    };
+    const computed = {
+      nodes: new Map([['E90', { id: 'E90', type: 'epic', label: 'Test Epic', description: 'd', source: 'board' }]]),
+      edges: new Map(),
+    };
+
+    const first = mergeGraph(existing, computed);
+    const second = mergeGraph({ nodes: first.nodes, edges: first.edges }, computed);
+
+    assert.deepStrictEqual(first.nodes, second.nodes);
+    assert.strictEqual(second.nodes.length, 1);
+    assert.strictEqual(second.mergeLog.length, 0);
+  });
+
+  test('mergeGraph: a genuine key-based merge reduces two entries to one and logs the merge', () => {
+    const existing = {
+      nodes: [{ id: 'svc-existing', type: 'service', label: 'Billing Worker', description: 'old', source: 'ast' }],
+      edges: [],
+    };
+    const computed = {
+      nodes: new Map([
+        ['svc-new', { id: 'svc-new', type: 'service', label: 'Billing Worker', description: 'updated', source: 'ast' }],
+      ]),
+      edges: new Map(),
+    };
+
+    const result = mergeGraph(existing, computed);
+
+    assert.strictEqual(result.nodes.length, 1);
+    assert.strictEqual(result.nodes[0].id, 'svc-existing');
+    assert.strictEqual(result.nodes[0].description, 'updated');
+    assert.strictEqual(result.mergeLog.length, 1);
+  });
+
+  test('mergeGraph: return value is JSON-serializable as exactly {nodes, edges} for graph.json (mergeLog is reporting-only)', () => {
+    const existing = { nodes: [], edges: [] };
+    const computed = { nodes: new Map(), edges: new Map() };
+    const result = mergeGraph(existing, computed);
+    const { nodes, edges } = result;
+    assert.deepStrictEqual(JSON.parse(JSON.stringify({ nodes, edges })), { nodes: [], edges: [] });
+  });
+
+  let failures = 0;
+  for (const { name, fn } of tests) {
+    try {
+      await fn();
+      console.log(`PASS - ${name}`);
+    } catch (err) {
+      failures += 1;
+      console.error(`FAIL - ${name}`);
+      console.error(err && err.stack ? err.stack : err);
+    }
+  }
+
+  console.log(`\n${tests.length - failures}/${tests.length} passed`);
+  if (failures > 0) process.exitCode = 1;
+}
+
+main();

package/scripts/populate-knowledge-graph.js

@@ -42,6 +42,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.join(__dirname, '..');
@@ -49,7 +50,21 @@ const REPO_ROOT = path.join(__dirname, '..');
 const EPIC_ID_RE = /^E\d+$/;
 const STORY_ID_RE = /^E\d+_S\d+$/;
 
-const NODE_KEY_ORDER = ['id', 'type', 'label', 'description', 'source', 'status', 'superseded_by'];
+// E20_S10_T05: extracted_at/content_hash/needs_revalidation are appended after the pre-existing
+// fields — never inserted in the middle — so a graph.json written before E20_S10_T05 diffs
+// cleanly against one written after it for every node that doesn't carry the new fields.
+const NODE_KEY_ORDER = [
+  'id',
+  'type',
+  'label',
+  'description',
+  'source',
+  'status',
+  'superseded_by',
+  'extracted_at',
+  'content_hash',
+  'needs_revalidation',
+];
 const EDGE_KEY_ORDER = ['id', 'from', 'to', 'type', 'description'];
 
 // ── CLI args ────────────────────────────────────────────────────────────────
@@ -326,6 +341,168 @@ function isBoardOwnedEdgeId(id) {
   return BOARD_EDGE_ID_PREFIXES.some((prefix) => id.startsWith(prefix));
 }
 
+// ── Entity resolution (E20_S10_T04) ────────────────────────────────────────
+//
+// This governs *whether two nodes are the same node at all* — distinct from, and does not
+// replace, STUB_SCHEMA.md's Evidence-Wins Conflict Rule (which governs *which description wins*
+// once two nodes are already known to be the same entity). A node's literal `id` is already this
+// populator's own stable identity for its own `board`-sourced writes (an Epic/Story's own board
+// id never changes shape between runs), so key-based merging is infrastructure ahead of its real
+// caller: a future `human`/`ast` writer describing the same real-world entity under a different
+// literal `id` than an existing node. Deliberately conservative (under-merging on purpose, per the
+// task's own instruction to start narrow and expand only on observed false negatives) — a node
+// with no usable key returns `null` and is matched by `id` only, never over-merged.
+
+const SOURCE_PRECEDENCE = { human: 2, ast: 2, board: 1 };
+
+function sourcePrecedence(source) {
+  return SOURCE_PRECEDENCE[source] ?? 0;
+}
+
+function normalizeKeyPart(value) {
+  return String(value ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+/**
+ * Compute a node's canonical identity key, or `null` if this node type has no reliable key yet.
+ * `epic`/`story` key on their own (already-stable) board id, matching this populator's existing
+ * identity scheme. Any other type (e.g. a future `service`/`module`/`function` from an `ast`/
+ * `human` writer) keys on its normalized `label` — exact-normalized, not fuzzy, per the
+ * conservative-by-design instruction above.
+ * @param {{id: string, type: string, label?: string}} node
+ * @returns {string|null}
+ */
+function canonicalKey(node) {
+  if (!node || !node.type) return null;
+  if (node.type === 'epic' || node.type === 'story') {
+    return node.id ? `${node.type}:${normalizeKeyPart(node.id)}` : null;
+  }
+  return node.label ? `${node.type}:${normalizeKeyPart(node.label)}` : null;
+}
+
+/**
+ * Resolve a computed node against an existing node map using canonical-key identity resolution,
+ * merging in place (and logging the merge) when a genuine match is found under a *different*
+ * literal id. Falls back to plain `id`-keyed merge/create — completely unchanged from the
+ * pre-E20_S10_T04 behavior — whenever no key-based match applies.
+ * @param {Map<string, object>} nodeMap mutated in place
+ * @param {string} computedId
+ * @param {object} computedNode
+ * @param {Map<string, string>} keyIndex canonical key -> existing node id, built before this run's
+ *   computed nodes are applied (so a computed node is only ever matched against pre-existing data,
+ *   never against another computed node from the same run)
+ * @param {Array<object>} mergeLog appended to in place with a record of every key-based merge
+ */
+function resolveNodeIdentity(nodeMap, computedId, computedNode, keyIndex, mergeLog) {
+  const key = canonicalKey(computedNode);
+  const matchedExistingId = key ? keyIndex.get(key) : undefined;
+
+  if (matchedExistingId && matchedExistingId !== computedId) {
+    // Genuine key-based merge: same canonical identity, different literal id. Merge into the
+    // EXISTING node's id (stable target) rather than creating a second node for the same entity.
+    const existingNode = nodeMap.get(matchedExistingId) ?? {};
+    const resolvedSource =
+      sourcePrecedence(computedNode.source) >= sourcePrecedence(existingNode.source)
+        ? computedNode.source
+        : existingNode.source; // never downgrade an existing node's provenance via a lower-precedence write
+
+    const changedFields = [];
+    for (const field of ['label', 'description', 'type']) {
+      if (computedNode[field] !== undefined && computedNode[field] !== existingNode[field]) {
+        changedFields.push(field);
+      }
+    }
+    if (existingNode.source !== resolvedSource) changedFields.push('source');
+
+    const merged = {
+      ...existingNode,
+      ...computedNode,
+      id: existingNode.id, // keep the existing (target) id stable — never renamed by a merge
+      source: resolvedSource,
+    };
+    nodeMap.set(matchedExistingId, canonicalizeKeys(ensureProvenanceMetadata(merged), NODE_KEY_ORDER));
+
+    mergeLog.push({
+      key,
+      targetId: matchedExistingId,
+      mergedFromId: computedId,
+      changedFields,
+      existingSource: existingNode.source,
+      incomingSource: computedNode.source,
+    });
+    return;
+  }
+
+  // No key-based match (or the match IS this same id, i.e. the pre-existing idempotent-on-id
+  // case) — fall back to plain id-keyed merge/create, unchanged from pre-E20_S10_T04 behavior.
+  const merged = { ...(nodeMap.get(computedId) ?? {}), ...computedNode };
+  nodeMap.set(computedId, canonicalizeKeys(ensureProvenanceMetadata(merged), NODE_KEY_ORDER));
+}
+
+// ── Staleness / revalidation (E20_S10_T05) ─────────────────────────────────
+//
+// Gating on `source` alone (E20_S10_T01) relocates, rather than solves, the original "board goes
+// stale" defect: a non-`board` node can itself drift from the source it was extracted from with no
+// signal to the user. `hashSource`/`checkStaleness` are the general-purpose, directly-testable
+// utilities this closes with — deliberately NOT new scheduling infrastructure, per the task's own
+// instruction to hook into an existing lifecycle trigger point instead. This populator has no live
+// `ast`/`human` writer yet (same caveat as E20_S10_T04's entity resolution), so it applies these
+// utilities to its own passthrough of any non-`board` node it merges, using that node's own
+// descriptive text as a content proxy — a future dedicated writer with real source-file text
+// should call `hashSource()` directly with its own normalized content instead of relying on this
+// proxy.
+
+/**
+ * Hash arbitrary content (already normalized by the caller, if normalization is available) into a
+ * short, stable fingerprint. Prefer passing normalized/parsed structure rather than raw bytes when
+ * the caller has one available — e.g. a future AST writer hashing a normalized AST dump rather than
+ * raw file text — so purely cosmetic/formatting-only source changes don't flip staleness.
+ * @param {string} content
+ * @returns {string} hex-encoded sha256 digest
+ */
+function hashSource(content) {
+  return createHash('sha256').update(String(content ?? '')).digest('hex');
+}
+
+/**
+ * Best-effort "source content" proxy for a node with no separately-tracked raw source file: its
+ * own label + description. Used only by this populator's own write path below, which has nothing
+ * else to hash against; a dedicated ast/human writer with real source-file text should hash that
+ * directly via hashSource() instead of going through this proxy.
+ */
+function contentFingerprint(node) {
+  return `${node.label ?? ''}${node.description ?? ''}`;
+}
+
+/**
+ * Compare a node's stored `content_hash` against a freshly computed hash of its current source
+ * content. A node with no stored `content_hash` yet has nothing to compare against — reported as
+ * not stale (never a false "needs re-verification" for a node that was never hash-stamped at all).
+ * @param {{content_hash?: string}} node
+ * @param {string} currentContent
+ * @returns {{stale: boolean}}
+ */
+function checkStaleness(node, currentContent) {
+  if (!node || !node.content_hash) return { stale: false };
+  return { stale: hashSource(currentContent) !== node.content_hash };
+}
+
+/**
+ * Stamp `extracted_at`/`content_hash` on any non-`board` node being written, refreshing
+ * `extracted_at` only when the computed content hash actually changes (so re-running against
+ * unchanged content never bumps the timestamp). `board` nodes are left untouched — this metadata
+ * is scoped to non-`board` provenance per the task's own Acceptance Criteria.
+ * @param {object} node
+ * @param {string} [now] ISO 8601 UTC timestamp; overridable for tests
+ * @returns {object} a new node object (or the same reference, if source is 'board')
+ */
+function ensureProvenanceMetadata(node, now = new Date().toISOString()) {
+  if (!node || node.source === 'board') return node;
+  const hash = hashSource(contentFingerprint(node));
+  if (node.content_hash === hash) return node; // unchanged — keep the existing extracted_at as-is
+  return { ...node, content_hash: hash, extracted_at: now };
+}
+
 function mergeGraph(existing, computed) {
   const nodeMap = new Map(existing.nodes.map((node) => [node.id, node]));
   // Prune stale populator-owned nodes no longer produced this run (e.g. an Epic or Story board
@@ -339,9 +516,18 @@ function mergeGraph(existing, computed) {
       nodeMap.delete(id);
     }
   }
+
+  // Built BEFORE this run's computed nodes are applied, so key-based resolution only ever matches
+  // against pre-existing graph state — never against a sibling computed node from the same pass.
+  const keyIndex = new Map();
+  for (const node of nodeMap.values()) {
+    const key = canonicalKey(node);
+    if (key && !keyIndex.has(key)) keyIndex.set(key, node.id);
+  }
+
+  const mergeLog = [];
   for (const [id, computedNode] of computed.nodes) {
-    const merged = { ...(nodeMap.get(id) ?? {}), ...computedNode };
-    nodeMap.set(id, canonicalizeKeys(merged, NODE_KEY_ORDER));
+    resolveNodeIdentity(nodeMap, id, computedNode, keyIndex, mergeLog);
   }
 
   const edgeMap = new Map(existing.edges.map((edge) => [edge.id, edge]));
@@ -360,7 +546,7 @@ function mergeGraph(existing, computed) {
 
   const nodes = [...nodeMap.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   const edges = [...edgeMap.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-  return { nodes, edges };
+  return { nodes, edges, mergeLog };
 }
 
 // ── Main ─────────────────────────────────────────────────────────────────
@@ -375,9 +561,26 @@ function run(argv) {
   const computed = deriveNodesAndEdges(epics, stories);
 
   const existing = loadExistingGraph(graphPath);
-  const merged = mergeGraph(existing, computed);
+  const { nodes, edges, mergeLog } = mergeGraph(existing, computed);
+  // graph.json's on-disk shape is strictly {nodes, edges} per STUB_SCHEMA.md — mergeLog is
+  // reporting-only and must never be serialized into it.
+  const merged = { nodes, edges };
   const nextContent = `${JSON.stringify(merged, null, 2)}\n`;
 
+  // E20_S10_T04: every key-based merge is logged (what changed, which sources were involved) so a
+  // silent merge never hides a legitimate content difference between sources — printed regardless
+  // of --dry-run, since a merge decision is worth surfacing even on a preview run.
+  for (const entry of mergeLog) {
+    process.stdout.write(
+      `[merge] ${entry.mergedFromId} -> ${entry.targetId} (key: ${entry.key}) — ` +
+        `source ${entry.existingSource ?? 'none'} + ${entry.incomingSource ?? 'none'} -> ${
+          entry.changedFields.includes('source')
+            ? 'upgraded'
+            : entry.existingSource ?? entry.incomingSource
+        }; changed fields: ${entry.changedFields.length ? entry.changedFields.join(', ') : 'none'}\n`,
+    );
+  }
+
   let currentContent = null;
   try {
     currentContent = fs.readFileSync(graphPath, 'utf8');
@@ -425,5 +628,10 @@ export {
   deriveNodesAndEdges,
   loadExistingGraph,
   mergeGraph,
+  canonicalKey,
+  resolveNodeIdentity,
+  hashSource,
+  checkStaleness,
+  ensureProvenanceMetadata,
   run,
 };

package/scripts/populate-knowledge-graph.staleness.test.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * @file scripts/populate-knowledge-graph.staleness.test.js
+ * Plain Node `assert`-based unit tests for E20_S10_T05's staleness/revalidation logic in
+ * scripts/populate-knowledge-graph.js (hashSource, checkStaleness, ensureProvenanceMetadata). Same
+ * no-framework convention as knowledge-graph.test.js and
+ * populate-knowledge-graph.entity-resolution.test.js.
+ *
+ * Run directly:
+ *   node scripts/populate-knowledge-graph.staleness.test.js
+ */
+
+import assert from 'node:assert';
+import {
+  hashSource,
+  checkStaleness,
+  ensureProvenanceMetadata,
+} from './populate-knowledge-graph.js';
+
+async function main() {
+  const tests = [];
+  function test(name, fn) {
+    tests.push({ name, fn });
+  }
+
+  // -----------------------------------------------------------------------------------------
+  // hashSource()
+  // -----------------------------------------------------------------------------------------
+
+  test('hashSource: identical content produces identical hashes', () => {
+    assert.strictEqual(hashSource('hello world'), hashSource('hello world'));
+  });
+
+  test('hashSource: different content produces different hashes', () => {
+    assert.notStrictEqual(hashSource('hello world'), hashSource('hello mars'));
+  });
+
+  test('hashSource: is defined for empty/undefined content (never throws)', () => {
+    assert.doesNotThrow(() => hashSource(''));
+    assert.doesNotThrow(() => hashSource(undefined));
+    assert.strictEqual(hashSource(''), hashSource(undefined));
+  });
+
+  // -----------------------------------------------------------------------------------------
+  // checkStaleness()
+  // -----------------------------------------------------------------------------------------
+
+  test('checkStaleness: reports "unchanged, no badge" (stale: false) when the source hash still matches', () => {
+    const content = 'function billingWorker() { reconcileLedger(); }';
+    const node = { content_hash: hashSource(content) };
+    assert.deepStrictEqual(checkStaleness(node, content), { stale: false });
+  });
+
+  test('checkStaleness: reports "needs re-verification" (stale: true) when the source has changed', () => {
+    const originalContent = 'function billingWorker() { reconcileLedger(); }';
+    const changedContent = 'function billingWorker() { retryCharge(); }'; // materially different
+    const node = { content_hash: hashSource(originalContent) };
+    assert.deepStrictEqual(checkStaleness(node, changedContent), { stale: true });
+  });
+
+  test('checkStaleness: a node with no stored content_hash is never reported stale (nothing to compare against)', () => {
+    assert.deepStrictEqual(checkStaleness({}, 'anything'), { stale: false });
+    assert.deepStrictEqual(checkStaleness(null, 'anything'), { stale: false });
+  });
+
+  // -----------------------------------------------------------------------------------------
+  // ensureProvenanceMetadata()
+  // -----------------------------------------------------------------------------------------
+
+  test('ensureProvenanceMetadata: a board node is left untouched (no extracted_at/content_hash)', () => {
+    const node = { id: 'E90', type: 'epic', label: 'Epic', description: 'd', source: 'board' };
+    const result = ensureProvenanceMetadata(node, '2026-01-01T00:00:00Z');
+    assert.strictEqual(result, node);
+    assert.strictEqual(result.content_hash, undefined);
+    assert.strictEqual(result.extracted_at, undefined);
+  });
+
+  test('ensureProvenanceMetadata: a new non-board node is stamped with content_hash + extracted_at', () => {
+    const node = { id: 'svc-1', type: 'service', label: 'Billing Worker', description: 'd', source: 'ast' };
+    const result = ensureProvenanceMetadata(node, '2026-01-01T00:00:00Z');
+    assert.ok(result.content_hash);
+    assert.strictEqual(result.extracted_at, '2026-01-01T00:00:00Z');
+  });
+
+  test('ensureProvenanceMetadata: re-stamping unchanged content does NOT bump extracted_at (no noisy re-timestamping)', () => {
+    const node = { id: 'svc-1', type: 'service', label: 'Billing Worker', description: 'd', source: 'ast' };
+    const first = ensureProvenanceMetadata(node, '2026-01-01T00:00:00Z');
+    const second = ensureProvenanceMetadata(first, '2026-06-01T00:00:00Z'); // later "now", same content
+    assert.strictEqual(second.extracted_at, '2026-01-01T00:00:00Z', 'extracted_at must not change when content is unchanged');
+    assert.strictEqual(second.content_hash, first.content_hash);
+  });
+
+  test('ensureProvenanceMetadata: content that actually changes DOES bump both content_hash and extracted_at', () => {
+    const node = { id: 'svc-1', type: 'service', label: 'Billing Worker', description: 'd', source: 'ast' };
+    const first = ensureProvenanceMetadata(node, '2026-01-01T00:00:00Z');
+    const changed = { ...first, description: 'materially different description' };
+    const second = ensureProvenanceMetadata(changed, '2026-06-01T00:00:00Z');
+    assert.notStrictEqual(second.content_hash, first.content_hash);
+    assert.strictEqual(second.extracted_at, '2026-06-01T00:00:00Z');
+  });
+
+  test('a purely cosmetic/formatting-only change to normalized input does not flip staleness when the caller passes normalized content', () => {
+    // Simulates a future caller that normalizes whitespace before hashing (e.g. a normalized AST
+    // dump rather than raw file bytes) — per the task's "prefer hashing normalized/parsed
+    // structure over raw bytes where feasible" guidance.
+    const normalize = (raw) => raw.trim().replace(/\s+/g, ' ');
+    const original = 'function billingWorker() {\n  reconcileLedger();\n}\n';
+    const cosmeticallyReformatted = '  function   billingWorker()   {   reconcileLedger();   }  ';
+
+    const node = { content_hash: hashSource(normalize(original)) };
+    assert.deepStrictEqual(checkStaleness(node, normalize(cosmeticallyReformatted)), { stale: false });
+  });
+
+  let failures = 0;
+  for (const { name, fn } of tests) {
+    try {
+      await fn();
+      console.log(`PASS - ${name}`);
+    } catch (err) {
+      failures += 1;
+      console.error(`FAIL - ${name}`);
+      console.error(err && err.stack ? err.stack : err);
+    }
+  }
+
+  console.log(`\n${tests.length - failures}/${tests.length} passed`);
+  if (failures > 0) process.exitCode = 1;
+}
+
+main();

package/scripts/postinstall.js

@@ -49,7 +49,7 @@
  *                "package_version":  "3.0.1",
  *                "generated_at":     "<ISO 8601>",
  *                "dest_root":        ".agents",
- *                "paths":            ["agents/developer.md", "skills/do/SKILL.md"]
+ *                "paths":            ["agents/developer.md", "skills/j-do/SKILL.md"]
  *              }
  *              `paths` are relative to the destination root, POSIX-separated,
  *              deduped and sorted, and record REGULAR FILES ONLY — never