rcf-lite 0.28.4 → 0.29.0

package/src/define/ledgers.js

@@ -189,6 +189,11 @@ function validateEntry(name, entry, filePath, where = 'entry') {
         filePath, field: `${where}.source`,
       });
     }
+    if (e.resolvedBy !== undefined && typeof e.resolvedBy !== 'string') {
+      throw new LedgerError(`brief ${where}.resolvedBy must be a string when present.`, {
+        filePath, field: `${where}.resolvedBy`,
+      });
+    }
   } else if (name === 'decisions') {
     if (typeof e.question !== 'string' || e.question.length === 0) {
       throw new LedgerError(`decisions ${where}.question must be non-empty.`, {
@@ -443,37 +448,231 @@ export function resolveEntry({ name, body, id, patch = {}, now }) {
   return { body: nextBody, entry: updated };
 }
 
+const RESOLVED_BY_GRAMMAR_RE = /^(REQ-\d+|TAD\.entity:.+|PRD\.user:.+|TAD\.system:.+|TAC-\d+(?:-[A-Za-z0-9-]+)?|omitted:.+)$/;
+
+/**
+ * True when `pointer` matches the closed grammar for a `resolvedBy`
+ * value. Shape-only; does NOT verify that the pointed-to id or name
+ * resolves against a tree (that is D2's `skeleton:resolvedBy` check).
+ *
+ * @param {string} pointer
+ * @returns {boolean}
+ */
+export function isResolvedByGrammar(pointer) {
+  if (typeof pointer !== 'string') return false;
+  return RESOLVED_BY_GRAMMAR_RE.test(pointer.trim());
+}
+
+const KIND_MARKER_RE = /^\[([^\]]+)\]\s*/;
+const SOURCE_MARKER_RE = /\s*\(source:\s*([^)]+)\)\s*$/;
+const QUESTION_PREFIX_RE = /^(TBC|TBD|Open|Question)\b[:.]?\s*/i;
+
 /**
  * Parse `--from <file>` content into brief-statement drafts: one entry
- * per non-empty line, stripping a leading `- `, `* ` or `<n>. ` bullet.
- * The caller supplies the `kind` (or `capability` as the default). All
- * statements land as `status: 'open'` at the same `addedAt`; the CLI
- * assigns sequential ids.
+ * per non-empty line. Each line optionally carries a leading `[kind]`
+ * marker and a trailing `(source: ...)` marker. A line without
+ * `[kind]` takes `opts.kind` (default `capability`); a line without
+ * `(source: ...)` takes `opts.source` or no source. Heuristics kind a
+ * line `openQuestion` when it ends with `?` or begins with `TBC`,
+ * `TBD`, `Open:` or `Question:`, unless a `[kind]` marker says
+ * otherwise. Unknown `[kind]` values raise `LedgerError` (code
+ * `usage`) before any write.
  *
  * @param {string} content
  * @param {object} [opts]
- * @param {string} [opts.kind] default kind for every extracted line
- * @param {string} [opts.source] optional source-span label per entry
+ * @param {string} [opts.kind] default kind for every unmarked line
+ * @param {string} [opts.source] default source for every unmarked line
  * @returns {Array<{ text: string, kind: string, source?: string }>}
  */
 export function parseBriefFromFile(content, opts = {}) {
-  const kind = opts.kind ?? 'capability';
+  const defaultKind = opts.kind ?? 'capability';
   /** @type {Array<{ text: string, kind: string, source?: string }>} */
   const drafts = [];
   for (const raw of content.split(/\r?\n/)) {
     const trimmed = raw.trim();
     if (!trimmed) continue;
-    const stripped = trimmed
+    let line = trimmed
       .replace(/^[-*]\s+/, '')
       .replace(/^\d+[.)]\s+/, '');
-    if (!stripped) continue;
-    const entry = { text: stripped, kind };
-    if (opts.source) entry.source = opts.source;
+    if (!line) continue;
+
+    // Trailing (source: ...) marker.
+    let source = opts.source;
+    const srcMatch = line.match(SOURCE_MARKER_RE);
+    if (srcMatch) {
+      source = srcMatch[1].trim();
+      line = line.slice(0, srcMatch.index).trimEnd();
+    }
+
+    // Leading [kind] marker.
+    let kind = null;
+    const kindMatch = line.match(KIND_MARKER_RE);
+    if (kindMatch) {
+      kind = kindMatch[1].trim();
+      line = line.slice(kindMatch[0].length).trim();
+      if (!BRIEF_KINDS.includes(/** @type {any} */ (kind))) {
+        throw new LedgerError(
+          `brief --from: unknown kind '${kind}' (expected one of: ${BRIEF_KINDS.join(', ')})`,
+          { field: 'kind', code: 'usage' },
+        );
+      }
+    }
+
+    if (!line) continue;
+
+    // Heuristics for openQuestion when no [kind] marker was given.
+    if (!kind) {
+      if (line.endsWith('?') || QUESTION_PREFIX_RE.test(line)) {
+        kind = 'openQuestion';
+      } else {
+        kind = defaultKind;
+      }
+    }
+
+    const entry = { text: line, kind };
+    if (source) entry.source = source;
     drafts.push(entry);
   }
   return drafts;
 }
 
+/**
+ * Parse a `resolvedBy` pointer against the walker tree. The six
+ * accepted forms are `REQ-nnn`, `TAD.entity:<name>`, `PRD.user:<name>`,
+ * `TAD.system:<name>`, `TAC-nnnn`, and `omitted:<reason>`. Resolution
+ * checks the pointed-to id or name actually exists in the tree
+ * (except for `omitted:`, which always passes once the reason is
+ * non-empty).
+ *
+ * @param {string} pointer
+ * @param {object} tree  walker tree (TreeModel-like)
+ * @returns {{ ok: true, kind: string, target: string } | { ok: false, why: string }}
+ */
+export function parseResolvedBy(pointer, tree) {
+  if (typeof pointer !== 'string' || pointer.length === 0) {
+    return { ok: false, why: 'pointer must be a non-empty string' };
+  }
+  const p = pointer.trim();
+
+  // omitted:<reason>
+  const omittedMatch = p.match(/^omitted:(.+)$/);
+  if (omittedMatch) {
+    const reason = omittedMatch[1].trim();
+    if (!reason) return { ok: false, why: 'omitted: pointer needs a reason' };
+    return { ok: true, kind: 'omitted', target: reason };
+  }
+
+  // REQ-nnn
+  if (/^REQ-\d+$/.test(p)) {
+    const found = (tree?.requirements ?? []).some((r) => r?.reqId === p);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'req', target: p };
+  }
+
+  // TAC-nnnn (short form, resolves to a tree TAC whose id starts
+  // with that prefix) or TAC-nnnn-<slug> (exact-match long form).
+  // Codex review 2026-10-02: an unanchored /^TAC-\d+/ let arbitrary
+  // suffixes (TAC-4130-made-up) pass as long as the numeric prefix
+  // matched an existing TAC; anchor the regex and gate the prefix
+  // fallback to the short form only.
+  const tacMatch = p.match(/^TAC-\d+(?:-[A-Za-z0-9-]+)?$/);
+  if (tacMatch) {
+    const tacs = tree?.tacs ?? [];
+    const isShortForm = /^TAC-\d+$/.test(p);
+    const found = tacs.some((t) => {
+      if (!t?.tacId) return false;
+      if (t.tacId === p) return true;
+      if (!isShortForm) return false;
+      return t.tacId.split('-').slice(0, 2).join('-') === p;
+    });
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'tac', target: p };
+  }
+
+  // TAD.entity:<name>
+  const entityMatch = p.match(/^TAD\.entity:(.+)$/);
+  if (entityMatch) {
+    const name = entityMatch[1].trim();
+    if (!name) return { ok: false, why: 'TAD.entity: pointer needs a name' };
+    const entities = tree?.tad?.dataArchitecture?.coreEntities ?? [];
+    const found = Array.isArray(entities)
+      && entities.some((e) => (typeof e === 'string' ? e : e?.name) === name);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'tadEntity', target: name };
+  }
+
+  // PRD.user:<name>
+  const userMatch = p.match(/^PRD\.user:(.+)$/);
+  if (userMatch) {
+    const name = userMatch[1].trim();
+    if (!name) return { ok: false, why: 'PRD.user: pointer needs a name' };
+    // Codex review 2026-10-02: the production PRD schema uses
+    // `targetUsers`; keep `users` as a fallback for the test
+    // fixtures but prefer the real path.
+    const users = tree?.prd?.targetUsers ?? tree?.prd?.users ?? [];
+    const found = Array.isArray(users)
+      && users.some((u) => (typeof u === 'string' ? u : u?.name) === name);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'prdUser', target: name };
+  }
+
+  // TAD.system:<name>
+  const systemMatch = p.match(/^TAD\.system:(.+)$/);
+  if (systemMatch) {
+    const name = systemMatch[1].trim();
+    if (!name) return { ok: false, why: 'TAD.system: pointer needs a name' };
+    // Codex review 2026-10-02: the production TAD schema puts
+    // externalSystems inside integrationArchitecture; keep the
+    // top-level path as a fallback for the test fixtures.
+    const systems = tree?.tad?.integrationArchitecture?.externalSystems ?? tree?.tad?.externalSystems ?? [];
+    const found = Array.isArray(systems)
+      && systems.some((s) => (typeof s === 'string' ? s : s?.name) === name);
+    if (!found) return { ok: false, why: 'pointer does not resolve' };
+    return { ok: true, kind: 'tadSystem', target: name };
+  }
+
+  return { ok: false, why: 'pointer outside grammar (REQ-nnn, TAD.entity:<name>, PRD.user:<name>, TAD.system:<name>, TAC-nnnn, omitted:<reason>)' };
+}
+
+/**
+ * Patch a ledger entry in place. Field patches honour `add`-side
+ * validation by re-running `validateLedger` on the resulting body.
+ * Throws `LedgerError` (code `usage`) when the id is unknown. The
+ * entry's `id` and `addedAt` are never touched; `status`, `addedAt`
+ * and `resolvedAt` are passed through from the current entry unless
+ * explicitly patched.
+ *
+ * @param {object} args
+ * @param {LedgerName} args.name
+ * @param {Record<string, unknown[]>} args.body
+ * @param {number} args.id
+ * @param {Record<string, unknown>} args.patch
+ * @returns {{ body: Record<string, unknown[]>, entry: Record<string, unknown> }}
+ */
+export function updateEntry({ name, body, id, patch }) {
+  const cfg = LEDGER_CONFIG[name];
+  if (!cfg) throw new LedgerError(`Unknown ledger '${name}'.`, { code: 'usage' });
+  const list = /** @type {any[]} */ (body[cfg.arrayKey] ?? []);
+  const idx = list.findIndex((e) => Number(e?.id) === Number(id));
+  if (idx < 0) {
+    throw new LedgerError(`${name} ledger has no entry with id ${id}.`, {
+      filePath: ledgerRelPath(name), field: `id ${id}`, code: 'usage',
+    });
+  }
+  const current = list[idx];
+  const next = { ...current };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue;
+    if (key === 'id' || key === 'addedAt') continue;
+    next[key] = value;
+  }
+  const nextList = [...list];
+  nextList[idx] = next;
+  const nextBody = { ...body, [cfg.arrayKey]: nextList };
+  validateLedger(name, nextBody, ledgerRelPath(name));
+  return { body: nextBody, entry: next };
+}
+
 /**
  * Load every ledger the project has actually authored, keyed by name.
  *

package/src/intake/index.js

@@ -2,5 +2,5 @@
 
 export { classifyFidelity, FIDELITY_LEVELS } from './fidelity.js';
 export { scanArtefactForFindings } from './validate.js';
-export { runIntakePhases } from './orchestrator.js';
+export { runIntakePhases, runIntakeScansOnDelta } from './orchestrator.js';
 export { writeIntakeRecord, composeIntakeRecord, nextIntakeId } from './manifest-writer.js';

package/src/intake/orchestrator.js

@@ -18,6 +18,123 @@ import { classifyFidelity } from './fidelity.js';
 import { scanArtefactForFindings } from './validate.js';
 import { composeIntakeRecord } from './manifest-writer.js';
 
+/**
+ * Run the mechanical intake scans over newly minted brief statements
+ * against every pre-existing brief statement. The scans operate on
+ * the raw text of the statements; a finding is attributed to the
+ * ids of every statement whose text the scan matched (an
+ * `impliedButNotStated` cue in one new statement with the matching
+ * negated-login phrase elsewhere attributes to both). On a frozen
+ * tree the caller passes every pre-existing statement as `existing`;
+ * the comparison set is `existing` by definition.
+ *
+ * Each returned finding carries:
+ *   { kind, detail, scanName, ids: number[] }
+ * where `kind` is one of the three mechanical kinds from
+ * `scanArtefactForFindings`, `ids` lists the involved statement ids
+ * from `newStatements` first and then `existing` (duplicates
+ * removed), and `scanName` is `kind` for the DEFINE PR 1 wiring.
+ *
+ * @param {Array<{ id: number, text?: string }>} newStatements
+ * @param {Array<{ id: number, text?: string }>} existing
+ * @returns {Array<{ kind: string, detail: string, scanName: string, ids: number[] }>}
+ */
+export function runIntakeScansOnDelta(newStatements, existing) {
+  const safeNew = Array.isArray(newStatements) ? newStatements : [];
+  const safeExisting = Array.isArray(existing) ? existing : [];
+  if (safeNew.length === 0) return [];
+
+  const combined = [...safeNew, ...safeExisting];
+  const combinedText = combined.map((s) => (typeof s?.text === 'string' ? s.text : '')).join('\n');
+  const rawFindings = scanArtefactForFindings(combinedText);
+  if (rawFindings.length === 0) return [];
+
+  // A finding only counts when at least one of the newStatements
+  // participates. We attribute by re-running the scan over the
+  // `newStatements` alone (if that yields the same kind of finding,
+  // the new side is sufficient) OR by running the scan over any
+  // (new, existing) pair that contains at least one new statement:
+  // the second case detects a contradiction between a new and an
+  // existing statement.
+  /** @type {Array<{ kind: string, detail: string, scanName: string, ids: number[] }>} */
+  const out = [];
+  const seen = new Set();
+  for (const f of rawFindings) {
+    const key = `${f.kind}::${f.detail}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const ids = attributeFinding(f, safeNew, safeExisting);
+    if (ids.length === 0) continue;
+    out.push({ kind: f.kind, detail: f.detail, scanName: f.kind, ids });
+  }
+  return out;
+}
+
+/**
+ * @param {{ kind: string, detail: string }} finding
+ * @param {Array<{ id: number, text?: string }>} newStatements
+ * @param {Array<{ id: number, text?: string }>} existing
+ * @returns {number[]}
+ */
+function attributeFinding(finding, newStatements, existing) {
+  /** @type {number[]} */
+  const ids = [];
+  for (const s of newStatements) {
+    if (statementParticipates(finding, s, [...newStatements, ...existing])) {
+      ids.push(Number(s.id));
+    }
+  }
+  if (ids.length === 0) return ids;
+  // Also attribute an existing statement that participates on the other side.
+  for (const s of existing) {
+    if (statementParticipates(finding, s, [...newStatements, ...existing])) {
+      if (!ids.includes(Number(s.id))) ids.push(Number(s.id));
+    }
+  }
+  return ids;
+}
+
+/**
+ * Decide whether `statement.text` contributes to `finding`. The scan
+ * is pattern-based and finds the same finding kind on the text in
+ * isolation if the statement itself carries the full pattern; for
+ * cross-statement findings (a contradiction between two statements)
+ * the statement contributes when it carries at least one half of the
+ * pattern and the other half appears somewhere in the combined set.
+ *
+ * @param {{ kind: string, detail: string }} finding
+ * @param {{ id: number, text?: string }} statement
+ * @param {Array<{ id: number, text?: string }>} combined
+ */
+function statementParticipates(finding, statement, combined) {
+  const text = typeof statement?.text === 'string' ? statement.text : '';
+  if (!text) return false;
+  const soloFindings = scanArtefactForFindings(text).map((f) => f.kind);
+  if (soloFindings.includes(finding.kind)) return true;
+  // Cross-statement: pair this statement's text with every other
+  // combined text and see whether the pair raises the same finding.
+  for (const other of combined) {
+    if (other === statement) continue;
+    const otherText = typeof other?.text === 'string' ? other.text : '';
+    if (!otherText) continue;
+    const pairFindings = scanArtefactForFindings(`${text}\n${otherText}`).map((f) => f.kind);
+    // Codex review 2026-10-02: a pre-existing finding already
+    // raised by `other` alone must not be re-attributed to an
+    // unrelated `statement` merely because concatenation leaves
+    // the pattern intact. Require the pair to raise the finding
+    // that neither side raises alone.
+    const otherSolo = scanArtefactForFindings(otherText).map((f) => f.kind);
+    if (
+      pairFindings.includes(finding.kind)
+      && !soloFindings.includes(finding.kind)
+      && !otherSolo.includes(finding.kind)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * @typedef {'napkin'|'productBrief'|'prd'|'tad'|'other'} ArtefactKind
  */