rcf-lite 0.0.1 → 0.8.0

package/src/req-baseline/sweep.js

@@ -0,0 +1,230 @@
+// Baseline-AC sweep planner + applier (spec §5.3, §5.4).
+//
+// The "open sweep candidate" property is DERIVED from the tree, not
+// persisted: a candidate is open exactly when the parent REQ carries a
+// shape, the baselineKey is not present as an AC on the US, and no
+// baselineAcOptOuts record covers it. See open-candidates.js. This module
+// walks the tree via that derivation, presents the candidates for
+// operator resolution, and materialises the two durable outcomes:
+// accepted keys become ACs (authoredBy: baseline), opted-out keys become
+// baselineAcOptOuts entries. Skipping (or being silent) simply leaves
+// the derived-open state as-is; the Stage-1 gate (gate.js) refuses build
+// on any FBS binding an AC on a US that still derives an open key.
+//
+// Moment-4 non-interactive create (spec §5.3 moment 4): a US created
+// under a classified REQ does not need any explicit auto-enqueue write
+// because the derivation catches unresolved keys directly. The Stage-1
+// gate remains the single unbypassable refusal surface.
+
+import { updateDocument } from '#core/store';
+import {
+  BASELINE_SHAPE_KEYS,
+  getBaselineSet,
+} from '#core/baseline-catalog';
+
+import { writeOptOut } from './opt-out.js';
+import { openCandidatesForUs } from './open-candidates.js';
+
+/**
+ * Plan the baseline sweep across the tree.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} opts
+ * @param {string|null} [opts.reqId]
+ * @param {boolean} [opts.all]
+ * @returns {{ candidates: Array<{ usId: string, reqId: string, baselineKey: string, reqShape: string, canonicalText: string }> }}
+ */
+export function planSweep(tree, opts = {}) {
+  const { reqId = null, all = false } = opts;
+
+  /** @type {Array<{ usId: string, reqId: string, baselineKey: string, reqShape: string, canonicalText: string }>} */
+  const candidates = [];
+
+  for (const [id, kind] of tree.kindById) {
+    if (kind !== 'userStory') continue;
+    const us = tree.byId.get(id);
+    if (!us) continue;
+    if (!all && reqId && us.reqId !== reqId) continue;
+    if (!all && !reqId) continue;
+    for (const c of openCandidatesForUs(tree, us)) {
+      candidates.push(c);
+    }
+  }
+  return { candidates };
+}
+
+/**
+ * Apply a batch of decisions.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {Array<{ candidate: object, action: 'accept'|'opt-out'|'skip', reason?: string }>} args.decisions
+ * @param {Date} [args.now]
+ * @returns {Promise<{ accepted: number, optedOut: number, left: number, optOutIds: string[], writtenAcIds: string[] } | import('#core/errors').RcfError>}
+ */
+export async function applySweepDecisions({ projectRoot, tree, decisions, now = new Date() }) {
+  let accepted = 0;
+  let optedOut = 0;
+  let left = 0;
+  /** @type {string[]} */
+  const optOutIds = [];
+  /** @type {string[]} */
+  const writtenAcIds = [];
+
+  // Group by US so each US gets one write.
+  const byUs = new Map();
+  for (const d of decisions) {
+    const usId = d.candidate.usId;
+    if (!byUs.has(usId)) byUs.set(usId, []);
+    byUs.get(usId).push(d);
+  }
+
+  /** @type {Array<{ reqId: string, baselineKey: string, reason: string }>} */
+  const pendingOptOuts = [];
+
+  for (const [usId, list] of byUs) {
+    const usDoc = tree.byId.get(usId);
+    if (!usDoc) continue;
+
+    const acsToAppend = [];
+    for (const d of list) {
+      if (d.action === 'accept') {
+        const ac = composeBaselineAc({ usDoc, candidate: d.candidate, now });
+        acsToAppend.push(ac);
+        writtenAcIds.push(ac.id);
+        accepted += 1;
+      } else if (d.action === 'opt-out') {
+        pendingOptOuts.push({ reqId: d.candidate.reqId, baselineKey: d.candidate.baselineKey, reason: d.reason ?? '' });
+        optedOut += 1;
+      } else {
+        left += 1;
+      }
+    }
+
+    if (acsToAppend.length === 0) continue;
+
+    const nextAcs = [
+      ...(Array.isArray(usDoc.acceptanceCriteria) ? usDoc.acceptanceCriteria : []),
+      ...acsToAppend,
+    ];
+
+    const result = await updateDocument({
+      projectRoot,
+      tree,
+      id: usId,
+      patch: { acceptanceCriteria: nextAcs },
+      sets: [],
+      options: {},
+      walkErrors: [],
+    });
+    if (result && result.kind && typeof result.message === 'string') return result;
+  }
+
+  for (const p of pendingOptOuts) {
+    const out = await writeOptOut({
+      projectRoot,
+      tree,
+      reqId: p.reqId,
+      baselineKey: p.baselineKey,
+      reason: p.reason,
+      scope: 'req',
+      now,
+    });
+    if (out && out.kind && typeof out.message === 'string') return out;
+    optOutIds.push(out.id);
+  }
+
+  return { accepted, optedOut, left, optOutIds, writtenAcIds };
+}
+
+/**
+ * Moment-4 auto-enqueue is a no-op today: the openness of a candidate is
+ * derived by open-candidates.js from the tree state (shape-classified
+ * REQ, no matching AC, no matching opt-out). A fresh US under a
+ * classified REQ therefore surfaces every unresolved baseline key as
+ * OPEN automatically, without a separate queue-write. The Stage-1 gate
+ * (gate.js) reads the same derivation and refuses build accordingly.
+ *
+ * Kept exported so the create/us hook has a stable seam name and can
+ * grow a queue-write in a future schemas release when a persistent
+ * open-queue field lands on user-story.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.usId
+ * @returns {Promise<{ enqueued: string[] }>}
+ */
+export async function applyPendingBaselinesForUs({ tree, usId }) {
+  const usDoc = tree.byId.get(usId);
+  if (!usDoc) return { enqueued: [] };
+  const open = openCandidatesForUs(tree, usDoc);
+  return { enqueued: open.map((c) => c.baselineKey) };
+}
+
+/**
+ * Compose an AC to inject for a baseline candidate.
+ *
+ * @param {object} args
+ * @param {object} args.usDoc
+ * @param {{ baselineKey: string, reqShape: string, canonicalText: string, given?: string, when?: string, then?: string }} args.candidate
+ * @param {Date} args.now
+ * @returns {object}
+ */
+export function composeBaselineAc({ usDoc, candidate, now }) {
+  const isoNow = now.toISOString();
+  const id = nextAcId(usDoc);
+  const canonicalText = candidate.canonicalText;
+  const gwt = candidate.given || candidate.when || candidate.then
+    ? { given: candidate.given ?? '', when: candidate.when ?? '', then: candidate.then ?? '' }
+    : extractGwt(canonicalText);
+  const ac = {
+    id,
+    description: canonicalText,
+    testable: true,
+    provenance: {
+      authoredBy: 'baseline',
+      baselineKey: candidate.baselineKey,
+      injectedAt: isoNow,
+      sourceReqShape: candidate.reqShape,
+      acceptedByOperatorAt: isoNow,
+    },
+  };
+  if (gwt.given) ac.given = gwt.given;
+  if (gwt.when) ac.when = gwt.when;
+  if (gwt.then) ac.then = gwt.then;
+  return ac;
+}
+
+const AC_HIER_ID_RE = /^AC-(\d{3,})-(\d+)$/;
+
+function nextAcId(usDoc) {
+  const acs = Array.isArray(usDoc.acceptanceCriteria) ? usDoc.acceptanceCriteria : [];
+  // Prefer hierarchical form matching the US id, e.g. US-201 → AC-201-1.
+  const usNum = (usDoc.usId ?? '').match(/^US-(\d+)$/)?.[1];
+  let maxN = 0;
+  for (const ac of acs) {
+    const m = (ac?.id ?? '').match(AC_HIER_ID_RE);
+    if (!m) continue;
+    const [, hier, tail] = m;
+    if (usNum && hier !== usNum) continue;
+    const n = Number.parseInt(tail, 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  return usNum ? `AC-${usNum}-${maxN + 1}` : `AC-${(Math.floor(Math.random() * 999)).toString().padStart(3, '0')}-1`;
+}
+
+function extractGwt(text) {
+  const gwt = { given: '', when: '', then: '' };
+  const g = text.match(/given\s+(.+?),\s*when/i);
+  const w = text.match(/,\s*when\s+(.+?),\s*then/i);
+  const t = text.match(/,\s*then\s+(.+)$/i);
+  if (g) gwt.given = g[1].trim();
+  if (w) gwt.when = w[1].trim();
+  if (t) gwt.then = t[1].trim().replace(/\.\s*$/, '');
+  return gwt;
+}
+
+// Kept-exported catalog constants for downstream discoverability.
+void BASELINE_SHAPE_KEYS; void getBaselineSet;

package/src/req-detection/classifier.js

@@ -0,0 +1,181 @@
+// REQ-shape classifier (Track C+D spec §4.4).
+//
+// Deterministic keyword-scan over an already-loaded REQ document. Reads
+// `title`, `description`, `rationale`, folds the parent PRD's `intent`
+// and `problem` as fallback context, and returns a
+// `shapeClassification` block per the requirement schema (§3.1). Never
+// reads USes or ACs (they may not exist yet and would circularly
+// re-trigger the classifier).
+//
+// Signals come from `matchReqShapeSignals` in core (single source of
+// truth; Track B's UI patterns flow through the same file). Multi-shape
+// verdicts are legitimate; the classifier records each match tagged with
+// the source field it came from.
+//
+// Content-pending case: a REQ whose `description` is empty at write time
+// records `shapes: []`, `reason: content-pending`; the classifier reruns
+// on the first `rcf update req --description ...` that adds real content.
+
+import { matchReqShapeSignals, SHAPE_KEYS } from '#core/patterns/req-shapes';
+
+/**
+ * @typedef {'webUi'|'httpApi'|'auth'|'persistence'|'notifications'} ReqShape
+ * @typedef {'webUi'|'httpApi'|'auth'|'persistence'|'notifications'|'none'} ReqShapeWithNone
+ * @typedef {'keyword-scan'|'content-pending'|'inheritedFromParent'|'operatorOverride'} ClassifierReason
+ */
+
+/**
+ * @typedef {object} ReqShapeSignal
+ * @property {'title'|'description'|'rationale'} source
+ * @property {string} match
+ * @property {ReqShape} shape
+ */
+
+/**
+ * @typedef {object} ReqShapeClassification
+ * @property {ReqShapeWithNone[]} shapes
+ * @property {ClassifierReason} reason
+ * @property {ReqShapeSignal[]} [signals]
+ * @property {string} classifiedAt
+ * @property {object} [operatorOverride]
+ */
+
+const ALLOWED_SOURCES = Object.freeze(['title', 'description', 'rationale']);
+
+/**
+ * Compute the shape classification for a REQ. Pure function; does not
+ * write to the document. Callers merge the returned block onto the REQ
+ * before persisting.
+ *
+ * @param {object} reqDoc                  the REQ document body
+ * @param {object} [opts]
+ * @param {object} [opts.parentPrd]        parent PRD body for fallback context
+ * @param {Date} [opts.now]                clock injection for tests
+ * @returns {ReqShapeClassification}
+ */
+export function classifyReq(reqDoc, opts = {}) {
+  const now = opts.now ?? new Date();
+  const isoNow = now.toISOString();
+
+  const title = typeof reqDoc?.title === 'string' ? reqDoc.title : '';
+  const description = typeof reqDoc?.description === 'string' ? reqDoc.description : '';
+  const rationale = typeof reqDoc?.rationale === 'string' ? reqDoc.rationale : '';
+
+  // Content-pending: the REQ has no real description body yet. Placeholder
+  // scaffolds land as "TODO", so treat descriptions that are empty or
+  // exactly-a-todo as pending. The classifier re-runs on the next update
+  // once the operator or an intake pass fills in real prose.
+  const contentPending = description.length === 0 || /^\s*TODO\b/i.test(description);
+  if (contentPending) {
+    return {
+      shapes: [],
+      reason: 'content-pending',
+      classifiedAt: isoNow,
+    };
+  }
+
+  const signals = [];
+
+  const primarySources = [
+    { source: 'title', text: title },
+    { source: 'description', text: description },
+    { source: 'rationale', text: rationale },
+  ];
+
+  for (const { source, text } of primarySources) {
+    if (!ALLOWED_SOURCES.includes(source) || text.length === 0) continue;
+    for (const m of matchReqShapeSignals(text)) {
+      signals.push({ source, shape: m.shape, match: m.match });
+    }
+  }
+
+  // Parent PRD fallback: only used to seed additional shapes when the REQ
+  // itself did not surface one. Signals are still attributed to the REQ's
+  // own fields per the schema enum (title/description/rationale) so the
+  // signals array shape stays stable; a shape inherited from the PRD lands
+  // in `shapes[]` with no signal row and the classifier reason stays
+  // keyword-scan (the signals are still what the REQ said; the parent
+  // widens the shape list only when the REQ's own text was silent). This
+  // matches spec §4.4 "fallback context" without mixing scopes.
+  const parentPrd = opts.parentPrd ?? null;
+  const parentText = parentPrd
+    ? [parentPrd.intent, parentPrd.problem].filter((s) => typeof s === 'string' && s.length > 0).join(' ')
+    : '';
+  const parentSignals = parentText.length > 0 ? matchReqShapeSignals(parentText) : [];
+
+  // Merge shapes: any shape the REQ's own text matched, plus any shape
+  // the parent PRD adds. Preserved in canonical order.
+  const shapesSet = new Set();
+  for (const s of signals) shapesSet.add(s.shape);
+  for (const m of parentSignals) shapesSet.add(m.shape);
+
+  const shapes = SHAPE_KEYS.filter((s) => shapesSet.has(s));
+  const finalShapes = shapes.length === 0 ? ['none'] : shapes;
+
+  const block = {
+    shapes: finalShapes,
+    reason: 'keyword-scan',
+    classifiedAt: isoNow,
+  };
+  if (signals.length > 0) block.signals = signals;
+  return block;
+}
+
+/**
+ * Merge a fresh classification onto an existing REQ document. Preserves
+ * a previous `operatorOverride` block when present, and preserves
+ * signals from earlier runs when the new run comes back
+ * `content-pending` (never clear real signals with a pending re-run;
+ * pending is a "no verdict yet" state, not a delete).
+ *
+ * @param {object} reqDoc               REQ document to merge onto (not mutated)
+ * @param {ReqShapeClassification} block classification from `classifyReq`
+ * @returns {object}                     new REQ doc with the merged block
+ */
+export function mergeClassificationOntoReq(reqDoc, block) {
+  const existing = reqDoc?.shapeClassification;
+  // On content-pending: only apply if there is no previous verdict.
+  if (block.reason === 'content-pending' && existing && existing.reason !== 'content-pending') {
+    return reqDoc;
+  }
+  const next = { ...reqDoc, shapeClassification: { ...block } };
+  if (existing?.operatorOverride) {
+    next.shapeClassification.operatorOverride = existing.operatorOverride;
+    // An operator override wins on the shapes field.
+    if (Array.isArray(existing.operatorOverride.newShapes) && existing.operatorOverride.newShapes.length > 0) {
+      next.shapeClassification.shapes = [...existing.operatorOverride.newShapes];
+    }
+  }
+  return next;
+}
+
+/**
+ * Compose an operator override block per spec §4.5. Records both the
+ * original classifier shapes and the newly-ruled shapes so the override
+ * history is visible to reviewers. Does not mutate the input; returns a
+ * new `shapeClassification` block ready to write.
+ *
+ * @param {object} args
+ * @param {ReqShapeWithNone[]} args.originalShapes
+ * @param {ReqShapeWithNone[]} args.newShapes
+ * @param {string} args.reason
+ * @param {ReqShapeSignal[]} [args.signals]
+ * @param {Date} [args.now]
+ * @returns {ReqShapeClassification}
+ */
+export function composeOperatorOverride({ originalShapes, newShapes, reason, signals, now = new Date() }) {
+  const isoNow = now.toISOString();
+  const block = {
+    shapes: [...newShapes],
+    reason: 'operatorOverride',
+    classifiedAt: isoNow,
+    operatorOverride: {
+      originalShapes: [...originalShapes],
+      newShapes: [...newShapes],
+      reason,
+      ackAt: isoNow,
+    },
+  };
+  if (Array.isArray(signals) && signals.length > 0) block.signals = signals;
+  return block;
+}

package/src/req-detection/index.js

@@ -0,0 +1,9 @@
+// Public surface for the REQ-shape classifier module (Track C+D §4).
+
+export {
+  classifyReq,
+  mergeClassificationOntoReq,
+  composeOperatorOverride,
+} from './classifier.js';
+
+export { classifyAndPersistReq } from './persist.js';

package/src/req-detection/persist.js

@@ -0,0 +1,55 @@
+// Persist a REQ-shape classification onto a REQ document (Track C+D §4.4).
+//
+// Reads the REQ from the in-memory tree, computes classification via
+// classifyReq (folding parent PRD context when the PRD is loaded), merges
+// per mergeClassificationOntoReq (which respects operator overrides and
+// refuses to overwrite a real verdict with content-pending), and writes
+// the merged shapeClassification block back via updateDocument.
+//
+// Never fails the calling verb: a classification write error is warned
+// on stderr but returns success (the write we care about is the REQ's
+// own body write; classification is provenance layered on top).
+
+import { updateDocument } from '#core/store';
+import { classifyReq, mergeClassificationOntoReq } from './classifier.js';
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.reqId              the id of the REQ to classify
+ * @param {Date} [args.now]
+ * @returns {Promise<{ ok: true, block: object, changed: boolean } | { ok: false, message: string }>}
+ */
+export async function classifyAndPersistReq({ projectRoot, tree, reqId, now = new Date() }) {
+  const reqDoc = tree?.byId?.get(reqId);
+  if (!reqDoc || reqDoc.reqId !== reqId) {
+    return { ok: false, message: `req-classify: ${reqId} not found in tree` };
+  }
+  const prdId = reqDoc.prdId;
+  const parentPrd = prdId ? tree.byId.get(prdId) : null;
+
+  const block = classifyReq(reqDoc, { parentPrd: parentPrd ?? undefined, now });
+  const merged = mergeClassificationOntoReq(reqDoc, block);
+
+  // Nothing to write when the merge decided to keep the existing block.
+  if (merged === reqDoc) return { ok: true, block: reqDoc.shapeClassification, changed: false };
+
+  const nextBlock = merged.shapeClassification;
+  // Write back through the store's updateDocument path so validation
+  // fires and updatedAt bumps.
+  const result = await updateDocument({
+    projectRoot,
+    tree,
+    id: reqId,
+    patch: { shapeClassification: nextBlock },
+    sets: [],
+    options: {},
+    walkErrors: [],
+  });
+  if (result && result.kind && typeof result.message === 'string') {
+    // RcfError shape
+    return { ok: false, message: `req-classify: ${result.message}` };
+  }
+  return { ok: true, block: nextBlock, changed: true };
+}