rcf-lite 0.0.1 → 0.7.1

package/src/finalise/ship-without-verified.js

@@ -0,0 +1,131 @@
+// Ship-without-verified acknowledgement writer
+// (verification-integrity-cluster-spec section 5.2, review finding B-1).
+//
+// When `rcf finalise --ship-without-verified` acknowledges MOCK-ONLY-DECLARED
+// or BLOCKED-BY-DECLARATION per-AC verdicts on a verify report and leaves
+// the FBS at 'complete' (spec section 5.2), the ack lands on the manifest
+// under the optional `shipWithoutVerified[]` array added in
+// @stravica-ai/rcf-schemas 0.4.1. Stdout is not durable and not greppable
+// at ship time; the manifest record is both. Schema shape:
+//
+//   { id: swv-<fbsId>-<n>, fbsId, ackedAt,
+//     declaredAcs[{acId, verdict, reason?}], reportPath }
+//
+// Id allocation mirrors reviewAudit's `ra-<fbsId>-<n>` monotonic pattern
+// (packages/rcf-lite/src/review/index.js:nextReviewAuditId) so a re-ack of
+// the same FBS increments deterministically.
+
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '#core/errors';
+import { validateDocument } from '#core/store';
+
+/**
+ * @typedef {object} ShipWithoutVerifiedDeclaredAc
+ * @property {string} acId
+ * @property {'MOCK-ONLY-DECLARED'|'BLOCKED-BY-DECLARATION'} verdict
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {object} ShipWithoutVerifiedRecord
+ * @property {string} id            `swv-<fbsId>-<n>` monotonic per FBS.
+ * @property {string} fbsId
+ * @property {string} ackedAt       ISO timestamp.
+ * @property {ShipWithoutVerifiedDeclaredAc[]} declaredAcs  minItems 1.
+ * @property {string} reportPath
+ */
+
+/**
+ * Monotonic id allocator for the shipWithoutVerified array. Mirrors
+ * `nextReviewAuditId` (review/index.js).
+ *
+ * @param {object|null} manifest
+ * @param {string} fbsId
+ * @returns {string}
+ */
+export function nextShipWithoutVerifiedId(manifest, fbsId) {
+  const prefix = `swv-${fbsId}-`;
+  const existing = Array.isArray(manifest?.shipWithoutVerified) ? manifest.shipWithoutVerified : [];
+  let maxN = 0;
+  for (const rec of existing) {
+    if (typeof rec?.id !== 'string' || !rec.id.startsWith(prefix)) continue;
+    const n = Number.parseInt(rec.id.slice(prefix.length), 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  return `${prefix}${maxN + 1}`;
+}
+
+/**
+ * Compose the record. Timestamps at UTC ISO.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} args.fbsId
+ * @param {ShipWithoutVerifiedDeclaredAc[]} args.declaredAcs
+ * @param {string} args.reportPath
+ * @param {Date} [args.now]
+ * @returns {ShipWithoutVerifiedRecord}
+ */
+export function composeShipWithoutVerifiedRecord({
+  manifest, fbsId, declaredAcs, reportPath, now = new Date(),
+}) {
+  return {
+    id: nextShipWithoutVerifiedId(manifest, fbsId),
+    fbsId,
+    ackedAt: now.toISOString(),
+    declaredAcs: declaredAcs.map((a) => {
+      const out = { acId: a.acId, verdict: a.verdict };
+      if (typeof a.reason === 'string' && a.reason.length > 0) out.reason = a.reason;
+      return out;
+    }),
+    reportPath,
+  };
+}
+
+/**
+ * Persist a ship-without-verified acknowledgement onto the manifest.
+ * Reads `tree.manifest` for the current state, appends the composed
+ * record to `manifest.shipWithoutVerified[]`, validates the composed
+ * manifest against the 0.4.1 schema, and writes it atomically. On
+ * validation failure the on-disk manifest is untouched (mirrors the
+ * preflight manifest-writer discipline).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {object} args.tree
+ * @param {ShipWithoutVerifiedRecord} args.record
+ * @returns {Promise<{ record: ShipWithoutVerifiedRecord } | import('#core/errors').RcfError>}
+ */
+export async function writeShipWithoutVerifiedRecord({ projectRoot, tree, record }) {
+  const manifest = tree.manifest ?? {};
+  const nextManifest = { ...manifest };
+  const existing = Array.isArray(nextManifest.shipWithoutVerified) ? nextManifest.shipWithoutVerified : [];
+  nextManifest.shipWithoutVerified = [...existing, record];
+
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });
+  if (validation) return validation;
+
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, absPath);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `finalise: ship-without-verified manifest write failed: ${err.message}`,
+      filePath: relPath,
+      stack: err.stack,
+    });
+  }
+  return { record };
+}

package/src/finalise/spawn.js

@@ -0,0 +1,84 @@
+// Fresh-subprocess invocation of `rcf-verify run` (spec §8.2). This is the
+// load-bearing independence guarantee: build-lite's finalise step launches
+// verify as a SEPARATE OS PROCESS with the isolation env - it MUST NOT import
+// verify's engine in-process, because the verifier agent must start from a
+// cold session with zero build context (§9). The subprocess exit code is the
+// gate; findings flow back via the --out report file, never stdout scraping.
+//
+// The isolation env (core's ISOLATION_RECIPE, §7.3) is layered onto the child
+// env here so the recipe travels with the process boundary exactly as §8.2
+// specifies ("spawn ... with the isolation env").
+
+import { spawn } from 'node:child_process';
+
+import { isolationEnv } from '#core/isolation';
+
+/**
+ * Assemble the `rcf-verify run` argument vector from finalise options.
+ * Deterministic and pure so it is directly unit-testable; the exact shape is
+ * the §8.2 invocation contract.
+ *
+ * @param {object} opts
+ * @param {string} opts.repo - RCF chain source (the project root)
+ * @param {string} opts.url - the running deployed app
+ * @param {string} opts.profile - deployed | ci | local-dev
+ * @param {string} opts.out - report artifact path (always written by verify)
+ * @param {string} opts.severityGate - PASS|COSMETIC|DEGRADED|BROKEN
+ * @param {boolean} [opts.parityEnv]
+ * @param {string} [opts.provision] - provisioning FILE path
+ * @param {string} [opts.chain] - PRD/chain ref
+ * @param {string} [opts.persona]
+ * @returns {string[]}
+ */
+export function buildVerifyArgs(opts) {
+  const args = [
+    'run',
+    '--repo', opts.repo,
+    '--profile', opts.profile,
+    '--url', opts.url,
+    '--severity-gate', opts.severityGate,
+    '--out', opts.out,
+  ];
+  if (opts.chain) args.push('--chain', opts.chain);
+  if (opts.parityEnv) args.push('--parity-env');
+  if (opts.provision) args.push('--provision', opts.provision);
+  if (opts.persona) args.push('--persona', opts.persona);
+  return args;
+}
+
+/**
+ * Spawn rcf-verify as a fresh subprocess and resolve with its exit code.
+ * stdio is inherited by default so the operator sees verify's live progress
+ * and its verdict line; the report artifact is read separately by the caller.
+ *
+ * The child env is the isolation recipe layered over the current env (§8.2 +
+ * §7.3): the recipe wins on conflict so a leaked parent value cannot re-enable
+ * auto-memory or non-essential traffic in the verifier session.
+ *
+ * @param {object} args
+ * @param {import('./detect.js').VerifyInvocation} args.invocation
+ * @param {string[]} args.verifyArgs - from buildVerifyArgs()
+ * @param {string} args.cwd
+ * @param {object} [deps]
+ * @param {typeof spawn} [deps.spawn]
+ * @param {NodeJS.ProcessEnv} [deps.baseEnv]
+ * @param {'inherit'|'pipe'|'ignore'} [deps.stdio]
+ * @returns {Promise<{ code: number, signal: NodeJS.Signals | null, env: NodeJS.ProcessEnv }>}
+ */
+export function spawnVerify({ invocation, verifyArgs, cwd }, deps = {}) {
+  const spawnFn = deps.spawn ?? spawn;
+  const childEnv = isolationEnv(deps.baseEnv ?? process.env);
+  const argv = [...invocation.prefixArgs, ...verifyArgs];
+  return new Promise((resolvePromise, reject) => {
+    const child = spawnFn(invocation.command, argv, {
+      cwd,
+      env: childEnv,
+      stdio: deps.stdio ?? 'inherit',
+    });
+    child.on('error', reject);
+    child.on('close', (code, signal) => {
+      // A signalled child (no numeric code) is a failure, not a pass.
+      resolvePromise({ code: code ?? (signal ? 1 : 0), signal, env: childEnv });
+    });
+  });
+}

