@oscharko-dev/keiko-workflows 0.2.0

package/dist/qualityIntelligence/scopedRegeneration.js

@@ -0,0 +1,35 @@
+// Scoped regeneration entry (Epic #735, Issue #743).
+//
+// Invokes the existing model-routed test-design workflow with a NARROWED set of ingested atoms
+// — only atoms belonging to stale candidates — and a fresh runId. Does NOT re-implement the
+// workflow; composes runQualityIntelligenceModelRoutedTestDesign unchanged.
+import { QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
+import { runQualityIntelligenceModelRoutedTestDesign } from "./modelRoutedTestDesign.js";
+const PLAN_STAGES = Object.freeze([
+    { name: "plan", descriptor: "qi:plan" },
+    { name: "candidates", descriptor: "qi:model-generate" },
+    { name: "judge", descriptor: "qi:judge" },
+    { name: "coverage", descriptor: "qi:coverage" },
+    { name: "validate", descriptor: "qi:validate" },
+    { name: "finalize", descriptor: "qi:finalize" },
+]);
+/**
+ * Run the model-routed test-design workflow scoped to a narrowed set of atoms. Returns the full run
+ * summary plus a count of narrowed atoms for caller bookkeeping. The caller is responsible for
+ * merging the regenerated candidates with preserved-fresh candidates from the original run.
+ */
+export async function runScopedRegeneration(input, deps) {
+    const plan = {
+        id: QI.asQualityIntelligenceRunId(input.newRunId),
+        requestedAt: input.requestedAt,
+        plannerKind: "model-routed",
+        stages: PLAN_STAGES,
+    };
+    const summary = await runQualityIntelligenceModelRoutedTestDesign({
+        plan,
+        envelopes: input.envelopes,
+        ingestedAtoms: input.ingestedAtoms,
+        provenanceRefs: input.provenanceRefs,
+    }, deps);
+    return { summary, narrowedAtomCount: input.ingestedAtoms.length };
+}

package/dist/ranking/filter.d.ts

@@ -0,0 +1,20 @@
+import type { CandidateFile, OmittedContextEntry } from "@oscharko-dev/keiko-contracts/connected-context";
+export interface AnnotatedCandidate {
+    readonly candidate: CandidateFile;
+    readonly generatedHint: boolean;
+    readonly duplicate: boolean;
+}
+export interface FilterOptions {
+    readonly minScore: number;
+    readonly maxKept: number;
+    readonly omitGenerated: boolean;
+    readonly omitNearDuplicates: boolean;
+    readonly nowMs: () => number;
+}
+export declare const DEFAULT_FILTER_OPTIONS: Omit<FilterOptions, "nowMs">;
+export interface FilterResult {
+    readonly kept: readonly CandidateFile[];
+    readonly omitted: readonly OmittedContextEntry[];
+}
+export declare function filterCandidates(entries: readonly AnnotatedCandidate[], options: FilterOptions): FilterResult;
+//# sourceMappingURL=filter.d.ts.map

package/dist/ranking/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/ranking/filter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACpB,MAAM,iDAAiD,CAAC;AAKzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,sBAAsB,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAKtD,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAClD;AAiGD,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,OAAO,EAAE,aAAa,GACrB,YAAY,CAmBd"}

package/dist/ranking/filter.js

@@ -0,0 +1,99 @@
+// Negative-context filter for the ranker (Epic #177, Issue #182). Converts annotated
+// candidates into a kept/omitted partition with explicit CandidateOmissionReason values.
+// Priority is fixed (pre-set reason > generated > low-relevance > duplicate); a hard maxKept
+// cap demotes the overflow to "budget-exhausted". Determinism: ties break on scopePath asc.
+export const DEFAULT_FILTER_OPTIONS = {
+    minScore: 0.15,
+    maxKept: 50,
+    omitGenerated: true,
+    omitNearDuplicates: true,
+};
+function classifyReason(entry, options) {
+    const preset = entry.candidate.omitted;
+    if (preset !== undefined) {
+        return preset;
+    }
+    if (entry.generatedHint && options.omitGenerated) {
+        return "generated";
+    }
+    if (entry.candidate.score < options.minScore) {
+        return "low-relevance";
+    }
+    if (entry.duplicate && options.omitNearDuplicates) {
+        return "near-duplicate";
+    }
+    return undefined;
+}
+function compareKept(a, b) {
+    if (b.score !== a.score) {
+        return b.score - a.score;
+    }
+    if (a.scopePath < b.scopePath) {
+        return -1;
+    }
+    if (a.scopePath > b.scopePath) {
+        return 1;
+    }
+    return 0;
+}
+function compareOmitted(a, b) {
+    if (a.scopePath < b.scopePath) {
+        return -1;
+    }
+    if (a.scopePath > b.scopePath) {
+        return 1;
+    }
+    return 0;
+}
+function toOmittedEntry(scopePath, reason, nowMs) {
+    return { scopePath, reason, omittedAtMs: nowMs };
+}
+function partition(entries, options, nowMs) {
+    const kept = [];
+    const lowRelevance = [];
+    const omittedEntries = [];
+    for (const entry of entries) {
+        const reason = classifyReason(entry, options);
+        if (reason === undefined) {
+            kept.push(entry.candidate);
+        }
+        else if (reason === "low-relevance") {
+            lowRelevance.push(entry.candidate);
+        }
+        else {
+            omittedEntries.push(toOmittedEntry(entry.candidate.scopePath, reason, nowMs));
+        }
+    }
+    return { kept, lowRelevance, omittedEntries };
+}
+function normalizeMaxKept(maxKept) {
+    if (!Number.isFinite(maxKept)) {
+        return 0;
+    }
+    return Math.max(0, Math.floor(maxKept));
+}
+function appendLowRelevanceOmissions(omittedEntries, candidates, nowMs) {
+    for (const candidate of candidates) {
+        omittedEntries.push(toOmittedEntry(candidate.scopePath, "low-relevance", nowMs));
+    }
+}
+export function filterCandidates(entries, options) {
+    const nowMs = options.nowMs();
+    const { kept, lowRelevance, omittedEntries } = partition(entries, options, nowMs);
+    const maxKept = normalizeMaxKept(options.maxKept);
+    lowRelevance.sort(compareKept);
+    if (kept.length === 0 && maxKept > 0) {
+        const fallback = lowRelevance.shift();
+        if (fallback !== undefined) {
+            kept.push(fallback);
+        }
+    }
+    appendLowRelevanceOmissions(omittedEntries, lowRelevance, nowMs);
+    kept.sort(compareKept);
+    const overflow = kept.splice(maxKept);
+    for (const overflowed of overflow) {
+        omittedEntries.push(toOmittedEntry(overflowed.scopePath, "budget-exhausted", nowMs));
+    }
+    omittedEntries.sort(compareOmitted);
+    return { kept, omitted: omittedEntries };
+}

package/dist/ranking/index.d.ts

@@ -0,0 +1,9 @@
+export type { ExtractedSignals, RankingHints, RankingInput } from "./signals.js";
+export { DEFAULT_GENERATED_PATTERNS, extractSignals } from "./signals.js";
+export type { ScoringWeights } from "./scoring.js";
+export { DEFAULT_SCORING_WEIGHTS, computeScore } from "./scoring.js";
+export type { AnnotatedCandidate, FilterOptions, FilterResult } from "./filter.js";
+export { DEFAULT_FILTER_OPTIONS, filterCandidates } from "./filter.js";
+export type { RankingDiagnostics, RankingOptions, RankingResult } from "./rank.js";
+export { rankCandidates } from "./rank.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ranking/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ranking/index.ts"],"names":[],"mappings":"AAKA,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE1E,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAErE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEvE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/ranking/index.js

