mandrel 1.57.0

package/.agents/scripts/lib/findings/classify-finding.js

@@ -0,0 +1,195 @@
+/**
+ * lib/findings/classify-finding.js — Finding classification + label routing.
+ *
+ * A "finding" here is an exploratory-QA ledger item (see
+ * `.agents/schemas/qa-ledger.schema.json`, Epic #3686). Each item carries a
+ * `class` drawn from a closed enum. `classifyFinding(finding)` resolves that
+ * class and routes it to the GitHub label set Triage applies when promoting
+ * the item to a follow-up ticket.
+ *
+ * Pure function: no network I/O. The class → label routing table is the
+ * single source of truth for which labels a given finding class maps to;
+ * label *names* are pulled from `lib/label-constants.js` so renames land in
+ * one place rather than as string literals here.
+ *
+ * Rejection (not silent defaulting) is the contract: a finding whose class is
+ * absent, empty, or outside the enum throws rather than falling back to a
+ * default class. A misclassified finding routed to the wrong labels is worse
+ * than a loud failure the operator can fix.
+ */
+
+import { META_LABELS } from '../label-constants.js';
+import { normalizeSeverity, SEVERITIES } from './severity.js';
+
+/**
+ * Focus-axis labels (Story #3721). These scope a finding to the area of the
+ * framework it concerns. They are not in `label-constants.js` because the
+ * focus axis is consumer-extensible; the routing table below is the only
+ * in-tree consumer, so the literals are defined here and referenced by symbol.
+ */
+export const FOCUS_LABELS = {
+  PRODUCT: 'focus::product',
+  ENVIRONMENT: 'focus::environment',
+  SCRIPTS: 'focus::scripts',
+  TESTS: 'focus::tests',
+  ENHANCEMENT: 'focus::enhancement',
+};
+
+/**
+ * The closed set of finding classes, mirroring the `class` enum in
+ * `.agents/schemas/qa-ledger.schema.json`. Exported so callers can validate
+ * against the same source of truth.
+ */
+export const FINDING_CLASSES = Object.freeze([
+  'product-bug',
+  'environment-setup',
+  'tooling-dx',
+  'test-gap',
+  'enhancement',
+]);
+
+/**
+ * Class → label-set routing table. Each class maps to exactly one label set.
+ * `tooling-dx` is the framework-gap path: it carries `meta::framework-gap` so
+ * the `/epic-plan` Phase 0 feedback fetcher surfaces it to the planner.
+ */
+const CLASS_TO_LABELS = Object.freeze({
+  'product-bug': [FOCUS_LABELS.PRODUCT],
+  'environment-setup': [FOCUS_LABELS.ENVIRONMENT],
+  'tooling-dx': [FOCUS_LABELS.SCRIPTS, META_LABELS.FRAMEWORK_GAP],
+  'test-gap': [FOCUS_LABELS.TESTS],
+  enhancement: [FOCUS_LABELS.ENHANCEMENT, META_LABELS.CONSUMER_IMPROVEMENT],
+});
+
+/**
+ * The closed set of severity values a finding can carry, re-exported from the
+ * canonical {@link ./severity.js} source of truth (Story #3816) so this module
+ * does not re-declare its own list. Ordered highest → lowest:
+ * `critical | high | medium | low | info`.
+ */
+export { SEVERITIES };
+
+/**
+ * Tokens that, when present in a finding's `area`, `labels`, or explicit
+ * `security` flag, mark it as security-relevant. The security signal is
+ * orthogonal to the class → label mapping: a `product-bug` and a `tooling-dx`
+ * finding can both be security-relevant, so this never alters the class route.
+ */
+const SECURITY_TOKENS = Object.freeze([
+  'security',
+  'injection',
+  'xss',
+  'csrf',
+  'auth',
+  'authz',
+  'authentication',
+  'authorization',
+  'secret',
+  'secrets',
+  'vulnerability',
+  'vuln',
+  'cve',
+]);
+
+/**
+ * Resolve a finding's severity to one of {@link SEVERITIES} via the shared
+ * canonical normaliser. An absent, empty, or unrecognised severity resolves to
+ * the canonical floor (`info`). Case- and whitespace-insensitive. Delegating to
+ * {@link normalizeSeverity} keeps this path bit-for-bit identical to the
+ * `promote-finding` path, so the same finding fingerprints the same regardless
+ * of which path produced its severity (Story #3816).
+ *
+ * @param {object} finding
+ * @returns {string} one of {@link SEVERITIES}
+ */
+function resolveSeverity(finding) {
+  return normalizeSeverity(finding?.severity);
+}
+
+/**
+ * Detect whether a finding is security-relevant. True when the finding sets an
+ * explicit truthy `security` flag, OR when any of its `area` / `labels`
+ * carries a known security token. Pure string inspection — no network I/O.
+ *
+ * @param {object} finding
+ * @returns {boolean}
+ */
+function resolveSecuritySignal(finding) {
+  if (finding?.security === true) return true;
+
+  const haystack = [];
+  if (typeof finding?.area === 'string') haystack.push(finding.area);
+  if (Array.isArray(finding?.labels)) {
+    for (const label of finding.labels) {
+      if (typeof label === 'string') haystack.push(label);
+    }
+  }
+
+  const normalized = haystack.map((s) => s.toLowerCase());
+  return normalized.some((value) =>
+    SECURITY_TOKENS.some((token) => value.includes(token)),
+  );
+}
+
+/**
+ * Resolve the raw `class` field of a finding to a known, non-empty class.
+ *
+ * @param {object} finding
+ * @returns {string} one of {@link FINDING_CLASSES}
+ * @throws {TypeError} when `finding` is not an object
+ * @throws {RangeError} when the class is absent, empty, or unknown
+ */
+function resolveClass(finding) {
+  if (finding === null || typeof finding !== 'object') {
+    throw new TypeError('classifyFinding: finding must be an object');
+  }
+  const raw = finding.class;
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new RangeError(
+      'classifyFinding: finding.class is required and must be a non-empty string',
+    );
+  }
+  const normalized = raw.trim();
+  if (!FINDING_CLASSES.includes(normalized)) {
+    throw new RangeError(
+      `classifyFinding: unknown finding class "${normalized}"; expected one of ${FINDING_CLASSES.join(', ')}`,
+    );
+  }
+  return normalized;
+}
+
+/**
+ * Classify a finding into exactly one class, route it to its label set, and
+ * carry a severity value plus a security signal alongside.
+ *
+ * The class → label routing is unchanged: every class still maps to exactly
+ * the same label set it always did. `severity` and `security` are additive
+ * signal fields the caller can act on (e.g. escalate a high-severity security
+ * finding) — they never alter the label set, so no existing class-to-label
+ * mapping is dropped.
+ *
+ * @param {object} finding — a ledger item carrying a `class` field, and
+ *   optionally `severity` and a `security` flag / security-relevant `area` /
+ *   `labels`.
+ * @returns {{ class: string, labels: string[], severity: string, security: boolean }}
+ *   the resolved class, the ordered GitHub labels Triage should apply, the
+ *   resolved severity (one of {@link SEVERITIES}; `info` when absent), and
+ *   whether the finding is security-relevant.
+ * @throws {TypeError|RangeError} on a non-object finding or an
+ *   unknown/empty class (never silently defaults).
+ */
+export function classifyFinding(finding) {
+  const findingClass = resolveClass(finding);
+  return {
+    class: findingClass,
+    labels: [...CLASS_TO_LABELS[findingClass]],
+    severity: resolveSeverity(finding),
+    security: resolveSecuritySignal(finding),
+  };
+}
+
+export const __testing = {
+  CLASS_TO_LABELS,
+  resolveSeverity,
+  resolveSecuritySignal,
+};

package/.agents/scripts/lib/findings/promote-finding.js

@@ -0,0 +1,353 @@
+/**
+ * lib/findings/promote-finding.js — Promote clustered ledger items to tickets.
+ *
+ * The `f1-shared-qa-core` promotion step (Epic #3798, Feature #3803). It is the
+ * tail of the exploratory-QA Triage path: once an operator has dispositioned a
+ * session's ledger items (see `.agents/schemas/qa-ledger.schema.json` and
+ * `lib/qa/qa-session.js`), the still-untriaged backlog is clustered and each
+ * cluster is promoted to a follow-up ticket — a single Story (via `/story-plan`)
+ * for a tight, one-deliverable cluster, or an Epic (via `/epic-plan --idea`) for
+ * a broad cluster that spans multiple coverage surfaces. Each contributing
+ * ledger item then has the resulting `routedTo` issue link written back onto it
+ * so a resume run sees the item as filed rather than re-promoting it.
+ *
+ * Routing **reuses the shared findings/route logic** — `routeFinding` from
+ * `route-finding.js`, the single dedup/route implementation `audit-to-stories`
+ * and `qa-explore` already share. It does NOT call `audit-to-stories`: that
+ * workflow parses `audit-*-results.md` markdown and is a different intake path.
+ * Here a cluster is adapted onto the canonical finding identity, routed against
+ * existing Issues, and only a `new` decision opens a fresh ticket; an
+ * `update-existing` / `duplicate` / `regression-of-closed` decision links back
+ * to the matched Issue without creating a duplicate.
+ *
+ * Pure orchestration: **no network I/O lives here.** Every GitHub side-effect
+ * (issue search, ticket creation) flows through INJECTED PORTS so the unit test
+ * runs with no network. Production wires the ports to the GitHub provider /
+ * `/story-plan` / `/epic-plan` surfaces; tests pass in-memory stubs.
+ */
+
+import { fingerprintFinding, routeFinding } from './route-finding.js';
+import { highestSeverity as highestSeverityOf } from './severity.js';
+
+/** Triaged dispositions, mirrored from the `disposition` enum in the schema. */
+const TRIAGED_DISPOSITIONS = Object.freeze(['file', 'defer', 'dismiss']);
+
+/** The two promotion targets a cluster routes to. */
+export const PROMOTION_TARGETS = Object.freeze({
+  STORY: 'story',
+  EPIC: 'epic',
+});
+
+/**
+ * A cluster of more than this many distinct coverage surfaces is broad enough
+ * to warrant an Epic (`/epic-plan --idea`) rather than a single Story
+ * (`/story-plan`). One or two surfaces is a tight, single-deliverable cluster.
+ */
+const EPIC_COVERAGE_THRESHOLD = 2;
+
+/**
+ * True when a ledger item has NOT yet been promoted — i.e. it is part of the
+ * rolling backlog. An item is untriaged when its `disposition` is not one of
+ * the canonical triaged values, OR it is explicitly dispositioned `file` but
+ * has not yet been routed (`routedTo` absent). A `defer` / `dismiss` item, or
+ * an already-`routedTo` item, is skipped.
+ *
+ * @param {{ disposition?: unknown, routedTo?: unknown }} item
+ * @returns {boolean}
+ */
+export function isPromotable(item) {
+  if (item === null || typeof item !== 'object') return false;
+  if (item.routedTo) return false;
+  const disposition = item.disposition;
+  if (disposition === 'defer' || disposition === 'dismiss') return false;
+  // `file` items are promotable; anything not in the triaged set (pending,
+  // untriaged, null, absent) is the rolling backlog and also promotable.
+  if (disposition === 'file') return true;
+  return !TRIAGED_DISPOSITIONS.includes(disposition);
+}
+
+/**
+ * Stable cluster key for a ledger item: its `class`. Items sharing a class
+ * describe the same kind of signal (a product bug, a tooling-DX gap, …) and
+ * merge into one follow-up ticket. A class whose items span many distinct
+ * coverage surfaces is broad enough to promote to an Epic (see
+ * {@link targetForCluster}); a class confined to one or two surfaces is a
+ * single-deliverable Story. Coverage is therefore a *secondary* signal that
+ * sizes the cluster rather than splitting it.
+ *
+ * @param {{ class?: string }} item
+ * @returns {string}
+ */
+function clusterKeyFor(item) {
+  return String(item?.class ?? 'unknown')
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * The highest severity present across a cluster's items, resolved through the
+ * shared canonical {@link ./severity.js} vocabulary (Story #3816). This module
+ * no longer declares its own severity rank table — the ordering lives in one
+ * place so a cluster severity and a `classify-finding` severity for the same
+ * input are identical, keeping the `fingerprintFinding` identity stable.
+ *
+ * @param {Array<{ severity?: string }>} items
+ * @returns {string} one of the canonical severities.
+ */
+function highestSeverity(items) {
+  return highestSeverityOf(items.map((item) => item?.severity));
+}
+
+/**
+ * Cluster the promotable (untriaged / unrouted) ledger items by coverage
+ * surface + class. Returns one cluster per distinct key, each carrying the
+ * contributing items, the distinct coverage surfaces it spans, the highest
+ * severity in the merge, and a synthesized title. Deterministic: clusters and
+ * their items preserve first-seen order.
+ *
+ * @param {Array<object>} items — ledger items (the full session ledger).
+ * @returns {Array<{
+ *   key: string,
+ *   class: string,
+ *   coverages: string[],
+ *   severity: string,
+ *   title: string,
+ *   items: object[],
+ * }>}
+ * @throws {TypeError} when `items` is not an array.
+ */
+export function clusterLedgerItems(items) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('clusterLedgerItems: items must be an array');
+  }
+
+  const byKey = new Map();
+  for (const item of items) {
+    if (!isPromotable(item)) continue;
+    const key = clusterKeyFor(item);
+    if (!byKey.has(key)) {
+      byKey.set(key, []);
+    }
+    byKey.get(key).push(item);
+  }
+
+  const clusters = [];
+  for (const [key, clusterItems] of byKey.entries()) {
+    const coverages = [
+      ...new Set(
+        clusterItems.map((i) => String(i?.coverage ?? 'unknown').trim()),
+      ),
+    ];
+    const cls = String(clusterItems[0]?.class ?? 'unknown').trim();
+    const title =
+      clusterItems.length === 1
+        ? clusterItems[0].evidence
+        : `Address ${clusterItems.length} ${cls} findings in ${coverages.join(' / ')}`;
+    clusters.push({
+      key,
+      class: cls,
+      coverages,
+      severity: highestSeverity(clusterItems),
+      title,
+      items: clusterItems,
+    });
+  }
+
+  return clusters;
+}
+
+/**
+ * Decide a cluster's promotion target. A cluster that spans more than
+ * {@link EPIC_COVERAGE_THRESHOLD} distinct coverage surfaces is broad enough to
+ * warrant an Epic (`/epic-plan --idea`); otherwise it is a single-deliverable
+ * Story (`/story-plan`).
+ *
+ * @param {{ coverages: string[] }} cluster
+ * @returns {'story'|'epic'}
+ */
+export function targetForCluster(cluster) {
+  const surfaces = Array.isArray(cluster?.coverages)
+    ? cluster.coverages.length
+    : 0;
+  return surfaces > EPIC_COVERAGE_THRESHOLD
+    ? PROMOTION_TARGETS.EPIC
+    : PROMOTION_TARGETS.STORY;
+}
+
+/**
+ * Adapt a cluster onto the canonical finding identity that `routeFinding`
+ * fingerprints over (`title`, `area`, `primaryFile`, `severity`, `labels`).
+ * The coverage surface stands in for `area`; the class becomes a label so two
+ * clusters with the same title but different classes fingerprint distinctly.
+ *
+ * @param {{ title: string, coverages: string[], class: string, severity: string }} cluster
+ * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string[] }}
+ */
+function clusterToFinding(cluster) {
+  return {
+    title: cluster.title,
+    area: cluster.coverages.join(','),
+    primaryFile: '',
+    severity: cluster.severity,
+    labels: [cluster.class],
+  };
+}
+
+/**
+ * Build the `routedTo` link the schema stamps onto a promoted ledger item.
+ *
+ * The `routedTo.url` field is `minLength: 1` in both `qa-finding.schema.json`
+ * and `qa-ledger.schema.json`, and the search/create port contract requires a
+ * routed issue to carry its canonical URL. So rather than silently stamp an
+ * empty string (which would persist a schema-invalid ledger item), this guards
+ * the url and throws when it is absent or blank (Story #3816, AC #4).
+ *
+ * @param {{ number: number, url?: string }} issue
+ * @param {'story'|'epic'|'issue'} kind
+ * @returns {{ issue: number, url: string, kind: string }}
+ * @throws {Error} when the routed issue has no non-empty `url`.
+ */
+function routedToLink(issue, kind) {
+  const url = typeof issue?.url === 'string' ? issue.url.trim() : '';
+  if (url.length === 0) {
+    throw new Error(
+      `promoteFindings: routed issue #${issue?.number ?? '?'} is missing a url; ` +
+        'the search/create port contract requires a non-empty url ' +
+        '(routedTo.url is minLength:1 in the qa-finding/qa-ledger schemas)',
+    );
+  }
+  return {
+    issue: issue.number,
+    url,
+    kind,
+  };
+}
+
+/**
+ * Promote the clustered untriaged ledger items into Stories / Epics via the
+ * shared findings/route logic, then write the resulting `routedTo` issue link
+ * back onto each contributing ledger item.
+ *
+ * For each cluster:
+ *   1. Adapt the cluster onto the canonical finding shape and route it with the
+ *      shared `routeFinding` against existing Issues (via the injected search
+ *      port). This dedups against work already filed.
+ *   2. On a `new` decision, open the follow-up ticket through the injected
+ *      `createStory` (`/story-plan`) or `createEpic` (`/epic-plan --idea`) port,
+ *      chosen by {@link targetForCluster}. On any other decision, link back to
+ *      the matched Issue rather than creating a duplicate.
+ *   3. Stamp the resolved `routedTo` link onto every contributing ledger item
+ *      (mutating the item objects in place, so a `qa-session` append persists
+ *      the link).
+ *
+ * All GitHub side-effects flow through the injected ports — there is no network
+ * I/O in this module, so the unit test runs offline.
+ *
+ * @param {Array<object>} ledgerItems — the full session ledger.
+ * @param {object} ports
+ * @param {(sha: string) => Promise<Array<{ number: number, state: string, body?: string }>>} [ports.searchIssues]
+ *   Fingerprint-keyed lookup over open+closed issues, forwarded to `routeFinding`.
+ * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.searchCandidates]
+ *   Optional semantic candidate search, forwarded to `routeFinding`.
+ * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createStory
+ *   Opens a single Story (`/story-plan`) for a tight cluster.
+ * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createEpic
+ *   Opens an Epic (`/epic-plan --idea`) for a broad cluster.
+ * @returns {Promise<{
+ *   promotions: Array<{
+ *     clusterKey: string,
+ *     target: 'story'|'epic',
+ *     decision: string,
+ *     created: boolean,
+ *     issue: number,
+ *     routedTo: { issue: number, url: string, kind: string },
+ *     itemIds: string[],
+ *   }>,
+ *   skipped: number,
+ * }>}
+ * @throws {Error} when a required create port is missing for a routed cluster.
+ */
+export async function promoteFindings(ledgerItems, ports = {}) {
+  const { searchIssues, searchCandidates, createStory, createEpic } = ports;
+  if (
+    typeof searchCandidates !== 'function' &&
+    typeof searchIssues !== 'function'
+  ) {
+    throw new Error(
+      'promoteFindings: a searchCandidates or searchIssues port is required',
+    );
+  }
+
+  const clusters = clusterLedgerItems(ledgerItems);
+  const promotions = [];
+
+  for (const cluster of clusters) {
+    const finding = clusterToFinding(cluster);
+    const route = await routeFinding(finding, {
+      searchIssues,
+      searchCandidates,
+    });
+
+    const target = targetForCluster(cluster);
+    let issue;
+    let created = false;
+
+    if (route.decision === 'new') {
+      const createPort =
+        target === PROMOTION_TARGETS.EPIC ? createEpic : createStory;
+      if (typeof createPort !== 'function') {
+        throw new Error(
+          `promoteFindings: a ${target === PROMOTION_TARGETS.EPIC ? 'createEpic' : 'createStory'} port is required to promote cluster ${cluster.key}`,
+        );
+      }
+      issue = await createPort(cluster);
+      created = true;
+    } else {
+      // Already filed (open match, duplicate, or regression of a closed
+      // ticket) — link back to the matched Issue instead of duplicating.
+      issue = {
+        number: route.matchedIssue.number,
+        url: route.matchedIssue.url,
+      };
+    }
+
+    const kind = created ? target : 'issue';
+    const link = routedToLink(issue, kind);
+
+    // Write the routedTo link back onto each contributing ledger item.
+    for (const item of cluster.items) {
+      item.routedTo = { ...link };
+    }
+
+    promotions.push({
+      clusterKey: cluster.key,
+      target,
+      decision: route.decision,
+      created,
+      issue: issue.number,
+      routedTo: link,
+      itemIds: cluster.items.map((i) => i.id),
+    });
+  }
+
+  const promotedItemCount = promotions.reduce(
+    (sum, p) => sum + p.itemIds.length,
+    0,
+  );
+
+  return {
+    promotions,
+    skipped:
+      ledgerItems.filter((i) => i && typeof i === 'object').length -
+      promotedItemCount,
+  };
+}
+
+export const __testing = {
+  EPIC_COVERAGE_THRESHOLD,
+  TRIAGED_DISPOSITIONS,
+  clusterKeyFor,
+  clusterToFinding,
+  highestSeverity,
+  fingerprintFinding,
+};