@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/security.js

@@ -0,0 +1,222 @@
+import { readFileSync } from 'node:fs';
+import picomatch from 'picomatch';
+import { parse as parseYaml } from 'yaml';
+import { globsOverlap, synthesizeLiteralSegment } from './claims.js';
+import { SmithError } from './errors.js';
+import { SENSITIVE_PATHS_POLICY_PATH } from './paths.js';
+export class SecurityError extends SmithError {
+}
+/**
+ * Every read below refuses a value of the wrong shape rather than substituting
+ * an empty one, for the reason the empty-`globs` throw already gives: a trigger
+ * the dispatcher cannot read does not fire weakly, it does not fire at all.
+ * `cases: infra` is valid YAML and a plausible slip -- the key takes a list,
+ * and a one-element list looks like a scalar -- and it turns
+ * `dispatchSecurityReviewer` from true to false with an empty trigger list.
+ *
+ * A *wrong* value stays legal: `cases: [infrastructure]` fires nothing either,
+ * but it is a sentence the operator wrote and can read back. Only shapes no
+ * comparison can read are refused.
+ */
+const NEVER_FIRES = 'A trigger the dispatcher cannot read does not fire weakly, it does not fire at all.';
+/** Copied, not aliased: two parses must not share one array. */
+function stringList(field, value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new SecurityError('security.invalid-policy', `sensitive-paths.yml ${field} must be a list of strings; got ${JSON.stringify(value)}. ${NEVER_FIRES}`, { field, value });
+    }
+    return [...value];
+}
+function flag(field, value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value !== 'boolean') {
+        throw new SecurityError('security.invalid-policy', `sensitive-paths.yml ${field} must be true or false; got ${JSON.stringify(value)}. ${NEVER_FIRES}`, { field, value });
+    }
+    return value;
+}
+/** The block, not just its keys: a scalar here takes all three arms dark at once. */
+function otherTriggers(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new SecurityError('security.invalid-policy', `sensitive-paths.yml other_triggers must be a block of keys; got ${JSON.stringify(value)}. ${NEVER_FIRES}`, { field: 'other_triggers', value });
+    }
+    return value;
+}
+export function parseSensitivePathsPolicy(yamlText) {
+    const doc = (parseYaml(yamlText) ?? {});
+    const globs = stringList('globs', doc.globs);
+    if (globs.length === 0) {
+        throw new SecurityError('security.invalid-policy', 'sensitive-paths.yml has no globs — a path trigger with an empty glob list never fires.');
+    }
+    const other = otherTriggers(doc.other_triggers);
+    // `epic_cases` was the original spelling, written before it was clear that
+    // `case` lives on the task spec and not on the epic. Both are read, and the
+    // error names whichever spelling the file actually used.
+    const usesCases = other.cases !== undefined && other.cases !== null;
+    return {
+        globs,
+        exclude: stringList('exclude', doc.exclude),
+        cases: usesCases
+            ? stringList('other_triggers.cases', other.cases)
+            : stringList('other_triggers.epic_cases', other.epic_cases),
+        epicTags: stringList('other_triggers.epic_tags', other.epic_tags),
+        scheduledRecheck: flag('other_triggers.scheduled_recheck', other.scheduled_recheck),
+    };
+}
+export function loadSensitivePathsPolicy(filePath = SENSITIVE_PATHS_POLICY_PATH) {
+    return parseSensitivePathsPolicy(readFileSync(filePath, 'utf8'));
+}
+/** Stands in for "some filename" when a pattern ends in `/**`. */
+const PROBE_SEGMENT = '__smith_probe__';
+/**
+ * Every literal a segment's brace set could pick, not just the leading one:
+ * `*auth*.{ts,py}` -> ['*auth*.ts', '*auth*.py'].
+ *
+ * `synthesizeLiteralSegment` keeps only the first alternative, which is the
+ * right call where it lives — it builds *a* candidate, and claims.ts asks
+ * whether one exists. Here the alternatives are the policy's nine-language
+ * extension list, so collapsing them to the leading `ts` made every file glob
+ * in the file silently TypeScript-only: a `.py` or `.tsx` claim had no
+ * candidate that could satisfy the glob at all (D-176).
+ */
+function braceAlternatives(segment) {
+    const brace = /\{([^{}]*)\}/.exec(segment);
+    if (brace === null)
+        return [segment];
+    const whole = brace[0];
+    return (brace[1] ?? '')
+        .split(',')
+        .flatMap((choice) => braceAlternatives(segment.replace(whole, () => choice)));
+}
+/**
+ * The concrete filenames a pattern's own final segment would accept. A pattern
+ * ending in `/**` accepts any filename and proposes the probe.
+ */
+function tailCandidates(pattern) {
+    const segments = pattern.split('/').filter((s) => s.length > 0);
+    const last = segments[segments.length - 1] ?? '';
+    if (last === '**')
+        return [PROBE_SEGMENT];
+    return braceAlternatives(last).map(synthesizeLiteralSegment);
+}
+/**
+ * `dot: true` throughout: the two entries this policy most needs to catch are
+ * `**\/*.env*` and `**\/.github/workflows/**`, and picomatch's default hides
+ * every dotfile from `*` and `**`. A trigger that cannot see `.env` is not a
+ * trigger.
+ */
+function matches(pattern, value) {
+    return picomatch(pattern, { dot: true })(value);
+}
+/**
+ * Concrete paths built from a claim's static base plus a policy glob's literal
+ * segments, one per filename either side proposes: `src/**` + `**\/auth/**` ->
+ * `src/auth/__smith_probe__`, `ui/src/**\/*.tsx` + `**\/auth/**` ->
+ * `ui/src/auth/x.tsx`.
+ *
+ * This is the case `globsOverlap` gives up on. Its `couldJointlyMatch` only
+ * ever synthesizes a *tail* — `src/__smith_probe__` and `__smith_probe__` for
+ * that pair — and neither satisfies both sides, so it answers "no overlap" for
+ * a claim that plainly contains `src/auth/login.ts`. Policy globs are almost
+ * all of the `**\/<literal>/**` shape, so that gap is the common case here, not
+ * an edge one. It stays local to this module: `globsOverlap` is load-bearing
+ * for wave scheduling, where a wider answer means more serialization.
+ *
+ * Residual, named rather than closed: when both sides constrain the filename
+ * and neither side's proposal satisfies the other — claim `src/*.vue` against
+ * `**\/*jwt*`, where the path that satisfies both is `src/jwt.vue` — no
+ * candidate is synthesized and the answer is "no overlap". Closing it needs
+ * real glob intersection rather than a probe. It errs toward not firing, which
+ * is the unsafe direction here, so it is worth revisiting if the policy ever
+ * grows an extension-free glob with no directory-shaped sibling.
+ */
+function sharesSynthesizedPath(claim, glob) {
+    const segments = glob.split('/').filter((s) => s.length > 0);
+    const trailingGlobstar = segments[segments.length - 1] === '**';
+    // The directories the glob names, without its own filename segment.
+    const dirs = (trailingGlobstar ? segments : segments.slice(0, -1))
+        .filter((s) => s !== '**')
+        .map(synthesizeLiteralSegment);
+    const base = picomatch
+        .scan(claim)
+        .base.split('/')
+        .filter((s) => s.length > 0);
+    // Both sides propose a filename, because either side may be the one that
+    // constrains it: a glob ending in `**` leaves it free and the claim's own
+    // tail is then the only constraint — which is how `ui/src/**/*.tsx` used to
+    // miss `**/auth/**` while the narrower `ui/src/auth/Login.tsx` fired it,
+    // the inversion this matcher exists to prevent (D-176). Widening the
+    // candidate list cannot produce a false positive: a candidate still has to
+    // satisfy both patterns.
+    return [...tailCandidates(glob), ...tailCandidates(claim)].some((tail) => {
+        const candidate = [...base, ...dirs, tail].join('/');
+        if (candidate.length === 0)
+            return false;
+        return matches(claim, candidate) && matches(glob, candidate);
+    });
+}
+/**
+ * Overlap, not containment: a claim fires a glob when *some* real path
+ * satisfies both. A task claiming `src/**` must fire against `**\/auth/**`
+ * even though it is the wider pattern — containment-only matching is the
+ * failure mode where a broadly scoped task escapes the review a narrowly
+ * scoped one gets.
+ *
+ * The direct consequence, stated so it is not mistaken for a bug: an
+ * open-ended `<dir>/**` claim fires every directory-shaped glob in the policy,
+ * because such a claim really could add `<dir>/auth/session.ts` tomorrow. For
+ * a security trigger that is the safe direction to err in.
+ */
+export function claimTouchesGlob(claim, glob) {
+    if (matches(glob, claim))
+        return true; // a literal claim sitting inside the glob
+    if (globsOverlap(claim, glob))
+        return true;
+    return sharesSynthesizedPath(claim, glob);
+}
+/**
+ * Exclusions are containment, deliberately: a claim is silenced only when it
+ * lies entirely inside an exclusion. Overlap here would let `**\/*.test.ts`
+ * silence `src/**`, and every broadly scoped task could dodge the review by
+ * claiming a tree that happens to hold a test file.
+ */
+function isExcluded(claim, exclude) {
+    return exclude.some((pattern) => matches(pattern, claim));
+}
+/**
+ * The security-reviewer's three dispatch triggers, computed instead of
+ * remembered (agent-interviews.md N-7, punch list P9-4). A trigger that fires
+ * only when the orchestrator remembers to check is not a trigger.
+ *
+ * At most one trigger per claim: the glob is evidence for "this claim is
+ * sensitive", not an enumeration of every glob it could match.
+ */
+export function securityTriggers(task, policy = loadSensitivePathsPolicy(), context = {}) {
+    const triggers = [];
+    for (const claim of task.claims) {
+        if (isExcluded(claim, policy.exclude))
+            continue;
+        const glob = policy.globs.find((candidate) => claimTouchesGlob(claim, candidate));
+        if (glob !== undefined)
+            triggers.push({ trigger: 'sensitive-claim-path', claim, glob });
+    }
+    const taskCase = context.case ?? task.case;
+    if (taskCase !== undefined && policy.cases.includes(taskCase)) {
+        triggers.push({ trigger: 'case', case: taskCase });
+    }
+    for (const tag of context.epicTags ?? []) {
+        if (policy.epicTags.includes(tag))
+            triggers.push({ trigger: 'epic-tag', tag });
+    }
+    if (context.scheduledRecheck === true && policy.scheduledRecheck) {
+        triggers.push({ trigger: 'scheduled-recheck' });
+    }
+    return {
+        taskId: task.task_id ?? null,
+        dispatchSecurityReviewer: triggers.length > 0,
+        triggers,
+    };
+}

package/factory/orchestrator/dist/severity.js

@@ -0,0 +1,293 @@
+import { readFileSync } from 'node:fs';
+import picomatch from 'picomatch';
+import { parse as parseYaml } from 'yaml';
+import { SmithError } from './errors.js';
+import { SEVERITY_POLICY_PATH } from './paths.js';
+export class SeverityError extends SmithError {
+}
+/** Escalation order, worst first — the same order severity.yml/taxonomy.yml document values in. */
+export const SEVERITY_ORDER = [
+    'S1-stop-the-line',
+    'S2-major',
+    'S3-minor',
+    'S4-nit',
+];
+/**
+ * Position in SEVERITY_ORDER, or `null` for a value that is not in it.
+ *
+ * `null` rather than a sentinel index, because both sentinels lie:
+ * `Number.POSITIVE_INFINITY` makes an unknown severity the mildest thing in the
+ * list and `-1` makes it the worst, and a caller that forgets to check gets a
+ * confident wrong answer either way. Callers that must not silently pass an
+ * unknown value — escalate() below — turn the `null` into a
+ * `severity.unknown-severity` throw.
+ */
+export function severityRank(severity) {
+    const index = SEVERITY_ORDER.indexOf(severity);
+    return index === -1 ? null : index;
+}
+/**
+ * The worse of two severities, worst-wins. Used by crossFinding.ts's
+ * `highest-wins` resolution, where two providers raised the same fingerprint
+ * and disagree on how bad it is.
+ *
+ * An unknown value on either side throws rather than losing the comparison:
+ * mintFindings() already refuses a non-canonical severity, so an unknown one
+ * here means a stored finding predates a taxonomy edit, and quietly treating it
+ * as mild is how an S1 becomes an S4.
+ */
+export function worseSeverity(a, b) {
+    const rankA = severityRank(a);
+    const rankB = severityRank(b);
+    for (const [value, rank] of [
+        [a, rankA],
+        [b, rankB],
+    ]) {
+        if (rank === null) {
+            throw new SeverityError('severity.unknown-severity', `Unknown severity "${value}".`, {
+                severity: value,
+            });
+        }
+    }
+    return rankA <= rankB ? a : b;
+}
+export function parseSeverityPolicy(yamlText) {
+    const doc = parseYaml(yamlText);
+    const rawLevels = doc.levels;
+    if (!rawLevels || typeof rawLevels !== 'object') {
+        throw new SeverityError('severity.invalid-document', 'severity.yml is missing `levels`.');
+    }
+    const levels = {};
+    for (const [name, level] of Object.entries(rawLevels)) {
+        if (typeof level.blocks_merge !== 'boolean') {
+            throw new SeverityError('severity.invalid-document', `severity.yml level "${name}" is missing boolean blocks_merge.`, { level: name });
+        }
+        levels[name] = { blocksMerge: level.blocks_merge };
+    }
+    return { levels };
+}
+export function loadSeverityPolicy(filePath = SEVERITY_POLICY_PATH) {
+    return parseSeverityPolicy(readFileSync(filePath, 'utf8'));
+}
+const ENTRY_HEADING = /^### /;
+const SECTION_HEADING = /^## (.+)$/;
+const BULLET = /^- ([a-z_]+):\s*(.*)$/;
+/** An indented, non-bullet line — a continuation of the previous bullet's value. */
+const CONTINUATION = /^\s+(\S.*)$/;
+/**
+ * taxonomy.yml `lesson_scope`, in compiled-section order — only entries under
+ * one of these `##` sections are real lessons, which is also what stops a `##`
+ * heading smuggled into a statement from minting one. Single source for both
+ * the parse side (here) and the compile side (`lessons.ts` imports this);
+ * `test/severity.test.ts` asserts it still matches taxonomy.yml.
+ */
+export const LESSON_SCOPES = [
+    'agent-role',
+    'claim-path',
+    'case-type',
+    'stack-wide',
+    'security',
+];
+const VALID_SCOPES = new Set(LESSON_SCOPES);
+/**
+ * Parse the "Same-mistake entry format" documented in lessons.md itself
+ * (§ Same-mistake entry format): a level-3 heading starts an entry, followed
+ * by `- key: value` bullets until a blank line or the next heading. A bullet
+ * value may wrap onto indented continuation lines (lessons.md's own example
+ * does exactly this for `statement`) — those are appended, trimmed and
+ * space-joined, to the bullet they follow; without this, a multi-line
+ * statement round-trips silently truncated mid-sentence. Entries missing
+ * statement/lesson_id are skipped, not fatal — lessons.md also carries
+ * non-rule / placeholder content ("_(none yet)_", prose) this parser has no
+ * business rejecting the whole file over. `finding_category` is OPTIONAL
+ * (lesson.schema.json says so, and agent-role/case-type entries never carry
+ * one) and parses as `''`: this file has two readers, the same-mistake match
+ * below and dispatch-time injection (lessons.ts, P9-2), and dropping a
+ * category-less entry here made every agent-role/case-type lesson — including
+ * every lesson `smith dream` raises — compile into lessons.md and then reach
+ * no one. `findMatchingLesson` skips the empty category explicitly, so
+ * escalation still matches exactly what it matched before. Only
+ * `###` headings inside a real `lesson_scope` section (`##
+ * agent-role`/`claim-path`/`case-type`/`stack-wide`) are parsed as entries —
+ * this also keeps the illustrative fenced example in lessons.md's own
+ * "Same-mistake entry format" doc section (before any `##` scope heading)
+ * from being parsed as a real lesson.
+ *
+ * Three bullets are SELECTORS — the one field a scope is filtered by at
+ * dispatch (D-129): `claim_path` for `claim-path`, `agent_role` for
+ * `agent-role`, `case_type` for `case-type`. Each is optional here and parses
+ * to `''` when absent, except `claim_path`, which keeps its historical `'**'`
+ * default. That asymmetry is deliberate and `lessonsForScope` depends on it: a
+ * missing selector must match NOTHING rather than everything, so an entry that
+ * names no role reaches no role instead of every one.
+ */
+export function parseLessons(markdown) {
+    const lines = markdown.split('\n');
+    const rules = [];
+    let scope = '';
+    let current = null;
+    let lastKey = null;
+    function flush() {
+        if (!current)
+            return;
+        const { lesson_id, finding_category, claim_path, agent_role, case_type, statement } = current;
+        if (lesson_id && statement) {
+            rules.push({
+                lessonId: lesson_id,
+                scope,
+                category: finding_category ?? '',
+                claimPath: claim_path ?? '**',
+                agentRole: agent_role ?? '',
+                caseType: case_type ?? '',
+                statement,
+            });
+        }
+        current = null;
+        lastKey = null;
+    }
+    for (const line of lines) {
+        const sectionMatch = line.match(SECTION_HEADING);
+        if (sectionMatch) {
+            flush();
+            scope = sectionMatch[1].trim();
+            continue;
+        }
+        if (ENTRY_HEADING.test(line)) {
+            flush();
+            current = VALID_SCOPES.has(scope) ? {} : null;
+            continue;
+        }
+        if (current) {
+            const bulletMatch = line.match(BULLET);
+            if (bulletMatch) {
+                const key = bulletMatch[1];
+                current[key] = bulletMatch[2].trim();
+                lastKey = key;
+                continue;
+            }
+            if (line.trim() === '') {
+                // A blank line doesn't close the entry (only the next heading, or
+                // EOF, does) but it does end any bullet's continuation run.
+                lastKey = null;
+                continue;
+            }
+            const continuationMatch = line.match(CONTINUATION);
+            if (continuationMatch && lastKey) {
+                const existingValue = current[lastKey] ?? '';
+                current[lastKey] = `${existingValue} ${continuationMatch[1].trim()}`.trim();
+            }
+        }
+    }
+    flush();
+    return rules;
+}
+/**
+ * Scopes whose claim_path is meaningful for the per-file same-mistake match
+ * (lessons.md convention). `security` is here because a security lesson is
+ * written against the paths it guards ("src/auth/**") — a repeat security
+ * finding on one of those paths is exactly what escalation is for. Left out, a
+ * security lesson would compile and be read by agents but never escalate
+ * anything (interview N-8).
+ */
+const FILE_SCOPED = new Set(['claim-path', 'stack-wide', 'security']);
+/**
+ * Whether this lesson's scope makes its `claim_path` mean anything. An
+ * `agent-role`/`case-type` entry has no file to check a finding against, so it
+ * never participates in the per-file match however it is written.
+ */
+export function isFileScoped(lesson) {
+    return FILE_SCOPED.has(lesson.scope);
+}
+/**
+ * Whether this lesson's compiled `claim_path` covers `filePath` — the second
+ * half of the escalation match, exported so `lessonAudit.ts` can ask the match
+ * its own question rather than reimplementing the glob semantics beside it.
+ */
+export function lessonCoversFile(lesson, filePath) {
+    if (!isFileScoped(lesson))
+        return false;
+    const isMatch = picomatch(lesson.claimPath);
+    return isMatch(filePath);
+}
+/**
+ * Whether this lesson can ever escalate anything — the two conditions of the
+ * match below that depend on the lesson alone, not on the finding it is being
+ * matched against.
+ *
+ *   1. It names a `finding_category`. The match is an equality against the new
+ *      finding's category, so an entry naming none is skipped before its claim
+ *      path is ever consulted. A category-less lesson (agent-role/case-type, or
+ *      anything `smith dream` raised) is injected at dispatch and read by
+ *      agents; it is simply never a *same mistake*, because there is no
+ *      category for it to be the same mistake as.
+ *   2. Its scope is file-scoped. `agent-role`/`case-type` entries have no file
+ *      to check a finding against.
+ *
+ * Exported because the same-mistake KPI has to count the instrument as well as
+ * the reading (sameMistakeKpi.ts), and a second copy of these two conditions is
+ * a second thing to keep true — interview N-8, where the compile side and the
+ * parse side each kept their own scope list and `security` vanished between
+ * them with no error anywhere.
+ */
+export function canEscalate(lesson) {
+    return lesson.category !== '' && isFileScoped(lesson);
+}
+function findMatchingLesson(category, filePath, lessons) {
+    for (const lesson of lessons) {
+        if (!canEscalate(lesson))
+            continue;
+        if (lesson.category === category && lessonCoversFile(lesson, filePath))
+            return lesson;
+    }
+    return null;
+}
+function escalate(severity, policy) {
+    const index = severityRank(severity);
+    if (index === null) {
+        throw new SeverityError('severity.unknown-severity', `Unknown severity "${severity}".`, {
+            severity,
+        });
+    }
+    const escalated = SEVERITY_ORDER[Math.max(0, index - 1)];
+    if (!policy.levels[escalated]) {
+        throw new SeverityError('severity.unknown-severity', `Escalated severity "${escalated}" is not defined in severity.yml.`, { severity: escalated });
+    }
+    return escalated;
+}
+function actionFor(severity, level) {
+    if (level.blocksMerge)
+        return 'block';
+    return severity.startsWith('S3') ? 'waiver-batch' : 'log-only';
+}
+/**
+ * Pure, deterministic gate decision for one finding: S1/S2 block, S3
+ * waiver-batch, S4 log-only (severity.yml) — escalated one severity level,
+ * up-capped at S1, when the finding matches an approved lesson for the same
+ * file + category (architecture §9.7).
+ */
+export function decide(finding, context, policy = loadSeverityPolicy()) {
+    // Corroboration first, escalation second, and the order is the decision:
+    // a repeat mistake is one level worse than whatever the finding actually
+    // IS, so the two readings have to be reconciled before the lesson has
+    // something to escalate. Reversed, a corroborated S2 that repeats a lesson
+    // would land at S2 instead of S1.
+    const corroborated = context.corroboratedSeverity === undefined
+        ? finding.severity
+        : worseSeverity(finding.severity, context.corroboratedSeverity);
+    const matched = findMatchingLesson(finding.finding_category, context.filePath, context.lessons);
+    const severity = matched ? escalate(corroborated, policy) : corroborated;
+    const level = policy.levels[severity];
+    if (!level) {
+        throw new SeverityError('severity.unknown-severity', `Unknown severity "${severity}".`, {
+            severity,
+        });
+    }
+    return {
+        severity,
+        blocks: level.blocksMerge,
+        action: actionFor(severity, level),
+        sameMistake: matched !== null,
+        matchedLessonId: matched?.lessonId ?? null,
+        corroborated: corroborated !== finding.severity,
+    };
+}