@@ -0,0 +1,8 @@
+// Public sub-barrel for deterministic hybrid candidate ranking and negative context
+// filtering (Epic #177, Issue #182). External consumers import every ranking symbol
+// through this module; internal modules (signals.ts, scoring.ts, filter.ts, rank.ts)
+// remain implementation detail.
+export { DEFAULT_GENERATED_PATTERNS, extractSignals } from "./signals.js";
+export { DEFAULT_SCORING_WEIGHTS, computeScore } from "./scoring.js";
+export { DEFAULT_FILTER_OPTIONS, filterCandidates } from "./filter.js";
+export { rankCandidates } from "./rank.js";

package/dist/ranking/rank.d.ts

@@ -0,0 +1,21 @@
+import { type CandidateOmissionReason } from "@oscharko-dev/keiko-contracts/connected-context";
+import { type FilterOptions, type FilterResult } from "./filter.js";
+import { type ScoringWeights } from "./scoring.js";
+import { type RankingInput } from "./signals.js";
+export interface RankingOptions {
+    readonly weights?: ScoringWeights;
+    readonly filter?: Omit<FilterOptions, "nowMs">;
+    readonly nowMs?: () => number;
+}
+export interface RankingDiagnostics {
+    readonly totalAtoms: number;
+    readonly uniqueCandidates: number;
+    readonly keptCount: number;
+    readonly omittedCounts: Readonly<Record<CandidateOmissionReason, number>>;
+    readonly elapsedMs: number;
+}
+export interface RankingResult extends FilterResult {
+    readonly diagnostics: RankingDiagnostics;
+}
+export declare function rankCandidates(input: RankingInput, options?: RankingOptions): RankingResult;
+//# sourceMappingURL=rank.d.ts.map

package/dist/ranking/rank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.d.ts","sourceRoot":"","sources":["../../src/ranking/rank.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,uBAAuB,EAG7B,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAyC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;CAC1C;AA+JD,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CAyB/F"}

package/dist/ranking/rank.js

@@ -0,0 +1,160 @@
+// Public facade for candidate ranking and negative-context filtering (Epic #177, Issue #182).
+// Pure composition of signals → scoring → filter. Validates scopePath via the contracts'
+// isValidScopePath (defense-in-depth) and accounts every CANDIDATE_OMISSION_REASONS key in
+// the returned diagnostics so UI/audit consumers can render zeros without conditionals.
+import { CANDIDATE_OMISSION_REASONS, isValidScopePath, } from "@oscharko-dev/keiko-contracts/connected-context";
+import { DEFAULT_FILTER_OPTIONS, filterCandidates, } from "./filter.js";
+import { DEFAULT_SCORING_WEIGHTS, computeScore } from "./scoring.js";
+import { DEFAULT_GENERATED_PATTERNS, extractSignals, } from "./signals.js";
+const AUTO_DUPLICATE_CLUSTER_MIN = 3;
+const AUTO_DUPLICATE_BASENAME_EXEMPTIONS = new Set([
+    "agents.md",
+    "package.json",
+    "readme.md",
+    "tsconfig.json",
+]);
+function resolveHints(hints) {
+    return {
+        generatedPathPatterns: hints?.generatedPathPatterns ?? DEFAULT_GENERATED_PATTERNS,
+        duplicateOf: hints?.duplicateOf ?? new Map(),
+    };
+}
+function resolveFilterOptions(filter, nowMs) {
+    const base = filter ?? DEFAULT_FILTER_OPTIONS;
+    return {
+        minScore: base.minScore,
+        maxKept: base.maxKept,
+        omitGenerated: base.omitGenerated,
+        omitNearDuplicates: base.omitNearDuplicates,
+        nowMs,
+    };
+}
+function groupAtomsByPath(atoms) {
+    const valid = new Map();
+    const invalidPaths = new Set();
+    for (const candidate of atoms) {
+        if (!isValidScopePath(candidate.scopePath, { mustBeRelative: true })) {
+            invalidPaths.add(candidate.scopePath);
+            continue;
+        }
+        const existing = valid.get(candidate.scopePath);
+        if (existing === undefined) {
+            valid.set(candidate.scopePath, [candidate]);
+        }
+        else {
+            existing.push(candidate);
+        }
+    }
+    return { valid, invalidPaths: [...invalidPaths] };
+}
+function basename(scopePath) {
+    const index = scopePath.lastIndexOf("/");
+    return index >= 0 ? scopePath.slice(index + 1) : scopePath;
+}
+function bestAtomScore(atoms) {
+    return atoms.reduce((best, atom) => Math.max(best, atom.score), 0);
+}
+function compareCanonicalCandidate(a, b) {
+    const scoreDelta = bestAtomScore(b[1]) - bestAtomScore(a[1]);
+    if (scoreDelta !== 0) {
+        return scoreDelta;
+    }
+    if (a[0].length !== b[0].length) {
+        return a[0].length - b[0].length;
+    }
+    return a[0].localeCompare(b[0]);
+}
+function deriveDuplicateHints(group, explicit) {
+    const derived = new Map(explicit);
+    const clusters = new Map();
+    for (const entry of group.entries()) {
+        const [scopePath] = entry;
+        if (derived.has(scopePath)) {
+            continue;
+        }
+        const key = basename(scopePath).toLowerCase();
+        if (AUTO_DUPLICATE_BASENAME_EXEMPTIONS.has(key)) {
+            continue;
+        }
+        const existing = clusters.get(key);
+        if (existing === undefined) {
+            clusters.set(key, [entry]);
+        }
+        else {
+            existing.push(entry);
+        }
+    }
+    for (const entries of clusters.values()) {
+        if (entries.length < AUTO_DUPLICATE_CLUSTER_MIN) {
+            continue;
+        }
+        const [canonical, ...duplicates] = [...entries].sort(compareCanonicalCandidate);
+        if (canonical === undefined) {
+            continue;
+        }
+        for (const [scopePath] of duplicates) {
+            derived.set(scopePath, canonical[0]);
+        }
+    }
+    return derived;
+}
+function buildAnnotated(group, input, hints, weights) {
+    const annotated = [];
+    for (const [scopePath, atomsForPath] of group) {
+        const signals = extractSignals(atomsForPath, input.anchors, hints);
+        const score = computeScore(signals, weights);
+        const candidate = {
+            scopePath,
+            score,
+            signals: signals.signals,
+            omitted: undefined,
+        };
+        annotated.push({
+            candidate,
+            generatedHint: signals.generatedHint,
+            duplicate: hints.duplicateOf.has(scopePath),
+        });
+    }
+    return annotated;
+}
+function emptyOmittedCounts() {
+    const counts = {};
+    for (const reason of CANDIDATE_OMISSION_REASONS) {
+        counts[reason] = 0;
+    }
+    return counts;
+}
+function tallyOmittedCounts(omitted, outsideScopeCount) {
+    const counts = emptyOmittedCounts();
+    for (const entry of omitted) {
+        counts[entry.reason] += 1;
+    }
+    counts["outside-scope"] += outsideScopeCount;
+    return counts;
+}
+export function rankCandidates(input, options = {}) {
+    const clock = options.nowMs ?? Date.now;
+    // Capture a single emission timestamp so every OmittedContextEntry created by this call carries
+    // the same omittedAtMs. The end-of-run clock read below measures elapsed time only.
+    const startMs = clock();
+    const frozenStartMs = () => startMs;
+    const hints = resolveHints(input.hints);
+    const weights = options.weights ?? DEFAULT_SCORING_WEIGHTS;
+    const { valid, invalidPaths } = groupAtomsByPath(input.atoms);
+    const rankingHints = { ...hints, duplicateOf: deriveDuplicateHints(valid, hints.duplicateOf) };
+    const annotated = buildAnnotated(valid, input, rankingHints, weights);
+    const filterOptions = resolveFilterOptions(options.filter, frozenStartMs);
+    const filterResult = filterCandidates(annotated, filterOptions);
+    // Invalid paths cannot be represented as OmittedContextEntry values without breaking
+    // ConnectedContextPack validation, so keep them diagnostics-only.
+    const omittedCounts = tallyOmittedCounts(filterResult.omitted, invalidPaths.length);
+    const elapsedMs = Math.max(0, clock() - startMs);
+    const diagnostics = {
+        totalAtoms: input.atoms.length,
+        uniqueCandidates: valid.size,
+        keptCount: filterResult.kept.length,
+        omittedCounts,
+        elapsedMs,
+    };
+    return { kept: filterResult.kept, omitted: filterResult.omitted, diagnostics };
+}

