@ijfw/memory-server 1.3.0 → 1.4.1

package/src/gate-result-formatter.js

@@ -0,0 +1,95 @@
+/**
+ * gate-result-formatter.js
+ *
+ * IJFW v1.4.0 Wave 0 / R2 — Gate-Result Formatter
+ *
+ * Utility that guarantees the gate-result block is the LAST emitted content
+ * from a gate. For code-based gates (Trident, preflight) the formatter is
+ * called deterministically before return. For skill-based gates (plan-check,
+ * cross-audit, swarm-review) it exposes a markdown snippet the skill pastes
+ * at end of its SKILL.md output contract (the model then echoes the block
+ * as its last line).
+ *
+ * Companion to `gate-result-schema.js` (t1).
+ */
+
+import { formatGateResult } from './gate-result-schema.js';
+
+const GATE_RESULT_FENCE = /```gate-result\s*\n[\s\S]*?\n```\s*$/;
+
+/**
+ * appendGateResult(outputString, gateResult)
+ *
+ * Append the fenced gate-result block to `outputString`. Idempotent: if
+ * `outputString` already ends with a gate-result fence, replace it rather
+ * than append a duplicate.
+ *
+ * @param {string} outputString
+ * @param {object} gateResult — validated gate-result object
+ * @returns {string}
+ */
+export function appendGateResult(outputString, gateResult) {
+  const base = typeof outputString === 'string' ? outputString : '';
+  const block = formatGateResult(gateResult);
+  const trimmed = base.replace(/\s+$/, '');
+
+  if (GATE_RESULT_FENCE.test(trimmed)) {
+    return trimmed.replace(GATE_RESULT_FENCE, block);
+  }
+
+  return trimmed + (trimmed.length > 0 ? '\n\n' : '') + block;
+}
+
+/**
+ * gateResultBlockOnly(gateResult)
+ *
+ * Return just the fenced gate-result block. Same as `formatGateResult` but
+ * lives in this module so callers depend on `gate-result-formatter` only.
+ *
+ * @param {object} gateResult
+ * @returns {string}
+ */
+export function gateResultBlockOnly(gateResult) {
+  return formatGateResult(gateResult);
+}
+
+/**
+ * gateResultTemplate(gate)
+ *
+ * Returns a markdown snippet skills paste at the end of their SKILL.md
+ * output contract. The snippet instructs the model to emit a gate-result
+ * block as the LAST line of its output, with the supplied `gate` name.
+ *
+ * @param {string} gate
+ * @returns {string}
+ */
+export function gateResultTemplate(gate) {
+  return [
+    '## Output contract',
+    '',
+    `Emit a gate-result block as the LAST line of your output. Use \`gate="${gate}"\`.`,
+    'Statuses: `PASS | CONDITIONAL | WARN | FLAG | FAIL`.',
+    '',
+    'Format:',
+    '',
+    '```gate-result',
+    '{',
+    '  "schema_version": "1.0",',
+    `  "gate": "${gate}",`,
+    '  "status": "PASS",',
+    '  "project_type": "<from project-type-detector>",',
+    '  "lenses": [],',
+    '  "affected_artifacts": [],',
+    '  "accounting": {"duration_ms": 0, "lenses_invoked": 0, "cost_usd": null},',
+    '  "remediation": [],',
+    '  "receipts_ref": null,',
+    '  "supersedes": null,',
+    `  "gate_id": "${gate.replace(/:/g, '-')}-<ts>-<rand4>",`,
+    '  "emitted_at": "<ISO-8601>"',
+    '}',
+    '```',
+    '',
+    'The block MUST be the last content you emit; nothing after it.',
+    '',
+  ].join('\n');
+}

package/src/gate-result-schema.js