package/src/intake/fidelity.js

@@ -0,0 +1,105 @@
+// Intake-fidelity classifier (spec §3.7, §6.4 phase 1).
+//
+// Deterministic word-count + signal-count classifier over the raw text of
+// a supplied artefact. The bands are the ones the spec ratified:
+//   none        → nothing supplied (caller passes an empty artefact list)
+//   napkin      → very short: one paragraph or a sketchy note
+//   briefLight  → short brief: names problem and capabilities, unstated NFRs
+//   briefStrong → full product brief with capabilities enumerated, NFRs named,
+//                 out-of-scope called out. The watchpost brief lives here.
+//   prd         → a full PRD or PRD-adjacent doc (front-matter, requirement
+//                 sections, acceptance-shaped bullets)
+//   prdPlusTad  → a PRD plus a TAD (architecture, ADR, TAC signals)
+//
+// The classifier is not a scoring engine; it uses cheap keyword signals
+// (headings, capability lists, NFR keywords, out-of-scope markers,
+// architecture markers) plus word count to assign a band. The operator
+// always confirms the verdict at phase-1 handoff.
+
+export const FIDELITY_LEVELS = Object.freeze([
+  'none',
+  'napkin',
+  'briefLight',
+  'briefStrong',
+  'prd',
+  'prdPlusTad',
+]);
+
+const CAP_HEADINGS = /^(?:\s*#+\s*)(?:capabilit(?:y|ies)|must-have|should-have|features?|user story|user stories|acceptance criteria)\b/im;
+const NFR_HEADINGS = /^(?:\s*#+\s*)(?:non[-\s]?functional|nfr|constraints?|performance|reliability|security|scalability|budgets?)\b/im;
+const OUT_OF_SCOPE = /^(?:\s*#+\s*)?(?:out[-\s]?of[-\s]?scope|non[-\s]?goals?|will not do|not (?:in|for) v[0-9])\b/im;
+const REQ_MARKERS = /^\s*(?:REQ|US|AC)-?[0-9]+/im;
+const PRD_MARKERS = /^(?:\s*#+\s*)?(?:product\s+requirements\s+document|prd|problem statement|users?\s*&?\s*personas?)\b/im;
+const TAD_MARKERS = /^(?:\s*#+\s*)?(?:technical\s+architecture|architecture decision record|adr[-\s]?[0-9]+|tac[-\s]?[0-9]+|system architecture|component diagram|api boundaries)\b/im;
+
+/**
+ * @typedef {'none'|'napkin'|'briefLight'|'briefStrong'|'prd'|'prdPlusTad'} FidelityBand
+ */
+
+/**
+ * @typedef {object} FidelitySignals
+ * @property {number} wordCount
+ * @property {boolean} capabilitiesEnumerated
+ * @property {boolean} nfrsNamed
+ * @property {boolean} outOfScopeListed
+ * @property {boolean} requirementMarkers
+ * @property {boolean} prdShape
+ * @property {boolean} tadShape
+ */
+
+/**
+ * Classify one artefact into a fidelity band. Accepts null/empty text
+ * ("nothing supplied").
+ *
+ * @param {string|null} text
+ * @param {object} [opts]
+ * @param {string|null} [opts.kindHint]  operator hint: napkin|productBrief|prd|prdPlusTad|other
+ * @returns {{ fidelity: FidelityBand, signals: FidelitySignals }}
+ */
+export function classifyFidelity(text, opts = {}) {
+  const hint = opts.kindHint ?? null;
+  const t = typeof text === 'string' ? text : '';
+  const wordCount = t.trim().length === 0 ? 0 : t.trim().split(/\s+/).length;
+  const signals = {
+    wordCount,
+    capabilitiesEnumerated: CAP_HEADINGS.test(t),
+    nfrsNamed: NFR_HEADINGS.test(t),
+    outOfScopeListed: OUT_OF_SCOPE.test(t),
+    requirementMarkers: REQ_MARKERS.test(t),
+    prdShape: PRD_MARKERS.test(t),
+    tadShape: TAD_MARKERS.test(t),
+  };
+
+  // Operator hint takes precedence when it is explicit and unambiguous.
+  if (hint === 'napkin') return { fidelity: 'napkin', signals };
+  if (hint === 'prd') return { fidelity: 'prd', signals };
+  if (hint === 'prdPlusTad') return { fidelity: 'prdPlusTad', signals };
+
+  if (wordCount === 0) return { fidelity: 'none', signals };
+
+  // Structural markers (PRD / TAD / requirement ids) win over the word
+  // count band: an operator supplying an already-structured short doc
+  // (a partial PRD, an ADR, a REQ-ids list) is at the prd/prdPlusTad
+  // band regardless of length.
+  if (signals.tadShape && (signals.prdShape || signals.requirementMarkers)) {
+    return { fidelity: 'prdPlusTad', signals };
+  }
+  if (signals.tadShape) return { fidelity: 'prdPlusTad', signals };
+  if (signals.requirementMarkers || (signals.prdShape && signals.capabilitiesEnumerated)) {
+    return { fidelity: 'prd', signals };
+  }
+
+  if (wordCount < 100) return { fidelity: 'napkin', signals };
+
+  // Brief band: capabilities enumerated + NFRs named + out-of-scope
+  // listed → briefStrong; otherwise briefLight.
+  if (signals.capabilitiesEnumerated && signals.nfrsNamed && signals.outOfScopeListed) {
+    return { fidelity: 'briefStrong', signals };
+  }
+  if (signals.capabilitiesEnumerated || signals.nfrsNamed || signals.outOfScopeListed) {
+    return { fidelity: 'briefLight', signals };
+  }
+  // Default: prose of some length but no signals — treat as napkin
+  // upgraded to briefLight over 400 words.
+  return { fidelity: wordCount >= 400 ? 'briefLight' : 'napkin', signals };
+}

package/src/intake/index.js

@@ -0,0 +1,6 @@
+// Public surface for the intake module (spec §6).
+
+export { classifyFidelity, FIDELITY_LEVELS } from './fidelity.js';
+export { scanArtefactForFindings } from './validate.js';
+export { runIntakePhases } from './orchestrator.js';
+export { writeIntakeRecord, composeIntakeRecord, nextIntakeId } from './manifest-writer.js';

package/src/intake/manifest-writer.js

@@ -0,0 +1,100 @@
+// Intake record composer + writer (spec §3.4).
+//
+// Composes the `intakeClassification` block and appends/replaces it on
+// the manifest, then writes the manifest atomically after schema
+// validation. Uses the same `.tmp → rename` pattern as the preflight
+// writer.
+
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '#core/errors';
+import { validateDocument } from '#core/store';
+
+const ID_RE = /^ic-\d{4}-\d{2}-\d{2}-(\d{3})$/;
+
+/**
+ * Compose the next monotonic intake id for the current date.
+ *
+ * @param {object|null} manifest
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function nextIntakeId(manifest, now = new Date()) {
+  const yyyy = now.getUTCFullYear().toString().padStart(4, '0');
+  const mm = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+  const dd = now.getUTCDate().toString().padStart(2, '0');
+  const prefix = `ic-${yyyy}-${mm}-${dd}-`;
+  const existingRec = manifest?.intakeClassification ?? null;
+  let maxN = 0;
+  if (existingRec && typeof existingRec.id === 'string' && existingRec.id.startsWith(prefix)) {
+    const m = existingRec.id.match(ID_RE);
+    if (m) {
+      const n = Number.parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > maxN) maxN = n;
+    }
+  }
+  return `${prefix}${(maxN + 1).toString().padStart(3, '0')}`;
+}
+
+/**
+ * Compose an intakeClassification block.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} args.fidelity
+ * @param {object[]} args.artefacts
+ * @param {object[]} args.validationFindings
+ * @param {object} args.elicitationScope
+ * @param {Date} [args.now]
+ * @returns {object}
+ */
+export function composeIntakeRecord({ manifest, fidelity, artefacts, validationFindings, elicitationScope, now = new Date() }) {
+  const isoNow = now.toISOString();
+  const record = {
+    id: nextIntakeId(manifest, now),
+    createdAt: isoNow,
+    fidelity,
+    artefacts,
+    validationFindings,
+    elicitationScope,
+    operatorAckAt: isoNow,
+  };
+  return record;
+}
+
+/**
+ * Write the composed intakeClassification onto the manifest.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {object} args.record
+ * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
+ */
+export async function writeIntakeRecord({ projectRoot, tree, record }) {
+  const manifest = tree?.manifest ?? {};
+  const nextManifest = { ...manifest, intakeClassification: record };
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: 'rcf/manifest.json' });
+  if (validation) return validation;
+  const abs = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(abs), { recursive: true });
+    const tmp = `${abs}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, abs);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `intake: manifest write failed: ${err.message}`,
+      filePath: 'rcf/manifest.json',
+      stack: err.stack,
+    });
+  }
+  return { record };
+}

package/src/intake/orchestrator.js

@@ -0,0 +1,138 @@
+// Intake orchestrator (spec §6.4 phases 1-3 combined).
+//
+// Reads the supplied artefacts, runs the fidelity classifier, applies
+// the validation scans, folds in any operator-supplied non-interactive
+// input file, and composes an intakeClassification record ready for the
+// manifest writer. Never talks to a subagent in v1 (the intake-worker
+// dispatch in spec §6.6 is out of scope for this build ship — the
+// deterministic scans plus operator-declared "otherDeclared" findings
+// via --input cover phase 2 without the reader dispatch).
+
+import { readFile, stat } from 'node:fs/promises';
+import { basename, isAbsolute, join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+import { rcfError } from '#core/errors';
+
+import { classifyFidelity } from './fidelity.js';
+import { scanArtefactForFindings } from './validate.js';
+import { composeIntakeRecord } from './manifest-writer.js';
+
+/**
+ * @typedef {'napkin'|'productBrief'|'prd'|'tad'|'other'} ArtefactKind
+ */
+
+const KIND_MAP = new Map([
+  ['napkin', 'napkin'],
+  ['productbrief', 'productBrief'],
+  ['prd', 'prd'],
+  ['prdplustad', 'prd'],
+  ['tad', 'tad'],
+  ['other', 'other'],
+]);
+
+/**
+ * Read + classify + validate every artefact and compose a full
+ * intakeClassification record. Returns an RcfError on IO failure.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string[]} args.artefactPaths
+ * @param {string|null} [args.kindHint]
+ * @param {object|null} [args.input]           optional non-interactive input file
+ * @param {Date} [args.now]
+ * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
+ */
+export async function runIntakePhases({ projectRoot, artefactPaths, kindHint = null, input = null, now = new Date() }) {
+  const artefactMeta = [];
+  const allFindings = [];
+  let text = '';
+  const paths = [...new Set(artefactPaths)];
+  for (const raw of paths) {
+    const abs = isAbsolute(raw) ? raw : join(projectRoot, raw);
+    let body = '';
+    let hash = null;
+    let wordCount = 0;
+    try {
+      body = await readFile(abs, 'utf8');
+      const info = await stat(abs);
+      void info;
+      hash = `sha256:${createHash('sha256').update(body).digest('hex')}`;
+      wordCount = body.trim().length === 0 ? 0 : body.trim().split(/\s+/).length;
+    } catch (err) {
+      return rcfError({
+        kind: 'usage',
+        message: `intake: cannot read artefact ${raw}: ${err.message}`,
+        filePath: raw,
+      });
+    }
+    text += `\n${body}`;
+    const kind = resolveKind({ path: raw, kindHint });
+    artefactMeta.push({
+      path: raw,
+      kind,
+      wordCount,
+      hash,
+      operatorSourced: true,
+    });
+    for (const f of scanArtefactForFindings(body)) allFindings.push(f);
+  }
+
+  const { fidelity, signals } = classifyFidelity(text, { kindHint });
+
+  // Fold non-interactive input: extra findings, operator responses,
+  // and elicitationScope hints all land here.
+  const inputFindings = Array.isArray(input?.validationFindings) ? input.validationFindings : [];
+  const inputResponses = new Map();
+  for (const f of inputFindings) {
+    if (typeof f?.detail === 'string' && typeof f?.operatorResponse === 'string') {
+      inputResponses.set(f.detail, f.operatorResponse);
+    }
+    if (f?.kind === 'otherDeclared') allFindings.push(f);
+  }
+
+  const isoNow = now.toISOString();
+  const findingsWithTimestamps = allFindings.map((f) => {
+    const entry = { kind: f.kind, detail: f.detail, raisedAt: isoNow };
+    if (f.kindDescription) entry.kindDescription = f.kindDescription;
+    const response = inputResponses.get(f.detail) ?? input?.operatorResponse;
+    if (typeof response === 'string' && response.length > 0) {
+      entry.operatorResponse = response;
+      entry.resolvedAt = isoNow;
+    }
+    return entry;
+  });
+
+  const elicitationScope = input?.elicitationScope ?? {
+    prdDrafted: fidelity === 'prd' || fidelity === 'prdPlusTad' ? 'supplied' : 'drafted',
+    reqDraftedFromArtefact: [],
+    reqRequiringElicitation: [],
+    acsFromArtefact: 0,
+    acsFromElicitation: 'all',
+  };
+
+  const record = composeIntakeRecord({
+    manifest: null,
+    fidelity: input?.fidelity ?? fidelity,
+    artefacts: artefactMeta,
+    validationFindings: findingsWithTimestamps,
+    elicitationScope,
+    now,
+  });
+
+  void signals; // exposed on classifier return for future observability
+
+  return { record };
+}
+
+function resolveKind({ path, kindHint }) {
+  const hint = KIND_MAP.get(String(kindHint ?? '').toLowerCase());
+  if (hint) return hint;
+  const base = basename(path).toLowerCase();
+  if (base.includes('napkin')) return 'napkin';
+  if (base.includes('prd') && base.includes('tad')) return 'prd';
+  if (base.includes('prd')) return 'prd';
+  if (base.includes('tad')) return 'tad';
+  if (base.includes('brief')) return 'productBrief';
+  return 'other';
+}

package/src/intake/validate.js

@@ -0,0 +1,80 @@
+// Intake-validation scans (spec §6.4 phase 2).
+//
+// Deterministic scans applied over the raw artefact text; each finding
+// carries a `kind` from the schema enum
+//   impliedButNotStated | contradiction | missingLoadBearingConstraint |
+//   otherDeclared
+// The "otherDeclared" bucket carries a free-text `kindDescription`; the
+// deterministic scans in this module never emit "otherDeclared" — that
+// bucket exists for the intake-worker subagent reader (spec §6.6),
+// which is out of the v1 build scope for this ship.
+//
+// The scans are BROAD by design; the operator resolves each finding at
+// phase 2 before phase 3 hands off to elicitation.
+
+/**
+ * @typedef {'impliedButNotStated'|'contradiction'|'missingLoadBearingConstraint'|'otherDeclared'} FindingKind
+ */
+
+/**
+ * @typedef {object} IntakeFinding
+ * @property {FindingKind} kind
+ * @property {string} detail
+ * @property {string} [kindDescription]
+ */
+
+const SERVICE_HINTS = [
+  { name: 'Resend', envHint: /RESEND_?API_?KEY/i },
+  { name: 'Twilio', envHint: /TWILIO_(?:AUTH_)?TOKEN|TWILIO_ACCOUNT_SID/i },
+  { name: 'SendGrid', envHint: /SENDGRID_?API_?KEY/i },
+  { name: 'Stripe', envHint: /STRIPE_(?:SECRET|API)_KEY/i },
+  { name: 'Slack', envHint: /SLACK_(?:BOT_)?TOKEN|SLACK_WEBHOOK/i },
+];
+
+const NEGATED_LOGIN_PHRASES = /\bno (?:login|sign[-\s]?in|auth|authenticat(?:ion|ed))\s+(?:is|required|needed)?/i;
+const HAS_ADMIN_UI = /\b(admin(?:istrator)?|dashboard|admin panel|admin route)\b/i;
+const HAS_WEB_UI = /\b(browser|html|web page|dashboard|admin)\b/i;
+const HAS_BROWSER_SIGNIN = /\b(browser sign[-\s]?in|sign[-\s]?in page|login page|html login)\b/i;
+const HAS_API_ONLY = /\b(api[-\s]?only|programmatic (?:client|access)|sdk[-\s]?driven|no browser)\b/i;
+
+/**
+ * Scan one artefact and return the deterministic findings.
+ *
+ * @param {string} text
+ * @returns {IntakeFinding[]}
+ */
+export function scanArtefactForFindings(text) {
+  const t = typeof text === 'string' ? text : '';
+  const findings = [];
+
+  // impliedButNotStated: brief mentions a web UI but never names the
+  // sign-in surface (HTML login page vs API-only).
+  if (HAS_WEB_UI.test(t) && !HAS_BROWSER_SIGNIN.test(t) && !HAS_API_ONLY.test(t)) {
+    findings.push({
+      kind: 'impliedButNotStated',
+      detail: 'artefact names a web UI (browser / HTML / dashboard) but does not name whether a browser sign-in page is in scope. The current wording could ship as API-only or with an HTML login; both are consistent with the brief. Resolve before REQ drafting so downstream ACs land on the right shape.',
+    });
+  }
+
+  // contradiction: brief says "no login required" alongside an admin UI.
+  if (NEGATED_LOGIN_PHRASES.test(t) && HAS_ADMIN_UI.test(t)) {
+    findings.push({
+      kind: 'contradiction',
+      detail: 'artefact says "no login required" in one section and names an admin dashboard elsewhere. An unauthenticated admin surface is either a mistake in the brief or a deliberate posture that changes every auth AC downstream.',
+    });
+  }
+
+  // missingLoadBearingConstraint: brief names a third-party service but
+  // does not name the credential env var.
+  for (const svc of SERVICE_HINTS) {
+    const nameRe = new RegExp(`\\b${svc.name}\\b`, 'i');
+    if (nameRe.test(t) && !svc.envHint.test(t)) {
+      findings.push({
+        kind: 'missingLoadBearingConstraint',
+        detail: `artefact names ${svc.name} as an integration but does not name the credential env var. Track A preflight will refuse to accept the service without a declared credential; capture the name now so the preflight session runs against a concrete key.`,
+      });
+    }
+  }
+
+  return findings;
+}