package/dist/ranking/scoring.d.ts

@@ -0,0 +1,13 @@
+import type { ExtractedSignals } from "./signals.js";
+export interface ScoringWeights {
+    readonly provenanceBestScore: number;
+    readonly provenanceCount: number;
+    readonly anchorOverlap: number;
+    readonly pathDepthAffinity: number;
+    readonly testPairBonus: number;
+    readonly stacktracePositionBonus: number;
+    readonly generatedPenalty: number;
+}
+export declare const DEFAULT_SCORING_WEIGHTS: ScoringWeights;
+export declare function computeScore(signals: ExtractedSignals, weights?: ScoringWeights): number;
+//# sourceMappingURL=scoring.d.ts.map

package/dist/ranking/scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../../src/ranking/scoring.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,eAAO,MAAM,uBAAuB,EAAE,cAQ5B,CAAC;AAgBX,wBAAgB,YAAY,CAC1B,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,cAAwC,GAChD,MAAM,CAUR"}

package/dist/ranking/scoring.js

@@ -0,0 +1,39 @@
+// Weighted scoring composition for ranked candidates (Epic #177, Issue #182).
+// Pure function: signal vector × weight vector → clamped unit score. The default positive
+// weights sum to 0.95 and the generated penalty weight is 0.30; the filter layer's
+// `omitGenerated` default keeps generated files OUT of the kept set regardless of score,
+// so the scoring penalty is a secondary defence (a fully-positive generated file scores
+// 0.65). Callers may override weights to tune ring-specific behaviour; never uses
+// parseFloat or .toFixed.
+export const DEFAULT_SCORING_WEIGHTS = {
+    provenanceBestScore: 0.35,
+    provenanceCount: 0.1,
+    anchorOverlap: 0.25,
+    pathDepthAffinity: 0.1,
+    testPairBonus: 0.1,
+    stacktracePositionBonus: 0.05,
+    generatedPenalty: 0.3,
+};
+const SIGNAL_WEIGHT_KEYS = {
+    "provenance-best-score": "provenanceBestScore",
+    "provenance-count": "provenanceCount",
+    "anchor-overlap": "anchorOverlap",
+    "path-depth-affinity": "pathDepthAffinity",
+    "test-pair-bonus": "testPairBonus",
+    "stacktrace-position-bonus": "stacktracePositionBonus",
+    "generated-penalty": "generatedPenalty",
+};
+function clampUnit(value) {
+    return Math.max(0, Math.min(1, value));
+}
+export function computeScore(signals, weights = DEFAULT_SCORING_WEIGHTS) {
+    let raw = 0;
+    for (const signal of signals.signals) {
+        const key = SIGNAL_WEIGHT_KEYS[signal.name];
+        if (key === undefined) {
+            continue;
+        }
+        raw += signal.value * weights[key];
+    }
+    return clampUnit(raw);
+}