@@ -0,0 +1,274 @@
+/**
+ * gate-result-schema.js
+ *
+ * IJFW v1.4.0 Wave 0 / t1 — Gate-Result Schema
+ *
+ * A "gate-result" is the canonical contract emitted by every quality gate
+ * in IJFW (Trident, preflight, plan-check, swarm-review, cross-audit,
+ * override-audit, extension-install). All gates speak this shape so that
+ * downstream consumers (blackboard, receipts, dashboards, remediation
+ * router) can read any gate uniformly.
+ *
+ * Locked decisions (do not relitigate without an ADR):
+ *   - FLAG status is required (it matches Trident's existing 5-level hierarchy).
+ *   - project_type is required at the top level — IJFW is project-agnostic.
+ *     Artifact ref types include book/content concepts, not just `file`.
+ *   - `lenses` is empty for single-model gates (preflight, audit-ci); only
+ *     multi-model gates (Trident, swarm-review, cross-audit) populate it.
+ *   - `remediation` is schema-ready and partially auto-routed in v1.4.0 via
+ *     `memory-feedback.js` (W7/B3), which surfaces pattern hints in the
+ *     prelude when N+ recent gates fail on the same artifact type. Full
+ *     auto-dispatch beyond pattern hints (e.g. cross-skill correlation,
+ *     time-series detection) remains v1.5.0+.
+ *   - `cost_usd` may be null (some gates run locally, free).
+ *   - `gate_id` collapses any `:` in namespaced gates to `-` to keep ids
+ *     filesystem-friendly across all 14 supported platforms.
+ *
+ * Format: gate-result objects are wire-encoded as a fenced
+ *   ```gate-result
+ *   <json>
+ *   ```
+ * block. This lets receipts grep gate-result blocks without parsing
+ * surrounding markdown and lets blackboard collators round-trip them.
+ *
+ * Hand-rolled validator. No joi/zod/ajv — zero new prod dependencies.
+ */
+
+export const SCHEMA_VERSION = '1.0';
+
+/**
+ * Gate name pattern.
+ *   - lowercase alpha-numeric with dashes
+ *   - optional single `:`-delimited namespace (e.g. `preflight:audit-ci`)
+ *   - must start with an alpha char in each segment
+ */
+// eslint-disable-next-line security/detect-unsafe-regex -- anchored kebab + optional `:`-namespaced kebab; non-overlapping branches
+export const GATE_NAME_PATTERN = /^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$/;
+
+export const VALID_STATUSES = Object.freeze([
+  'PASS',
+  'CONDITIONAL',
+  'WARN',
+  'FLAG',
+  'FAIL',
+]);
+
+export const VALID_PROJECT_TYPES = Object.freeze([
+  'software',
+  'book',
+  'content',
+  'business',
+  'design',
+  'mixed',
+  'unknown',
+]);
+
+export const VALID_ARTIFACT_TYPES = Object.freeze([
+  'file',
+  'chapter',
+  'section',
+  'asset',
+  'persona',
+  'decision',
+  'component',
+]);
+
+const ISO8601_PATTERN =
+  // eslint-disable-next-line security/detect-unsafe-regex -- fixed-length anchored ISO 8601 shape; optional fractional + tz are non-overlapping
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+/**
+ * makeGateId(gate) — build a `<gate>-<timestamp>-<rand4>` id.
+ * Namespaced gates collapse `:` to `-` for filesystem safety.
+ *
+ * @param {string} gate
+ * @returns {string}
+ */
+export function makeGateId(gate) {
+  if (typeof gate !== 'string' || !GATE_NAME_PATTERN.test(gate)) {
+    throw new TypeError(
+      `makeGateId: invalid gate name "${gate}" — must match ${GATE_NAME_PATTERN}`,
+    );
+  }
+  const safe = gate.replace(/:/g, '-');
+  const ts = Date.now();
+  // 4-hex random suffix. Math.random is fine here — gate_id collision risk
+  // is operational, not security-critical (Trident audit is the trust gate).
+  const rand4 = Math.floor(Math.random() * 0x10000)
+    .toString(16)
+    .padStart(4, '0');
+  return `${safe}-${ts}-${rand4}`;
+}
+
+
+function isString(v) {
+  return typeof v === 'string';
+}
+
+function isNonNullObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * validateGateResult(obj) — hand-rolled validator.
+ *
+ * @param {unknown} obj
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateGateResult(obj) {
+  const errors = [];
+
+  if (!isNonNullObject(obj)) {
+    return { valid: false, errors: ['root: must be an object'] };
+  }
+
+  // schema_version
+  if (obj.schema_version !== SCHEMA_VERSION) {
+    errors.push(
+      `schema_version: must equal "${SCHEMA_VERSION}", got ${JSON.stringify(obj.schema_version)}`,
+    );
+  }
+
+  // gate
+  if (!isString(obj.gate)) {
+    errors.push('gate: must be a string');
+  } else if (!GATE_NAME_PATTERN.test(obj.gate)) {
+    errors.push(
+      `gate: "${obj.gate}" does not match ${GATE_NAME_PATTERN}`,
+    );
+  }
+
+  // status
+  if (!VALID_STATUSES.includes(obj.status)) {
+    errors.push(
+      `status: must be one of ${VALID_STATUSES.join('|')}, got ${JSON.stringify(obj.status)}`,
+    );
+  }
+
+  // project_type
+  if (!VALID_PROJECT_TYPES.includes(obj.project_type)) {
+    errors.push(
+      `project_type: must be one of ${VALID_PROJECT_TYPES.join('|')}, got ${JSON.stringify(obj.project_type)}`,
+    );
+  }
+
+  // lenses
+  if (!Array.isArray(obj.lenses)) {
+    errors.push('lenses: must be an array (empty for single-model gates)');
+  } else {
+    obj.lenses.forEach((lens, i) => {
+      if (!isNonNullObject(lens)) {
+        errors.push(`lenses[${i}]: must be an object`);
+        return;
+      }
+      if (!isString(lens.model)) errors.push(`lenses[${i}].model: must be a string`);
+      if (!VALID_STATUSES.includes(lens.verdict)) {
+        errors.push(
+          `lenses[${i}].verdict: must be one of ${VALID_STATUSES.join('|')}`,
+        );
+      }
+      if (typeof lens.confidence !== 'number' || lens.confidence < 0 || lens.confidence > 1) {
+        errors.push(`lenses[${i}].confidence: must be number in [0,1]`);
+      }
+      if (!isString(lens.summary)) errors.push(`lenses[${i}].summary: must be a string`);
+    });
+  }
+
+  // affected_artifacts
+  if (!Array.isArray(obj.affected_artifacts)) {
+    errors.push('affected_artifacts: must be an array');
+  } else {
+    obj.affected_artifacts.forEach((a, i) => {
+      if (!isNonNullObject(a)) {
+        errors.push(`affected_artifacts[${i}]: must be an object`);
+        return;
+      }
+      if (!VALID_ARTIFACT_TYPES.includes(a.type)) {
+        errors.push(
+          `affected_artifacts[${i}].type: must be one of ${VALID_ARTIFACT_TYPES.join('|')}`,
+        );
+      }
+      if (!isString(a.ref)) errors.push(`affected_artifacts[${i}].ref: must be a string`);
+      if (!isString(a.role)) errors.push(`affected_artifacts[${i}].role: must be a string`);
+    });
+  }
+
+  // accounting
+  if (!isNonNullObject(obj.accounting)) {
+    errors.push('accounting: must be an object');
+  } else {
+    const a = obj.accounting;
+    if (typeof a.duration_ms !== 'number' || a.duration_ms < 0) {
+      errors.push('accounting.duration_ms: must be a non-negative number');
+    }
+    if (typeof a.lenses_invoked !== 'number' || a.lenses_invoked < 0 || !Number.isInteger(a.lenses_invoked)) {
+      errors.push('accounting.lenses_invoked: must be a non-negative integer');
+    }
+    if (a.cost_usd !== null && (typeof a.cost_usd !== 'number' || a.cost_usd < 0)) {
+      errors.push('accounting.cost_usd: must be null or non-negative number');
+    }
+  }
+
+  // remediation
+  if (!Array.isArray(obj.remediation)) {
+    errors.push('remediation: must be an array (may be empty)');
+  } else {
+    obj.remediation.forEach((r, i) => {
+      if (!isNonNullObject(r)) {
+        errors.push(`remediation[${i}]: must be an object`);
+        return;
+      }
+      if (!isString(r.action)) errors.push(`remediation[${i}].action: must be a string`);
+      if (!isString(r.target)) errors.push(`remediation[${i}].target: must be a string`);
+      if (!isString(r.agent_recommended)) {
+        errors.push(`remediation[${i}].agent_recommended: must be a string`);
+      }
+      if (typeof r.confidence !== 'number' || r.confidence < 0 || r.confidence > 1) {
+        errors.push(`remediation[${i}].confidence: must be number in [0,1]`);
+      }
+    });
+  }
+
+  // receipts_ref
+  if (obj.receipts_ref !== null && !isString(obj.receipts_ref)) {
+    errors.push('receipts_ref: must be a string or null');
+  }
+
+  // supersedes
+  if (obj.supersedes !== null && !isString(obj.supersedes)) {
+    errors.push('supersedes: must be a string or null');
+  }
+
+  // gate_id
+  if (!isString(obj.gate_id) || obj.gate_id.length === 0) {
+    errors.push('gate_id: must be a non-empty string');
+  } else if (isString(obj.gate)) {
+    // Soft-check that gate_id starts with the (colon-collapsed) gate name.
+    const safeGate = obj.gate.replace(/:/g, '-');
+    if (!obj.gate_id.startsWith(safeGate + '-')) {
+      errors.push(
+        `gate_id: expected to start with "${safeGate}-" (colon-collapsed gate name)`,
+      );
+    }
+  }
+
+  // emitted_at
+  if (!isString(obj.emitted_at) || !ISO8601_PATTERN.test(obj.emitted_at)) {
+    errors.push('emitted_at: must be ISO-8601 string');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * formatGateResult(obj) — render a gate-result object as a fenced
+ *   ```gate-result\n<json>\n```
+ * block. Does NOT validate first — call validateGateResult() yourself.
+ *
+ * @param {object} obj
+ * @returns {string}
+ */
+export function formatGateResult(obj) {
+  const json = JSON.stringify(obj, null, 2);
+  return '```gate-result\n' + json + '\n```';
+}

package/src/gate-result.js

@@ -0,0 +1,195 @@
+/**
+ * gate-result.js
+ *
+ * IJFW v1.4.0 Wave 1 / t5 — Gate-Result Emitter
+ *
+ * Consumer surface every quality gate calls to emit a canonical gate-result.
+ * Composes the W0 schema (validation) + formatter modules, fills in defaults,
+ * detects project_type when omitted, and writes a fire-and-forget JSON
+ * receipt under .ijfw/memory/gate-receipts/.
+ *
+ * Discipline:
+ *   - ESM only; built-in Node.js modules only (no new prod deps).
+ *   - ASCII only in strings.
+ *   - Receipt writes MUST NOT throw — the gate's hot path is the priority.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+import {
+  GATE_NAME_PATTERN,
+  SCHEMA_VERSION,
+  VALID_STATUSES,
+  formatGateResult,
+  makeGateId,
+  validateGateResult,
+} from './gate-result-schema.js';
+import { detect as detectProjectType } from './project-type-detector.js';
+
+// Re-exports so consumers can import everything they need from this module.
+export {
+  GATE_NAME_PATTERN,
+  SCHEMA_VERSION,
+  VALID_STATUSES,
+  formatGateResult,
+  makeGateId,
+  validateGateResult,
+};
+
+/**
+ * emitGateResult(gateOpts, context) — build, validate, and format a gate
+ * result. Returns the fenced ```gate-result\n<json>\n``` block.
+ *
+ * @param {{
+ *   gate: string,
+ *   status: string,
+ *   lenses?: Array,
+ *   affected_artifacts?: Array,
+ *   accounting: {duration_ms: number, lenses_invoked: number, cost_usd: number|null},
+ *   remediation?: Array,
+ *   receipts_ref?: string|null,
+ *   supersedes?: string|null,
+ * }} gateOpts
+ * @param {{projectRoot?: string, project_type?: string}} [context]
+ * @returns {Promise<string>}
+ */
+export async function emitGateResult(gateOpts, context = {}) {
+  if (gateOpts === null || typeof gateOpts !== 'object') {
+    throw new TypeError('emitGateResult: gateOpts must be an object');
+  }
+
+  const projectType =
+    typeof context.project_type === 'string' && context.project_type.length > 0
+      ? context.project_type
+      : await resolveProjectType(context.projectRoot);
+
+  const result = {
+    schema_version: SCHEMA_VERSION,
+    gate_id: makeGateId(gateOpts.gate),
+    gate: gateOpts.gate,
+    status: gateOpts.status,
+    project_type: projectType,
+    lenses: Array.isArray(gateOpts.lenses) ? gateOpts.lenses : [],
+    affected_artifacts: Array.isArray(gateOpts.affected_artifacts)
+      ? gateOpts.affected_artifacts
+      : [],
+    accounting: gateOpts.accounting,
+    remediation: Array.isArray(gateOpts.remediation) ? gateOpts.remediation : [],
+    receipts_ref: gateOpts.receipts_ref === undefined ? null : gateOpts.receipts_ref,
+    supersedes: gateOpts.supersedes === undefined ? null : gateOpts.supersedes,
+    emitted_at: new Date().toISOString(),
+  };
+
+  const { valid, errors } = validateGateResult(result);
+  if (!valid) {
+    throw new Error(
+      `emitGateResult: invalid gate-result — ${errors.join('; ')}`,
+    );
+  }
+
+  // Fire-and-forget receipt write. The gate's hot path must NOT block on
+  // disk I/O — makeReceipt swallows its own errors and resolves undefined
+  // on failure. The trailing .catch is belt-and-braces in case a future
+  // refactor lets something escape makeReceipt's try/catch.
+  makeReceipt(result, {
+    projectRoot:
+      typeof context.projectRoot === 'string' && context.projectRoot.length > 0
+        ? context.projectRoot
+        : process.cwd(),
+  }).catch(() => {});
+
+  return formatGateResult(result);
+}
+
+/**
+ * makeReceipt(gateResult) — fire-and-forget JSON receipt write.
+ *
+ * Writes `.ijfw/memory/gate-receipts/<gate_id>.json` (creating parent dirs
+ * as needed). Disk errors are swallowed and logged to stderr; this never
+ * throws so the gate's hot path is never blocked by receipt issues.
+ *
+ * @param {object} gateResult — validated gate-result object (NOT the
+ *   fenced block string). Caller is responsible for passing the object;
+ *   if you only have the block string, JSON.parse the body first.
+ * @param {{projectRoot?: string}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function makeReceipt(gateResult, opts = {}) {
+  try {
+    if (!gateResult || typeof gateResult !== 'object') return;
+    const gateId = typeof gateResult.gate_id === 'string' ? gateResult.gate_id : null;
+    if (!gateId) return;
+
+    // Defence-in-depth against path traversal via a poisoned gate_id.
+    // makeGateId() produces ids matching `<gate>-<ts>-<rand4>` where <gate>
+    // has colons collapsed to hyphens — i.e. lowercase alphanumerics + hyphen
+    // only, starting with a letter. Anything else (e.g. "../" segments,
+    // absolute paths, alternate separators) is rejected outright.
+    if (!RECEIPT_GATE_ID_PATTERN.test(gateId)) {
+      try {
+        process.stderr.write(
+          `ijfw: makeReceipt rejected unsafe gate_id "${gateId}"\n`,
+        );
+      } catch {
+        /* even stderr write can fail in odd environments; nothing to do */
+      }
+      return;
+    }
+    // Belt-and-braces: strip any directory component that slipped past the
+    // regex (e.g. odd Unicode tricks, alternate path separators on Windows).
+    const safeId = basename(gateId);
+
+    const root = typeof opts.projectRoot === 'string' && opts.projectRoot.length > 0
+      ? opts.projectRoot
+      : process.cwd();
+
+    const receiptPath = join(
+      root,
+      '.ijfw',
+      'memory',
+      'gate-receipts',
+      `${safeId}.json`,
+    );
+
+    await mkdir(dirname(receiptPath), { recursive: true });
+    const body = JSON.stringify(gateResult, null, 2) + '\n';
+    await writeFile(receiptPath, body, 'utf8');
+  } catch (err) {
+    // Fire-and-forget: log and move on. The gate hot path must not fail.
+    const msg = err && err.message ? err.message : String(err);
+    try {
+      process.stderr.write(`ijfw: gate-result receipt write failed: ${msg}\n`);
+    } catch {
+      /* even stderr write can fail in odd environments; nothing to do */
+    }
+  }
+}
+
+// --- Internals -------------------------------------------------------------
+
+// Strict gate_id shape: lowercase alphanumerics + hyphen, must start with a
+// letter. Matches what makeGateId() produces after colon-collapse + ts/rand4
+// suffix. Used by makeReceipt() to refuse poisoned gate_id values before any
+// filesystem call.
+const RECEIPT_GATE_ID_PATTERN = /^[a-z][a-z0-9-]+$/;
+
+async function resolveProjectType(projectRoot) {
+  try {
+    const root = typeof projectRoot === 'string' && projectRoot.length > 0
+      ? projectRoot
+      : process.cwd();
+    // detect() is synchronous; we call it inside an async function so any
+    // throw is captured by the catch below and falls back to 'unknown'.
+    const detected = detectProjectType(root);
+    if (detected && typeof detected.primary_type === 'string' && detected.primary_type.length > 0) {
+      return detected.primary_type;
+    }
+    if (detected && typeof detected.type === 'string' && detected.type.length > 0) {
+      return detected.type;
+    }
+    return 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}

package/src/intent-router.js

@@ -132,7 +132,9 @@ const INTENTS = [
     priority: 10,
     patterns: [
       /\bcross[- ]?audit(?:\s|ing)?\b/i,
+      // eslint-disable-next-line security/detect-unsafe-regex -- intent checks run on one user prompt string; alternations are small and token-bounded.
       /\b(?:get|need)\s+(?:a\s+)?second opinion\b/i,
+      // eslint-disable-next-line security/detect-unsafe-regex -- intent checks run on one user prompt string; alternations are small and token-bounded.
       /\b(?:have|ask)\s+(?:codex|gemini|opencode|aider|copilot)\s+(?:to\s+)?(?:review|audit|check)\b/i,
       /\bsecond[- ]model (?:review|opinion|audit)\b/i,
       /\b(?:peer|adversarial)[- ]?(?:review|audit)\b/i,

package/src/lib/npm-view.js

@@ -7,6 +7,7 @@ import { homedir } from 'node:os';
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { rotateLogIfNeeded, redactUrl } from './atomic-io.js';
 
+// eslint-disable-next-line security/detect-unsafe-regex -- npm version output is a short scalar string and is retried/truncated by caller.
 const VERSION_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
 const PKG = '@ijfw/install';
 

package/src/memory/fts5.js

@@ -10,7 +10,7 @@
 //   - PRAGMA busy_timeout = 5000 + BEGIN IMMEDIATE for racing writers
 //   - PRAGMA quick_check post-write enforces integrity
 //
-// Security model (D-PILLAR-SPEC §12, real fix-wave C3):
+// Security model (D-PILLAR-SPEC section 12, real fix-wave C3):
 //   indexEntry runs `redactSecrets()` over `entry.body` AND `entry.source`
 //   BEFORE the INSERT. The scrub is the security gate that ensures secret-
 //   shaped tokens are never persisted in `memory_entries`, the FTS index,
@@ -37,7 +37,7 @@ import {
 import { autoIndexGraphFromMemoryBody } from '../compute/graph-auto-index.js';
 import { redactSecrets } from '../redactor.js';
 
-// D-PILLAR-SPEC §12 ingest scrub gate. Default-on; the only escape hatch
+// D-PILLAR-SPEC section 12 ingest scrub gate. Default-on; the only escape hatch
 // is the IJFW_INGEST_SCRUB=0 env var, used for local debugging only and
 // never a shipping posture. Read on every indexEntry so test harnesses
 // can flip it without re-importing.
@@ -196,7 +196,7 @@ export function indexEntry(db, entry) {
   if (typeof entry.body !== 'string' || entry.body.length === 0) {
     throw new MemoryDbError('indexEntry: entry.body must be a non-empty string.');
   }
-  // D-PILLAR-SPEC §12 ingest scrub gate. Replace `body` and `source`
+  // D-PILLAR-SPEC section 12 ingest scrub gate. Replace `body` and `source`
   // with their redacted forms BEFORE the INSERT, so the FTS index, the
   // graph auto-index pass below, and any downstream reader only ever
   // see scrubbed text. After this branch `entry` is unchanged for the

package/src/memory/migrations/002-tier-semantic.js

@@ -1,6 +1,6 @@
 // IJFW v1.3.0 -- memory migration 002: 4-tier semantic axis (D1).
 //
-// Source authority: PRD-v2 §9 Pillar D D1 + .planning/1.3.0/D-PILLAR-SPEC.md §1
+// Source authority: PRD-v2 section 9 Pillar D D1 + .planning/1.3.0/D-PILLAR-SPEC.md section 1
 // (tier promotion rules).
 //
 // Adds `tier_semantic` column ORTHOGONAL to existing tier_access (hot/warm/cold
@@ -10,7 +10,7 @@
 //
 // ADD-ONLY semantics. Default 'working' protects every legacy row -- existing
 // memory_entries pre-D1 are by definition session-bound observations, which is
-// the exact definition of Working in D-PILLAR-SPEC §1. Promotion to other
+// the exact definition of Working in D-PILLAR-SPEC section 1. Promotion to other
 // tiers happens via tier-promotion.js (separate module, not this migration).
 //
 // CREATE INDEX on (tier_semantic, created_at) so the search filter

package/src/memory/staleness.js

@@ -43,7 +43,7 @@ const DEFAULT_STALE_VALUE = 1;
  * propagateStaleMemory(memDb, computeDb, supersededNodeId, options) -> envelope
  *
  * Walk the COMPUTE kg graph from `supersededNodeId` (BFS, weight + depth
- * gated per D-PILLAR-SPEC §2). For every reachable node (excluding the
+ * gated per D-PILLAR-SPEC section 2). For every reachable node (excluding the
  * start node by default), find `memory_entries` rows whose `body` mentions
  * the node's name and flip their `stale_candidate` column to `staleValue`.
  *

package/src/memory/tier-promotion.js

@@ -1,6 +1,6 @@
 // IJFW v1.3.0 -- D1 tier promotion logic.
 //
-// Source authority: .planning/1.3.0/D-PILLAR-SPEC.md §1 (tier promotion rules).
+// Source authority: .planning/1.3.0/D-PILLAR-SPEC.md section 1 (tier promotion rules).
 //
 // Implements the four promotion edges defined in the spec:
 //
@@ -32,7 +32,7 @@
 
 import { tokenizeBody, jaccardSimilarity } from './tokenize.js';
 
-// Constants from D-PILLAR-SPEC §1.
+// Constants from D-PILLAR-SPEC section 1.
 const JACCARD_THRESHOLD = 0.7;
 const PROCEDURAL_MIN_DURATION_MS = 5 * 60 * 1000;
 const PROCEDURAL_PATTERN_MIN_CHAINS = 3;
@@ -51,7 +51,7 @@ export const TIERS = Object.freeze({
 
 /**
  * Promote Working tier observations from the just-ended session into a
- * single Episodic summary record. Per D-PILLAR-SPEC §1, this is invoked
+ * single Episodic summary record. Per D-PILLAR-SPEC section 1, this is invoked
  * at SessionEnd boundary by the D3 hook; it is idempotent per session
  * (a session that's already been consolidated is skipped).
  *
@@ -124,7 +124,7 @@ export function promoteWorkingToEpisodic(db, opts = {}) {
 /**
  * Promote Episodic records to Semantic when supersession criteria are met.
  *
- * Per D-PILLAR-SPEC §1 trigger A (explicit) + trigger B (supersession):
+ * Per D-PILLAR-SPEC section 1 trigger A (explicit) + trigger B (supersession):
  *   A. If an Episodic record's `source` carries the literal substring
  *      `promote:semantic` (set by user via slash command or skill), promote.
  *   B. If two Episodic records have token-set Jaccard similarity > 0.7,
@@ -243,7 +243,7 @@ export function promoteEpisodicToSemantic(db) {
 
 /**
  * Promote Working tier observations into a procedural_candidate (and on
- * pattern match, into Procedural) per D-PILLAR-SPEC §1.
+ * pattern match, into Procedural) per D-PILLAR-SPEC section 1.
  *
  * Caller provides a TaskUpdate event:
  *   { task_id, status, start_ts, end_ts, body, session_id, commit_tags? }
@@ -360,7 +360,7 @@ export function promoteWorkingToProcedural(db, taskUpdate = {}) {
 // --- Semantic -> archived (alpha no-op) ------------------------------------
 
 /**
- * Per D-PILLAR-SPEC §1: no promotion in alpha. Function exists so callers
+ * Per D-PILLAR-SPEC section 1: no promotion in alpha. Function exists so callers
  * that wire up the four-edge state machine don't get an undefined-import
  * error; returns a no-op shape consistent with the others.
  */