cclaw-cli 0.23.1 → 0.24.0

package/dist/cli.js

@@ -58,7 +58,7 @@ Commands:
              Flags: --stage=<id>         Limit to one flow stage (${FLOW_STAGES.join("|")}).
                     --tier=<A|B|C>       Fidelity tier (A=single-shot, B=tools, C=workflow).
                     --schema-only        Run only structural verifiers (default).
-                    --rules              Run structural + rule verifiers (not wired yet).
+                    --rules              Also run rule-based verifiers (keywords, regex, counts, uniqueness, traceability).
                     --judge              Include LLM judging (not wired yet; requires API key).
                     --dry-run            Validate config + corpus, print summary, do not execute.
                     --json               Emit machine-readable JSON on stdout.

package/dist/eval/corpus.d.ts

@@ -17,3 +17,14 @@ export declare function fixturePathFor(projectRoot: string, caseEntry: EvalCase)
  * the case but not on disk — structural fixtures ship alongside cases.
  */
 export declare function readFixtureArtifact(projectRoot: string, caseEntry: EvalCase): Promise<string | undefined>;
+/**
+ * Resolve an entry from `extraFixtures` to an absolute filesystem path,
+ * relative to the case's stage directory (same convention as `fixture`).
+ */
+export declare function extraFixturePath(projectRoot: string, caseEntry: EvalCase, label: string): string | undefined;
+/**
+ * Read every declared extra fixture for a case into a `{ label → text }`
+ * map. Missing files throw so authoring mistakes surface immediately rather
+ * than being silently skipped by cross-artifact verifiers.
+ */
+export declare function readExtraFixtures(projectRoot: string, caseEntry: EvalCase): Promise<Record<string, string>>;

package/dist/eval/corpus.js

@@ -58,6 +58,128 @@ function parseStructural(filePath, raw) {
         structural.maxChars = maxChars;
     return structural;
 }