package/dist/ranking/signals.d.ts

@@ -0,0 +1,20 @@
+import type { CandidateSignal, EvidenceAtom } from "@oscharko-dev/keiko-contracts/connected-context";
+import type { SearchAnchor } from "../planner/index.js";
+export interface RankingInput {
+    readonly atoms: readonly EvidenceAtom[];
+    readonly anchors: readonly SearchAnchor[];
+    readonly hints?: RankingHints;
+}
+export interface RankingHints {
+    readonly generatedPathPatterns?: readonly string[];
+    readonly duplicateOf?: ReadonlyMap<string, string>;
+}
+export declare const DEFAULT_GENERATED_PATTERNS: readonly string[];
+export interface ExtractedSignals {
+    readonly scopePath: string;
+    readonly signals: readonly CandidateSignal[];
+    readonly baseScore: number;
+    readonly generatedHint: boolean;
+}
+export declare function extractSignals(atomsForPath: readonly EvidenceAtom[], anchors: readonly SearchAnchor[], hints: Required<RankingHints>): ExtractedSignals;
+//# sourceMappingURL=signals.d.ts.map

package/dist/ranking/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../src/ranking/signals.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACb,MAAM,iDAAiD,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpD;AAED,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAS9C,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAyHD,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,YAAY,EAAE,EACrC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,GAC5B,gBAAgB,CAuBlB"}

package/dist/ranking/signals.js

@@ -0,0 +1,145 @@
+// Per-candidate signal extraction for the deterministic hybrid ranker (Epic #177, Issue #182).
+// Pure JS — no IO, no clock, no randomness. The signal name list is fixed; the scoring layer
+// maps weights to signals by NAME (see SIGNAL_WEIGHT_KEYS in scoring.ts), not by position.
+// Penalties are emitted alongside positive signals so the scorer treats them uniformly;
+// downstream code interprets values via signal names only.
+export const DEFAULT_GENERATED_PATTERNS = [
+    "/dist/",
+    "/build/",
+    "/.next/",
+    "/coverage/",
+    "/__snapshots__/",
+    ".min.js",
+    ".bundle.js",
+    ".d.ts.map",
+];
+// Fixed regex for stack-frame "at fn (path:line:col)" and "at path:line:col" detection.
+// No user input is interpolated.
+const STACK_FRAME_RE = /^\s*at\s+(?:\S+\s+\(([^\s:]+):\d+(?::\d+)?\)|([^\s:]+):\d+(?::\d+)?)/;
+function clampUnit(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function detectGenerated(scopePath, patterns) {
+    // Scope paths are workspace-relative (no leading "/"), so a pattern like "/dist/" would
+    // miss a root-level "dist/foo.js". Match leading "<pattern-without-slash>/" against the
+    // path start AND the original "/<pattern>/" anywhere inside the path. .min.js / .bundle.js
+    // / .d.ts.map patterns (no leading "/") use a plain substring match.
+    const lower = scopePath.toLowerCase();
+    for (const pattern of patterns) {
+        const p = pattern.toLowerCase();
+        if (lower.includes(p)) {
+            return true;
+        }
+        if (p.startsWith("/") && p.endsWith("/")) {
+            const stripped = p.slice(1);
+            if (lower.startsWith(stripped)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function computeProvenanceBestScore(atoms) {
+    if (atoms.length === 0) {
+        return 0;
+    }
+    let best = 0;
+    for (const candidate of atoms) {
+        if (candidate.score > best) {
+            best = candidate.score;
+        }
+    }
+    return clampUnit(best);
+}
+function computeProvenanceCount(atoms) {
+    return Math.min(atoms.length, 10) / 10;
+}
+function computeAnchorOverlap(scopePath, anchors) {
+    if (anchors.length === 0) {
+        return 0;
+    }
+    const lowerPath = scopePath.toLowerCase();
+    let hits = 0;
+    for (const anc of anchors) {
+        if (anc.term.length > 0 && lowerPath.includes(anc.term.toLowerCase())) {
+            hits += 1;
+        }
+    }
+    return clampUnit(hits / anchors.length);
+}
+function computePathDepthAffinity(scopePath) {
+    if (scopePath.length === 0) {
+        return 0;
+    }
+    const depth = scopePath.split("/").length - 1;
+    return 1 / (1 + depth);
+}
+function computeTestPairBonus(scopePath, anchors) {
+    const isTest = scopePath.endsWith(".test.ts") || scopePath.endsWith(".spec.ts");
+    if (!isTest) {
+        return 0;
+    }
+    const sourcePath = scopePath.replace(/\.test\.ts$/, ".ts").replace(/\.spec\.ts$/, ".ts");
+    const lowerSourcePath = sourcePath.toLowerCase();
+    for (const anc of anchors) {
+        if (anc.kind === "path" && anc.term.toLowerCase() === lowerSourcePath) {
+            return 1;
+        }
+    }
+    return 0;
+}
+function computeStacktracePositionBonus(scopePath, anchors) {
+    if (scopePath.length === 0) {
+        return 0;
+    }
+    // The planner lowercases anchor terms, so we compare case-insensitively here too. A
+    // direct equality on the captured path would miss legitimate matches whose source file
+    // name has uppercase characters (and would also be inconsistent on case-insensitive
+    // filesystems like macOS/Windows).
+    const lowerScopePath = scopePath.toLowerCase();
+    for (const anc of anchors) {
+        if (anc.kind !== "quoted") {
+            continue;
+        }
+        const match = STACK_FRAME_RE.exec(anc.term);
+        if (match === null) {
+            continue;
+        }
+        const framePath = match[1] ?? match[2];
+        if (framePath?.toLowerCase() === lowerScopePath) {
+            return 1;
+        }
+    }
+    return 0;
+}
+function deriveScopePath(atoms) {
+    if (atoms.length === 0) {
+        return "";
+    }
+    const first = atoms[0];
+    return first === undefined ? "" : first.scopePath;
+}
+export function extractSignals(atomsForPath, anchors, hints) {
+    const scopePath = deriveScopePath(atomsForPath);
+    const generatedHint = detectGenerated(scopePath, hints.generatedPathPatterns);
+    const provBest = computeProvenanceBestScore(atomsForPath);
+    const provCount = computeProvenanceCount(atomsForPath);
+    const overlap = computeAnchorOverlap(scopePath, anchors);
+    const depthAff = computePathDepthAffinity(scopePath);
+    const testBonus = computeTestPairBonus(scopePath, anchors);
+    const stackBonus = computeStacktracePositionBonus(scopePath, anchors);
+    const penalty = generatedHint ? -1 : 0;
+    const signals = [
+        { name: "provenance-best-score", value: provBest },
+        { name: "provenance-count", value: provCount },
+        { name: "anchor-overlap", value: overlap },
+        { name: "path-depth-affinity", value: depthAff },
+        { name: "test-pair-bonus", value: testBonus },
+        { name: "stacktrace-position-bonus", value: stackBonus },
+        { name: "generated-penalty", value: penalty },
+    ];
+    const positives = [provBest, provCount, overlap, depthAff, testBonus, stackBonus];
+    const positiveMean = positives.reduce((acc, n) => acc + n, 0) / positives.length;
+    const baseScore = clampUnit(positiveMean + penalty);
+    return { scopePath, signals, baseScore, generatedHint };
+}

package/dist/unit-tests/context.d.ts

@@ -0,0 +1,7 @@
+import { type ContextPack, type WorkspaceFs, type WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import type { UnitTestWorkflowInput, WorkflowLimits } from "./types.js";
+export interface TestGenContextDeps {
+    readonly fs?: WorkspaceFs | undefined;
+}
+export declare function buildTestGenContext(workspace: WorkspaceInfo, input: UnitTestWorkflowInput, limits: WorkflowLimits, deps?: TestGenContextDeps): ContextPack;
+//# sourceMappingURL=context.d.ts.map

package/dist/unit-tests/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/unit-tests/context.ts"],"names":[],"mappings":"AAOA,OAAO,EAKL,KAAK,WAAW,EAOhB,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAkB,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAExF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACvC;AAsJD,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,kBAAuB,GAC5B,WAAW,CAcb"}