+function parseRegexRule(filePath, context, value) {
+    if (typeof value === "string") {
+        return { pattern: value };
+    }
+    if (!isRecord(value)) {
+        throw corpusError(filePath, `"${context}" entries must be either a string or a mapping with "pattern"`);
+    }
+    const pattern = value.pattern;
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        throw corpusError(filePath, `"${context}" mapping entry must include a non-empty "pattern" string`);
+    }
+    const flags = value.flags;
+    if (flags !== undefined && typeof flags !== "string") {
+        throw corpusError(filePath, `"${context}" flags must be a string`);
+    }
+    const description = value.description;
+    if (description !== undefined && typeof description !== "string") {
+        throw corpusError(filePath, `"${context}" description must be a string`);
+    }
+    const rule = { pattern };
+    if (flags !== undefined)
+        rule.flags = flags;
+    if (description !== undefined)
+        rule.description = description;
+    return rule;
+}
+function parseRegexRules(filePath, context, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw corpusError(filePath, `"${context}" must be an array`);
+    }
+    return value.map((entry, index) => parseRegexRule(filePath, `${context}[${index}]`, entry));
+}
+function parseOccurrenceBounds(filePath, context, value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value)) {
+        throw corpusError(filePath, `"${context}" must be a mapping of phrase → integer`);
+    }
+    const out = {};
+    for (const [phrase, count] of Object.entries(value)) {
+        if (typeof count !== "number" || !Number.isFinite(count) || !Number.isInteger(count) || count < 0) {
+            throw corpusError(filePath, `"${context}.${phrase}" must be a non-negative integer`);
+        }
+        out[phrase] = count;
+    }
+    return out;
+}
+function parseRules(filePath, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isRecord(raw)) {
+        throw corpusError(filePath, `"expected.rules" must be a mapping`);
+    }
+    const mustContain = readStringArray(filePath, "expected.rules.must_contain", raw.must_contain ?? raw.mustContain);
+    const mustNotContain = readStringArray(filePath, "expected.rules.must_not_contain", raw.must_not_contain ?? raw.mustNotContain);
+    const regexRequired = parseRegexRules(filePath, "expected.rules.regex_required", raw.regex_required ?? raw.regexRequired);
+    const regexForbidden = parseRegexRules(filePath, "expected.rules.regex_forbidden", raw.regex_forbidden ?? raw.regexForbidden);
+    const minOccurrences = parseOccurrenceBounds(filePath, "expected.rules.min_occurrences", raw.min_occurrences ?? raw.minOccurrences);
+    const maxOccurrences = parseOccurrenceBounds(filePath, "expected.rules.max_occurrences", raw.max_occurrences ?? raw.maxOccurrences);
+    const uniqueBulletsInSection = readStringArray(filePath, "expected.rules.unique_bullets_in_section", raw.unique_bullets_in_section ?? raw.uniqueBulletsInSection);
+    const rules = {};
+    if (mustContain)
+        rules.mustContain = mustContain;
+    if (mustNotContain)
+        rules.mustNotContain = mustNotContain;
+    if (regexRequired)
+        rules.regexRequired = regexRequired;
+    if (regexForbidden)
+        rules.regexForbidden = regexForbidden;
+    if (minOccurrences)
+        rules.minOccurrences = minOccurrences;
+    if (maxOccurrences)
+        rules.maxOccurrences = maxOccurrences;
+    if (uniqueBulletsInSection)
+        rules.uniqueBulletsInSection = uniqueBulletsInSection;
+    return Object.keys(rules).length === 0 ? undefined : rules;
+}
+function parseTraceability(filePath, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isRecord(raw)) {
+        throw corpusError(filePath, `"expected.traceability" must be a mapping`);
+    }
+    const idPattern = raw.id_pattern ?? raw.idPattern;
+    if (typeof idPattern !== "string" || idPattern.length === 0) {
+        throw corpusError(filePath, `"expected.traceability.id_pattern" must be a non-empty regex source`);
+    }
+    const idFlags = raw.id_flags ?? raw.idFlags;
+    if (idFlags !== undefined && typeof idFlags !== "string") {
+        throw corpusError(filePath, `"expected.traceability.id_flags" must be a string`);
+    }
+    const source = raw.source;
+    if (typeof source !== "string" || source.length === 0) {
+        throw corpusError(filePath, `"expected.traceability.source" must be "self" or an extra_fixtures label`);
+    }
+    const requireInRaw = raw.require_in ?? raw.requireIn;
+    const requireIn = readStringArray(filePath, "expected.traceability.require_in", requireInRaw);
+    if (!requireIn || requireIn.length === 0) {
+        throw corpusError(filePath, `"expected.traceability.require_in" must be a non-empty array`);
+    }
+    const out = { idPattern, source, requireIn };
+    if (idFlags !== undefined)
+        out.idFlags = idFlags;
+    return out;
+}
+function parseExtraFixtures(filePath, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isRecord(raw)) {
+        throw corpusError(filePath, `"extra_fixtures" must be a mapping of label → path`);
+    }
+    const out = {};
+    for (const [label, value] of Object.entries(raw)) {
+        if (typeof value !== "string" || value.length === 0) {
+            throw corpusError(filePath, `"extra_fixtures.${label}" must be a non-empty path string`);
+        }
+        out[label] = value;
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}
 function parseExpected(filePath, raw) {
     if (raw === undefined)
         return undefined;
@@ -68,12 +190,12 @@ function parseExpected(filePath, raw) {
     const structural = parseStructural(filePath, raw.structural);
     if (structural)
         shape.structural = structural;
-    if (raw.rules !== undefined) {
-        if (!isRecord(raw.rules)) {
-            throw corpusError(filePath, `"expected.rules" must be a mapping`);
-        }
-        shape.rules = raw.rules;
-    }
+    const rules = parseRules(filePath, raw.rules);
+    if (rules)
+        shape.rules = rules;
+    const traceability = parseTraceability(filePath, raw.traceability);
+    if (traceability)
+        shape.traceability = traceability;
     if (raw.judge !== undefined) {
         if (!isRecord(raw.judge)) {
             throw corpusError(filePath, `"expected.judge" must be a mapping`);
@@ -101,13 +223,15 @@ function validateCase(filePath, raw) {
     const contextFiles = readStringArray(filePath, "context_files", raw.context_files ?? raw.contextFiles);
     const expected = parseExpected(filePath, raw.expected);
     const fixture = typeof raw.fixture === "string" ? raw.fixture : undefined;
+    const extraFixtures = parseExtraFixtures(filePath, raw.extra_fixtures ?? raw.extraFixtures);
     return {
         id: id.trim(),
         stage: stageRaw,
         inputPrompt: inputPrompt.trim(),
         contextFiles,
         expected,
-        fixture
+        fixture,
+        extraFixtures
     };
 }
 /**
@@ -173,3 +297,34 @@ export async function readFixtureArtifact(projectRoot, caseEntry) {
     }
     return fs.readFile(fixturePath, "utf8");
 }
+/**
+ * Resolve an entry from `extraFixtures` to an absolute filesystem path,
+ * relative to the case's stage directory (same convention as `fixture`).
+ */
+export function extraFixturePath(projectRoot, caseEntry, label) {
+    const value = caseEntry.extraFixtures?.[label];
+    if (!value)
+        return undefined;
+    return path.resolve(projectRoot, EVALS_ROOT, "corpus", caseEntry.stage, value);
+}
+/**
+ * Read every declared extra fixture for a case into a `{ label → text }`
+ * map. Missing files throw so authoring mistakes surface immediately rather
+ * than being silently skipped by cross-artifact verifiers.
+ */
+export async function readExtraFixtures(projectRoot, caseEntry) {
+    const out = {};
+    if (!caseEntry.extraFixtures)
+        return out;
+    for (const label of Object.keys(caseEntry.extraFixtures)) {
+        const filePath = extraFixturePath(projectRoot, caseEntry, label);
+        if (!filePath)
+            continue;
+        if (!(await exists(filePath))) {
+            throw new Error(`Extra fixture missing for ${caseEntry.stage}/${caseEntry.id} ` +
+                `(label="${label}"): ${filePath}`);
+        }
+        out[label] = await fs.readFile(filePath, "utf8");
+    }
+    return out;
+}

package/dist/eval/runner.js

@@ -2,9 +2,11 @@ import { randomUUID } from "node:crypto";
 import { CCLAW_VERSION } from "../constants.js";
 import { FLOW_STAGES } from "../types.js";
 import { compareAgainstBaselines, loadBaselinesByStage } from "./baseline.js";
-import { loadCorpus, readFixtureArtifact } from "./corpus.js";
+import { loadCorpus, readExtraFixtures, readFixtureArtifact } from "./corpus.js";
 import { loadEvalConfig } from "./config-loader.js";
+import { verifyRules } from "./verifiers/rules.js";
 import { verifyStructural } from "./verifiers/structural.js";
+import { verifyTraceability } from "./verifiers/traceability.js";
 function groupByStage(cases) {
     return cases.reduce((acc, item) => {
         acc[item.stage] = (acc[item.stage] ?? 0) + 1;
@@ -21,33 +23,65 @@ function skeletonVerifierResult(message, details) {
         ...(details !== undefined ? { details } : {})
     };
 }
-async function runCaseStructural(projectRoot, caseEntry, plannedTier) {
+/**
+ * --schema-only narrows to structural. --rules opens up rules + traceability
+ * on top of structural (traceability is a rule-family verifier even though
+ * it lives in its own module). Default (no flag) matches --schema-only for
+ * backwards compatibility with the Step 1 gate.
+ */
+function resolveRunFlags(options) {
+    const rulesRequested = options.rules === true;
+    const schemaOnly = options.schemaOnly === true;
+    return {
+        runStructural: true,
+        runRules: rulesRequested && !schemaOnly,
+        runTraceability: rulesRequested && !schemaOnly
+    };
+}
+async function loadArtifactOrRecord(projectRoot, caseEntry, verifierResults) {
+    try {
+        return await readFixtureArtifact(projectRoot, caseEntry);
+    }
+    catch (err) {
+        verifierResults.push({
+            kind: "structural",
+            id: "structural:fixture:missing",
+            ok: false,
+            score: 0,
+            message: err instanceof Error ? err.message : String(err),
+            details: { fixture: caseEntry.fixture }
+        });
+        return undefined;
+    }
+}
+async function runCase(projectRoot, caseEntry, plannedTier, flags) {
     const started = Date.now();
-    const structuralExpected = caseEntry.expected?.structural;
     const verifierResults = [];
-    if (!structuralExpected || Object.keys(structuralExpected).length === 0) {
-        // No structural expectations declared — case is treated as "N/A" for this
-        // verifier kind; a placeholder pass keeps downstream math simple while
-        // making the situation visible in the report.
-        verifierResults.push(skeletonVerifierResult("No structural expectations declared for this case; structural verifier skipped.", { skipped: true }));
-    }
-    else {
-        let artifact;
-        try {
-            artifact = await readFixtureArtifact(projectRoot, caseEntry);
-        }
-        catch (err) {
+    const expected = caseEntry.expected;
+    const hasStructural = !!expected?.structural && Object.keys(expected.structural).length > 0;
+    const hasRules = flags.runRules && !!expected?.rules && Object.keys(expected.rules).length > 0;
+    const hasTraceability = flags.runTraceability && !!expected?.traceability;
+    const needsArtifact = hasStructural || hasRules || hasTraceability;
+    let artifact;
+    if (needsArtifact) {
+        artifact = await loadArtifactOrRecord(projectRoot, caseEntry, verifierResults);
+        if (artifact === undefined && verifierResults.length === 0) {
             verifierResults.push({
                 kind: "structural",
-                id: "structural:fixture:missing",
+                id: "structural:fixture:absent",
                 ok: false,
                 score: 0,
-                message: err instanceof Error ? err.message : String(err),
-                details: { fixture: caseEntry.fixture }
+                message: "Expectations declared but no fixture path provided. Add `fixture: ./<id>/fixture.md`.",
+                details: { fixtureProvided: false }
             });
         }
-        if (artifact !== undefined) {
-            const results = verifyStructural(artifact, structuralExpected);
+    }
+    if (flags.runStructural) {
+        if (!hasStructural) {
+            verifierResults.push(skeletonVerifierResult("No structural expectations declared for this case; structural verifier skipped.", { skipped: true }));
+        }
+        else if (artifact !== undefined) {
+            const results = verifyStructural(artifact, expected.structural);
             if (results.length === 0) {
                 verifierResults.push(skeletonVerifierResult("Structural expectations parsed but produced zero checks.", { skipped: true }));
             }
@@ -55,18 +89,32 @@ async function runCaseStructural(projectRoot, caseEntry, plannedTier) {
                 verifierResults.push(...results);
             }
         }
-        else if (verifierResults.length === 0) {
+    }
+    if (hasRules && artifact !== undefined) {
+        const results = verifyRules(artifact, expected.rules);
+        verifierResults.push(...results);
+    }
+    if (hasTraceability && artifact !== undefined) {
+        try {
+            const extras = await readExtraFixtures(projectRoot, caseEntry);
+            const results = verifyTraceability(artifact, extras, expected.traceability);
+            verifierResults.push(...results);
+        }
+        catch (err) {
             verifierResults.push({
-                kind: "structural",
-                id: "structural:fixture:absent",
+                kind: "rules",
+                id: "traceability:fixture:missing",
                 ok: false,
                 score: 0,
-                message: "Structural expectations declared but no fixture path provided. Add `fixture: ./<id>/fixture.md`.",
-                details: { fixtureProvided: false }
+                message: err instanceof Error ? err.message : String(err),
+                details: { extraFixtures: Object.keys(caseEntry.extraFixtures ?? {}) }
             });
         }
     }
-    const allOk = verifierResults.every((r) => r.ok);
+    const nonSkippedResults = verifierResults.filter((r) => r.details?.skipped !== true);
+    const allOk = nonSkippedResults.length === 0
+        ? verifierResults.every((r) => r.ok)
+        : nonSkippedResults.every((r) => r.ok);
     return {
         caseId: caseEntry.id,
         stage: caseEntry.stage,
@@ -125,12 +173,10 @@ export async function runEval(options) {
     if (corpus.length === 0) {
         notes.push("Corpus is empty. Seed cases live under `.cclaw/evals/corpus/<stage>/*.yaml`.");
     }
-    if (options.rules) {
-        notes.push("--rules is accepted; rule verifiers are not wired yet.");
-    }
     if (options.judge) {
         notes.push("--judge is accepted; LLM judging is not wired yet.");
     }
+    const flags = resolveRunFlags(options);
     if (options.dryRun === true) {
         const summary = {
             kind: "dry-run",
@@ -142,8 +188,8 @@ export async function runEval(options) {
             },
             plannedTier,
             verifiersAvailable: {
-                structural: true,
-                rules: false,
+                structural: flags.runStructural,
+                rules: flags.runRules,
                 judge: false,
                 workflow: false
             },
@@ -154,7 +200,7 @@ export async function runEval(options) {
     const now = new Date().toISOString();
     const caseResults = [];
     for (const item of corpus) {
-        caseResults.push(await runCaseStructural(options.projectRoot, item, plannedTier));
+        caseResults.push(await runCase(options.projectRoot, item, plannedTier, flags));
     }
     const stages = stagesInResults(caseResults);
     const baselines = await loadBaselinesByStage(options.projectRoot, stages);

package/dist/eval/types.d.ts

@@ -58,11 +58,69 @@ export interface StructuralExpected {
      */
     requiredFrontmatterKeys?: string[];
 }
-/** Superset of per-verifier expectation shapes. Only `structural` is wired in Step 1. */
+/**
+ * Rule-based expectations — zero-LLM content checks that are richer than
+ * structural (regex, numeric bounds, uniqueness). Introduced in Step 2.
+ *
+ * Every array field is optional; an empty `RulesExpected` produces zero
+ * verifier results so authors can enable rules incrementally.
+ */
+export interface RulesExpected {
+    /** Case-insensitive substrings the body must include at least once. */
+    mustContain?: string[];
+    /** Case-insensitive substrings the body must NOT include. */
+    mustNotContain?: string[];
+    /** Regex patterns that must match the body at least once. */
+    regexRequired?: RuleRegex[];
+    /** Regex patterns that must NOT match the body. */
+    regexForbidden?: RuleRegex[];
+    /** For each substring key, the body must contain at least N occurrences. */
+    minOccurrences?: Record<string, number>;
+    /** For each substring key, the body must contain at most N occurrences. */
+    maxOccurrences?: Record<string, number>;
+    /**
+     * For each named section (case-insensitive heading substring), every bullet
+     * (`- ...`) directly under the section must be unique. Catches duplicated
+     * decisions or repeated risks.
+     */
+    uniqueBulletsInSection?: string[];
+}
+export interface RuleRegex {
+    /** Source of the regex. Parsed with `new RegExp(pattern, flags)`. */
+    pattern: string;
+    /** Optional regex flags; defaults to `"i"` for case-insensitive matching. */
+    flags?: string;
+    /** Human-readable label rendered in verifier messages and slugged into the id. */
+    description?: string;
+}
+/**
+ * Cross-stage traceability expectations — assert every ID extracted from
+ * `source` also appears in `self` and/or named `extra_fixtures`. Introduced
+ * in Step 2.
+ */
+export interface TraceabilityExpected {
+    /** Regex applied to the `source` fixture to collect the authoritative ID set. */
+    idPattern: string;
+    /** Optional regex flags (defaults to `"g"`). */
+    idFlags?: string;
+    /**
+     * Where to read the authoritative ID set from. Either `"self"` (the case's
+     * primary `fixture`) or a label present in the case's `extraFixtures` map.
+     */
+    source: string;
+    /**
+     * Where every source ID must also appear. Each entry is `"self"` or an
+     * `extraFixtures` label. Order is preserved for deterministic result ids.
+     */
+    requireIn: string[];
+}
+/** Superset of per-verifier expectation shapes. */
 export interface ExpectedShape {
     structural?: StructuralExpected;
-    /** Rule-based (keyword/regex/traceability) checks — Step 2. */
-    rules?: Record<string, unknown>;
+    /** Rule-based (keyword/regex/count/uniqueness) checks — Step 2. */
+    rules?: RulesExpected;
+    /** Cross-stage ID propagation checks — Step 2. */
+    traceability?: TraceabilityExpected;
     /** LLM-judge rubrics — Step 3. */
     judge?: Record<string, unknown>;
 }
@@ -89,6 +147,13 @@ export interface EvalCase {
      * Step 1 development aid.
      */
     fixture?: string;
+    /**
+     * Additional fixture paths loaded alongside the primary `fixture`, keyed
+     * by a free-form label. Consumed by cross-artifact verifiers (e.g.,
+     * traceability) introduced in Step 2. Paths are resolved relative to the
+     * case's stage directory, just like `fixture`.
+     */
+    extraFixtures?: Record<string, string>;
 }
 /** Result of one verifier applied to one case. */
 export interface VerifierResult {

package/dist/eval/verifiers/rules.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Rule-based verifier: deterministic, zero-LLM checks that are richer than
+ * structural heading/length assertions. Each rule produces exactly one
+ * `VerifierResult` so baselines diff at the check level, and authoring a
+ * rule sideways in YAML never silently skips.
+ *
+ * Semantics:
+ *
+ * - All substring matching is case-insensitive. Regex matching uses the
+ *   flags declared on the rule (default `"i"`).
+ * - Rules operate on the artifact BODY (frontmatter stripped), mirroring
+ *   the structural verifier so min/max counts and length checks agree on
+ *   what "body" means.
+ * - `uniqueBulletsInSection` scans every section (heading, case-insensitive
+ *   substring match) and flags duplicate top-level bullets ("- item"). The
+ *   search stops at the next heading of equal or lower depth.
+ */
+import type { RulesExpected, VerifierResult } from "../types.js";
+/**
+ * Run every configured rule check against the artifact body. Returns `[]`
+ * when `expected` is undefined or empty so the runner can distinguish
+ * "no rules declared" from "all rules passed".
+ */
+export declare function verifyRules(artifact: string, expected: RulesExpected | undefined): VerifierResult[];

package/dist/eval/verifiers/rules.js

@@ -0,0 +1,218 @@
+import { splitFrontmatter } from "./structural.js";
+function slugify(input) {
+    return (input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/(^-|-$)/g, "")
+        .slice(0, 64) || "rule");
+}
+function result(id, ok, message, details) {
+    return {
+        kind: "rules",
+        id,
+        ok,
+        score: ok ? 1 : 0,
+        message,
+        ...(details !== undefined ? { details } : {})
+    };
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let index = 0;
+    let count = 0;
+    while (true) {
+        const at = haystack.indexOf(needle, index);
+        if (at < 0)
+            return count;
+        count += 1;
+        index = at + needle.length;
+    }
+}
+function compileRegex(rule) {
+    const flags = rule.flags ?? "i";
+    try {
+        return new RegExp(rule.pattern, flags);
+    }
+    catch (err) {
+        throw new Error(`Invalid regex for rule "${rule.description ?? rule.pattern}" ` +
+            `(pattern=${JSON.stringify(rule.pattern)}, flags=${JSON.stringify(flags)}): ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+}
+function ruleLabel(rule) {
+    return rule.description?.trim() || rule.pattern;
+}
+function checkMustContain(needles, body) {
+    const bodyLower = body.toLowerCase();
+    return needles.map((needle) => {
+        const found = bodyLower.includes(needle.toLowerCase());
+        return result(`rules:contains:${slugify(needle)}`, found, found
+            ? `Required phrase "${needle}" present.`
+            : `Required phrase "${needle}" missing from body.`, { phrase: needle });
+    });
+}
+function checkMustNotContain(needles, body) {
+    const bodyLower = body.toLowerCase();
+    return needles.map((needle) => {
+        const lowered = needle.toLowerCase();
+        const occurrences = countOccurrences(bodyLower, lowered);
+        const ok = occurrences === 0;
+        return result(`rules:not-contains:${slugify(needle)}`, ok, ok
+            ? `Forbidden phrase "${needle}" absent (as required).`
+            : `Forbidden phrase "${needle}" appears ${occurrences} time(s).`, { phrase: needle, occurrences });
+    });
+}
+function checkRegexRequired(rules, body) {
+    return rules.map((rule) => {
+        const label = ruleLabel(rule);
+        const regex = compileRegex(rule);
+        const matches = body.match(new RegExp(regex.source, withGlobal(regex.flags)));
+        const count = matches ? matches.length : 0;
+        const ok = count > 0;
+        return result(`rules:regex-required:${slugify(label)}`, ok, ok
+            ? `Required pattern /${rule.pattern}/ matched ${count} time(s).`
+            : `Required pattern /${rule.pattern}/ did not match.`, { pattern: rule.pattern, flags: rule.flags ?? "i", matches: count });
+    });
+}
+function checkRegexForbidden(rules, body) {
+    return rules.map((rule) => {
+        const label = ruleLabel(rule);
+        const regex = compileRegex(rule);
+        const matches = body.match(new RegExp(regex.source, withGlobal(regex.flags)));
+        const count = matches ? matches.length : 0;
+        const ok = count === 0;
+        return result(`rules:regex-forbidden:${slugify(label)}`, ok, ok
+            ? `Forbidden pattern /${rule.pattern}/ absent.`
+            : `Forbidden pattern /${rule.pattern}/ matched ${count} time(s).`, { pattern: rule.pattern, flags: rule.flags ?? "i", matches: count });
+    });
+}
+function withGlobal(flags) {
+    return flags.includes("g") ? flags : `${flags}g`;
+}
+function checkMinOccurrences(bounds, body) {
+    const bodyLower = body.toLowerCase();
+    return Object.entries(bounds).map(([needle, min]) => {
+        const occurrences = countOccurrences(bodyLower, needle.toLowerCase());
+        const ok = occurrences >= min;
+        return result(`rules:min-occurrences:${slugify(needle)}`, ok, ok
+            ? `Phrase "${needle}" appears ${occurrences} time(s) (>= ${min}).`
+            : `Phrase "${needle}" appears ${occurrences} time(s); expected at least ${min}.`, { phrase: needle, occurrences, min });
+    });
+}
+function checkMaxOccurrences(bounds, body) {
+    const bodyLower = body.toLowerCase();
+    return Object.entries(bounds).map(([needle, max]) => {
+        const occurrences = countOccurrences(bodyLower, needle.toLowerCase());
+        const ok = occurrences <= max;
+        return result(`rules:max-occurrences:${slugify(needle)}`, ok, ok
+            ? `Phrase "${needle}" appears ${occurrences} time(s) (<= ${max}).`
+            : `Phrase "${needle}" appears ${occurrences} time(s); expected at most ${max}.`, { phrase: needle, occurrences, max });
+    });
+}
+function sliceBySection(body) {
+    const lines = body.split(/\r?\n/);
+    const slices = [];
+    let current = null;
+    for (const rawLine of lines) {
+        const line = rawLine.trimStart();
+        const match = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+        if (match) {
+            if (current) {
+                slices.push({
+                    heading: current.heading,
+                    depth: current.depth,
+                    body: current.body.join("\n")
+                });
+            }
+            current = { heading: match[2].trim(), depth: match[1].length, body: [] };
+        }
+        else if (current) {
+            current.body.push(rawLine);
+        }
+    }
+    if (current) {
+        slices.push({
+            heading: current.heading,
+            depth: current.depth,
+            body: current.body.join("\n")
+        });
+    }
+    return slices;
+}
+function extractTopLevelBullets(sectionBody) {
+    const bullets = [];
+    for (const rawLine of sectionBody.split(/\r?\n/)) {
+        const line = rawLine.replace(/\s+$/, "");
+        const leading = line.match(/^(\s*)[-*]\s+(.+)$/);
+        if (!leading)
+            continue;
+        if (leading[1].length > 0)
+            continue;
+        bullets.push(leading[2].trim());
+    }
+    return bullets;
+}
+function checkUniqueBulletsInSection(sections, body) {
+    const slices = sliceBySection(body);
+    return sections.map((needle) => {
+        const lowerNeedle = needle.toLowerCase();
+        const slice = slices.find((s) => s.heading.toLowerCase().includes(lowerNeedle));
+        if (!slice) {
+            return result(`rules:unique-in-section:${slugify(needle)}`, false, `Section matching "${needle}" not found; cannot check uniqueness.`, { section: needle, found: false });
+        }
+        const bullets = extractTopLevelBullets(slice.body);
+        const seen = new Map();
+        for (const bullet of bullets) {
+            const key = bullet.toLowerCase();
+            seen.set(key, (seen.get(key) ?? 0) + 1);
+        }
+        const duplicates = [...seen.entries()]
+            .filter(([, count]) => count > 1)
+            .map(([entry, count]) => ({ entry, count }));
+        const ok = duplicates.length === 0;
+        return result(`rules:unique-in-section:${slugify(needle)}`, ok, ok
+            ? `Section "${slice.heading}" has ${bullets.length} unique bullet(s).`
+            : `Section "${slice.heading}" has duplicate bullet(s): ${duplicates
+                .map((d) => `"${d.entry}" x${d.count}`)
+                .join(", ")}.`, {
+            section: slice.heading,
+            bullets: bullets.length,
+            duplicates
+        });
+    });
+}
+/**
+ * Run every configured rule check against the artifact body. Returns `[]`
+ * when `expected` is undefined or empty so the runner can distinguish
+ * "no rules declared" from "all rules passed".
+ */
+export function verifyRules(artifact, expected) {
+    if (!expected)
+        return [];
+    const split = splitFrontmatter(artifact);
+    const body = split.body;
+    const results = [];
+    if (expected.mustContain?.length) {
+        results.push(...checkMustContain(expected.mustContain, body));
+    }
+    if (expected.mustNotContain?.length) {
+        results.push(...checkMustNotContain(expected.mustNotContain, body));
+    }
+    if (expected.regexRequired?.length) {
+        results.push(...checkRegexRequired(expected.regexRequired, body));
+    }
+    if (expected.regexForbidden?.length) {
+        results.push(...checkRegexForbidden(expected.regexForbidden, body));
+    }
+    if (expected.minOccurrences && Object.keys(expected.minOccurrences).length) {
+        results.push(...checkMinOccurrences(expected.minOccurrences, body));
+    }
+    if (expected.maxOccurrences && Object.keys(expected.maxOccurrences).length) {
+        results.push(...checkMaxOccurrences(expected.maxOccurrences, body));
+    }
+    if (expected.uniqueBulletsInSection?.length) {
+        results.push(...checkUniqueBulletsInSection(expected.uniqueBulletsInSection, body));
+    }
+    return results;
+}

package/dist/eval/verifiers/traceability.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cross-stage traceability verifier: extract a set of IDs from a source
+ * fixture (e.g. `D-\d+` decisions declared during scope) and assert every
+ * ID appears in the artifact-under-test and/or in other linked fixtures.
+ *
+ * The verifier is intentionally source-agnostic: the caller passes the
+ * primary artifact plus a label → text map for any extra fixtures declared
+ * on the case. `source` and entries in `requireIn` are either the string
+ * `"self"` (the primary artifact) or labels present in the extras map.
+ *
+ * Result ids follow `traceability:<source>->:<target>:<reason>` so baselines
+ * diff at the per-link granularity. A missing link produces one result with
+ * a list of missing IDs in its `details` payload.
+ */
+import type { TraceabilityExpected, VerifierResult } from "../types.js";
+export declare const SELF_LABEL = "self";
+/**
+ * Run traceability checks. Returns `[]` when expectations are undefined.
+ * Emits a single "source-missing" result when the declared source fixture
+ * has zero IDs (authoring error), and one result per `requireIn` target
+ * listing any IDs absent in that fixture.
+ */
+export declare function verifyTraceability(primaryArtifact: string, extraFixtures: Record<string, string>, expected: TraceabilityExpected | undefined): VerifierResult[];

package/dist/eval/verifiers/traceability.js

@@ -0,0 +1,84 @@
+import { splitFrontmatter } from "./structural.js";
+export const SELF_LABEL = "self";
+function result(id, ok, message, details) {
+    return {
+        kind: "rules",
+        id,
+        ok,
+        score: ok ? 1 : 0,
+        message,
+        ...(details !== undefined ? { details } : {})
+    };
+}
+function compileIdRegex(expected) {
+    const flags = expected.idFlags ?? "g";
+    const normalized = flags.includes("g") ? flags : `${flags}g`;
+    try {
+        return new RegExp(expected.idPattern, normalized);
+    }
+    catch (err) {
+        throw new Error(`Invalid traceability id_pattern ${JSON.stringify(expected.idPattern)} ` +
+            `(flags=${JSON.stringify(normalized)}): ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+}
+function bodyOf(text) {
+    return splitFrontmatter(text).body;
+}
+function extractIds(text, regex) {
+    const body = bodyOf(text);
+    const found = new Set();
+    for (const match of body.matchAll(regex)) {
+        found.add(match[0]);
+    }
+    return [...found].sort();
+}
+function resolveFixture(label, primary, extraFixtures) {
+    if (label === SELF_LABEL)
+        return primary;
+    return extraFixtures[label];
+}
+/**
+ * Run traceability checks. Returns `[]` when expectations are undefined.
+ * Emits a single "source-missing" result when the declared source fixture
+ * has zero IDs (authoring error), and one result per `requireIn` target
+ * listing any IDs absent in that fixture.
+ */
+export function verifyTraceability(primaryArtifact, extraFixtures, expected) {
+    if (!expected)
+        return [];
+    const regex = compileIdRegex(expected);
+    const sourceText = resolveFixture(expected.source, primaryArtifact, extraFixtures);
+    if (sourceText === undefined) {
+        return [
+            result(`traceability:source:${expected.source}:missing`, false, `Traceability source fixture "${expected.source}" not loaded.`, { source: expected.source })
+        ];
+    }
+    const sourceIds = extractIds(sourceText, regex);
+    if (sourceIds.length === 0) {
+        return [
+            result(`traceability:source:${expected.source}:empty`, false, `Source "${expected.source}" yielded zero ids for pattern /${expected.idPattern}/.`, { source: expected.source, pattern: expected.idPattern })
+        ];
+    }
+    const results = [];
+    for (const target of expected.requireIn) {
+        const targetText = resolveFixture(target, primaryArtifact, extraFixtures);
+        if (targetText === undefined) {
+            results.push(result(`traceability:target:${target}:missing`, false, `Traceability target fixture "${target}" not loaded.`, { target }));
+            continue;
+        }
+        const targetBody = bodyOf(targetText);
+        const missing = sourceIds.filter((id) => !targetBody.includes(id));
+        const ok = missing.length === 0;
+        results.push(result(`traceability:${expected.source}->${target}`, ok, ok
+            ? `Every id (${sourceIds.length}) from "${expected.source}" appears in "${target}".`
+            : `Target "${target}" is missing ${missing.length}/${sourceIds.length} id(s): ${missing.join(", ")}.`, {
+            source: expected.source,
+            target,
+            sourceIds,
+            missing,
+            pattern: expected.idPattern
+        }));
+    }
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {