@bastani/atomic 0.9.16-alpha.7 → 0.9.16-alpha.8

package/dist/builtin/workflows/builtin/review-convergence.ts

@@ -1,229 +0,0 @@
-export type ReviewNextAction =
-  | "implementation"
-  | "pull-request"
-  | "finish"
-  | "blocked"
-  | "needs_human";
-
-export type ParseDiagnostics = {
-  readonly kind: "structured_output_parse_failure";
-  readonly message: string;
-  readonly raw_text_preview?: string;
-};
-
-export type ReviewConvergenceSummary = {
-  readonly parsed: boolean;
-  readonly approved: boolean;
-  readonly stopReviewLoop: boolean;
-  readonly nextAction: ReviewNextAction;
-  readonly finalActionRemaining: boolean;
-  readonly diagnostics: readonly string[];
-};
-
-export type ParsedReviewDecision<TDecision> = {
-  readonly decision: TDecision;
-  readonly parsed: boolean;
-  readonly diagnostics: readonly string[];
-};
-
-export type RequirementTraceabilityLike = {
-  readonly requirement: string;
-  readonly status: "proven" | "contradicted" | "missing" | "unverified";
-  readonly evidence: string;
-};
-
-const FINAL_ACTION_PATTERN = /\b(?:pr|pull[- ]request|merge[- ]request|review request|github pr|create pr)\b/iu;
-
-export function isFinalActionTraceability(
-  entry: RequirementTraceabilityLike,
-): boolean {
-  return FINAL_ACTION_PATTERN.test(`${entry.requirement}\n${entry.evidence}`);
-}
-
-export function finalActionRemaining(
-  traceability: readonly RequirementTraceabilityLike[],
-): boolean {
-  return traceability.some(
-    (entry) => entry.status !== "proven" && isFinalActionTraceability(entry),
-  );
-}
-
-export function traceabilityProvenExceptFinalAction(args: {
-  readonly traceability: readonly RequirementTraceabilityLike[];
-  readonly allowFinalActionRemaining: boolean;
-}): boolean {
-  return args.traceability.length > 0 && args.traceability.every((entry) => {
-    if (entry.status === "proven") return true;
-    return args.allowFinalActionRemaining &&
-      entry.status !== "contradicted" &&
-      isFinalActionTraceability(entry);
-  });
-}
-
-/**
- * Highest numeric finding priority that still blocks evidence closure for
- * in-scope (`consistent_with_objective`) findings. P0=0, P1=1, P2=2 block;
- * P3=3 is a dismissible nice-to-have only when the finding is not required by
- * the objective.
- */
-export const MAX_BLOCKING_PRIORITY = 2;
-
-export type ObjectiveAlignedFindingLike = {
-  readonly objective_alignment?: string;
-  readonly priority?: number | null;
-};
-
-/**
- * Shared evidence-closure predicate for reviewer findings.
- *
- * A finding keeps the convergence loop open when it is objective-relevant and
- * unresolved:
- * - `required_by_objective` findings block at ANY priority — severity labels
- *   alone never dismiss work the literal contract requires.
- * - `consistent_with_objective` findings block at P0/P1/P2; P3 is a
- *   non-blocking nice-to-have. Missing/`null` priority blocks so ambiguity
- *   never silently approves.
- * - `beyond_objective` / `contradicts_objective` findings never block: the
- *   literal contract's scope controls stay authoritative.
- * - Unknown or missing alignment blocks, so unclassified findings cannot be
- *   waved through.
- */
-export function findingBlocksClosure(finding: ObjectiveAlignedFindingLike): boolean {
-  const alignment = finding.objective_alignment;
-  if (alignment === "beyond_objective" || alignment === "contradicts_objective") {
-    return false;
-  }
-  if (alignment === "required_by_objective") return true;
-  if (alignment !== "consistent_with_objective") return true;
-  const priority = finding.priority;
-  if (priority === undefined || priority === null) return true;
-  return priority <= MAX_BLOCKING_PRIORITY;
-}
-
-export type ConsolidatableFinding = ObjectiveAlignedFindingLike & {
-  readonly title: string;
-  readonly code_location?: {
-    readonly absolute_file_path: string;
-  };
-};
-
-export type ConsolidatedFinding<F extends ConsolidatableFinding> = {
-  readonly finding: F;
-  readonly reviewers: readonly string[];
-  readonly blocking: boolean;
-};
-
-function findingConsolidationKey(finding: ConsolidatableFinding): string {
-  const normalizedTitle = finding.title
-    .replace(/^\s*\[P[0-3]\]\s*/iu, "")
-    .toLowerCase()
-    .replace(/\s+/gu, " ")
-    .trim();
-  return `${finding.code_location?.absolute_file_path ?? ""}::${normalizedTitle}`;
-}
-
-/**
- * Consolidate the current review round's findings into one deduplicated batch
- * so repair work is planned and executed batch-wise instead of one finding per
- * turn. Findings from different reviewers that name the same location and
- * (priority-tag-insensitive) title merge into a single entry; blocking status
- * is the OR of the merged findings, and blocking entries sort first.
- */
-export function consolidateFindingsBatch<F extends ConsolidatableFinding>(
-  reviews: readonly { readonly reviewer: string; readonly findings: readonly F[] }[],
-): ConsolidatedFinding<F>[] {
-  const byKey = new Map<string, { finding: F; reviewers: string[]; blocking: boolean }>();
-  for (const review of reviews) {
-    for (const finding of review.findings) {
-      const key = findingConsolidationKey(finding);
-      const existing = byKey.get(key);
-      if (existing === undefined) {
-        byKey.set(key, {
-          finding,
-          reviewers: [review.reviewer],
-          blocking: findingBlocksClosure(finding),
-        });
-        continue;
-      }
-      if (!existing.reviewers.includes(review.reviewer)) {
-        existing.reviewers.push(review.reviewer);
-      }
-      existing.blocking = existing.blocking || findingBlocksClosure(finding);
-    }
-  }
-  return [...byKey.values()].sort((a, b) => Number(b.blocking) - Number(a.blocking));
-}
-
-/**
- * The unresolved objective-relevant findings that veto evidence closure for a
- * review round, regardless of how many reviewers individually approved.
- */
-export function unresolvedClosureFindings<F extends ConsolidatableFinding>(
-  reviews: readonly { readonly reviewer: string; readonly findings: readonly F[] }[],
-): ConsolidatedFinding<F>[] {
-  return consolidateFindingsBatch(reviews).filter((entry) => entry.blocking);
-}
-
-/** Short, inspectable summary of the findings that keep closure open. */
-export function closureGapSummary(
-  unresolved: readonly ConsolidatedFinding<ConsolidatableFinding>[],
-): string {
-  const preview = unresolved
-    .slice(0, 5)
-    .map((entry) => entry.finding.title)
-    .join("; ");
-  const suffix = unresolved.length > 5 ? "; …" : "";
-  return `${unresolved.length} unresolved objective-relevant blocking finding(s)${
-    preview.length > 0 ? `: ${preview}${suffix}` : ""
-  }`;
-}
-
-const PREVIEW_LIMIT = 500;
-
-function rawTextPreview(rawText: string): string | undefined {
-  const trimmed = rawText.trim();
-  if (trimmed.length === 0) return undefined;
-  return trimmed.slice(0, PREVIEW_LIMIT);
-}
-
-export function parseFailureDiagnostics(
-  reviewer: string,
-  rawText: string,
-): readonly string[] {
-  const preview = rawTextPreview(rawText);
-  const base = `Structured reviewer decision parse failed for ${reviewer}: no schema-valid JSON decision was returned.`;
-  return preview === undefined ? [base] : [base, `Raw reviewer output preview: ${preview}`];
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-export function reviewerFailureText(error: unknown): string {
-  const messages = [errorMessage(error)];
-  if (error instanceof AggregateError) {
-    for (const nested of error.errors) {
-      messages.push(errorMessage(nested));
-    }
-  }
-  return [...new Set(messages.map((message) => message.trim()).filter(Boolean))]
-    .join("\n");
-}
-
-export function summarizeReviewConvergence(args: {
-  readonly parsed: boolean;
-  readonly approved: boolean;
-  readonly stopReviewLoop: boolean;
-  readonly nextAction: ReviewNextAction;
-  readonly finalActionRemaining?: boolean;
-  readonly diagnostics: readonly string[];
-}): ReviewConvergenceSummary {
-  return {
-    parsed: args.parsed,
-    approved: args.approved,
-    stopReviewLoop: args.stopReviewLoop,
-    nextAction: args.nextAction,
-    finalActionRemaining: args.finalActionRemaining ?? args.nextAction === "pull-request",
-    diagnostics: args.diagnostics,
-  };
-}

package/dist/builtin/workflows/builtin/selection-math.ts

@@ -1,156 +0,0 @@
-/** Pure, seeded selection math for the probabilistic pivot tournament. */
-import { VERIFICATION_SCALE } from "./verification-criteria.js";
-
-export interface DirectedPair {
-	a: number;
-	b: number;
-}
-
-export interface ScoringJob {
-	a: number;
-	b: number;
-	criterionId: string;
-	rep: number;
-	swapped: boolean;
-}
-
-export interface ComparisonPlan {
-	ring: DirectedPair[];
-	pivotRounds: (pivots: number[]) => DirectedPair[];
-	jobs: (pairs: readonly DirectedPair[], criterionIds: readonly string[]) => ScoringJob[];
-}
-
-export interface Preference {
-	a: number;
-	b: number;
-	p: number;
-}
-
-export interface RankingEntry {
-	index: number;
-	meanPreference: number;
-}
-
-export type Ranking = RankingEntry[];
-
-const UINT32_RANGE = 0x1_0000_0000;
-const MULBERRY_INCREMENT = 0x6d2b79f5;
-
-/** Return a deterministic Mulberry32-class random-float generator. */
-export function seeded_rng(seed: number): () => number {
-	let state = seed >>> 0;
-	return () => {
-		state = (state + MULBERRY_INCREMENT) >>> 0;
-		let t = state;
-		t = Math.imul(t ^ (t >>> 15), t | 1);
-		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-		return ((t ^ (t >>> 14)) >>> 0) / UINT32_RANGE;
-	};
-}
-
-function ring_cycle(n: number, rng: () => number): DirectedPair[] {
-	const permutation = Array.from({ length: n }, (_, index) => index);
-	for (let index = n - 1; index > 0; index -= 1) {
-		const other = Math.floor(rng() * (index + 1));
-		[permutation[index], permutation[other]] = [permutation[other]!, permutation[index]!];
-	}
-	return permutation.map((a, index) => ({ a, b: permutation[(index + 1) % n]! }));
-}
-
-function pair_key(a: number, b: number): string {
-	return a < b ? `${a}:${b}` : `${b}:${a}`;
-}
-
-
-/** Build a deterministic ring and expose the later pivot/job phases as pure closures. */
-export function plan_comparisons(input: {
-	n: number;
-	pivots: number;
-	repeats: number;
-	seed: number;
-}): ComparisonPlan {
-	const { n, pivots: pivotCount, repeats, seed } = input;
-	if (n < 2) throw new RangeError("n must be at least 2");
-	if (pivotCount < 1) throw new RangeError("pivots must be at least 1");
-	if (repeats < 1) throw new RangeError("repeats must be at least 1");
-
-	const ring = ring_cycle(n, seeded_rng(seed));
-	return {
-		ring,
-		pivotRounds: (pivots) => {
-			const scheduled = new Set(ring.map(({ a, b }) => pair_key(a, b)));
-			const pivotSet = new Set(pivots);
-			const pairs: DirectedPair[] = [];
-			const add = (a: number, b: number): void => {
-				if (a === b) return;
-				const key = pair_key(a, b);
-				if (scheduled.has(key)) return;
-				scheduled.add(key);
-				pairs.push({ a, b });
-			};
-			for (let candidate = 0; candidate < n; candidate += 1) {
-				if (pivotSet.has(candidate)) continue;
-				for (const pivot of pivots) add(candidate, pivot);
-			}
-			for (let first = 0; first < pivots.length; first += 1) {
-				for (let second = first + 1; second < pivots.length; second += 1) {
-					add(pivots[first]!, pivots[second]!);
-				}
-			}
-			return pairs;
-		},
-		jobs: (pairs, criterionIds) => {
-			const jobs: ScoringJob[] = [];
-			for (const pair of pairs) {
-				for (const criterionId of criterionIds) {
-					for (let rep = 0; rep < repeats; rep += 1) {
-						jobs.push({ a: pair.a, b: pair.b, criterionId, rep, swapped: rep % 2 === 1 });
-					}
-				}
-			}
-			return jobs;
-		},
-	};
-}
-
-/** Convert a verification score to the reward range used by Bradley-Terry. */
-function normalize_score(score: number): number {
-	return (score - VERIFICATION_SCALE.min) / (VERIFICATION_SCALE.max - VERIFICATION_SCALE.min);
-}
-
-/** Return the Bradley-Terry soft preference for the first score. */
-export function soft_win(scoreA: number, scoreB: number): number {
-	const difference = normalize_score(scoreA) - normalize_score(scoreB);
-	return 1 / (1 + Math.exp(-difference));
-}
-
-/** Add each preference to both candidates' win mass and comparison count. */
-export function accumulate(prefs: readonly Preference[], w: number[], c: number[]): void {
-	for (const { a, b, p } of prefs) {
-		w[a]! += p;
-		c[a]! += 1;
-		w[b]! += 1 - p;
-		c[b]! += 1;
-	}
-}
-
-function mean_preference(w: number[], c: number[], index: number): number {
-	return c[index] === 0 ? 0 : w[index]! / c[index]!;
-}
-
-function candidate_order(w: number[], c: number[]): number[] {
-	return Array.from({ length: w.length }, (_, index) => index).sort((left, right) => {
-		const difference = mean_preference(w, c, right) - mean_preference(w, c, left);
-		return difference === 0 ? left - right : difference;
-	});
-}
-
-/** Return the top-k candidate indices, resolving equal means by index. */
-export function select_pivots(w: number[], c: number[], k: number): number[] {
-	return candidate_order(w, c).slice(0, k);
-}
-
-/** Return every candidate ordered by mean preference, including unscored ones. */
-export function rank_candidates(w: number[], c: number[]): Ranking {
-	return candidate_order(w, c).map((index) => ({ index, meanPreference: mean_preference(w, c, index) }));
-}

package/dist/builtin/workflows/builtin/steering-context.ts

@@ -1,51 +0,0 @@
-/**
- * Steering propagation wrapper for builtin workflow run contexts.
- *
- * Every builtin workflow wraps its run context once, at the definition entry
- * point, so each `ctx.task` / `ctx.chain` / `ctx.parallel` prompt carries the
- * steering propagation contract. Wrapping the context rather than every call
- * site means a stage added later inherits the pattern instead of silently
- * dropping user amendments on the floor.
- *
- * The wrapper delegates through the prototype chain rather than spreading:
- * the runtime context exposes `cwd` as a getter that resolves the workflow's
- * current working directory on each read, and a spread would snapshot it.
- *
- * cross-ref:
- *   - builtin/shared-prompts.ts (STEERING_PROPAGATION_CONTRACT)
- *   - test/unit/builtin-workflow-steering-propagation.test.ts (enforcement)
- */
-import type {
-  WorkflowInputValues,
-  WorkflowOutputValues,
-  WorkflowRunContext,
-  WorkflowTaskOptions,
-  WorkflowTaskStep,
-} from "../src/shared/types.js";
-import { withSteeringPropagation } from "./shared-prompts.js";
-
-function withPromptContract(options: WorkflowTaskOptions): WorkflowTaskOptions {
-  return options.prompt === undefined
-    ? options
-    : { ...options, prompt: withSteeringPropagation(options.prompt) };
-}
-
-function withStepContract(step: WorkflowTaskStep): WorkflowTaskStep {
-  const withPrompt = step.prompt === undefined
-    ? step
-    : { ...step, prompt: withSteeringPropagation(step.prompt) };
-  return withPrompt.task === undefined
-    ? withPrompt
-    : { ...withPrompt, task: withSteeringPropagation(withPrompt.task) };
-}
-
-export function withSteeringPropagationContext<
-  TInputs extends WorkflowInputValues,
-  TOutputs extends WorkflowOutputValues,
->(ctx: WorkflowRunContext<TInputs, TOutputs>): WorkflowRunContext<TInputs, TOutputs> {
-  const wrapped = Object.create(ctx) as WorkflowRunContext<TInputs, TOutputs>;
-  wrapped.task = (name, options) => ctx.task(name, withPromptContract(options));
-  wrapped.chain = (steps, options) => ctx.chain(steps.map(withStepContract), options);
-  wrapped.parallel = (steps, options) => ctx.parallel(steps.map(withStepContract), options);
-  return wrapped;
-}

package/dist/builtin/workflows/builtin/tournament-prompts.ts

@@ -1,70 +0,0 @@
-type PromptSection = readonly [tag: string, content: string];
-
-const GROUNDED_REPORTING = "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
-const READABLE_REPORT = "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background and repetition. Use complete, readable sentences rather than compressed fragments.";
-
-/** The default three-criterion decomposition of the tournament rubric. */
-export const DEFAULT_TOURNAMENT_CRITERIA = [
-	{ name: "Correctness", description: "Satisfies the task without material errors." },
-	{ name: "Completeness", description: "Covers required outcomes and important edge cases." },
-	{
-		name: "Evidence and task fit",
-		description: "Supports claims with observable evidence or checks and is directly usable without irrelevant work.",
-	},
-] as const;
-
-function taggedPrompt(sections: readonly PromptSection[]): string {
-	return sections
-		.map(([tag, content]) => `<${tag}>\n${content.trim()}\n</${tag}>`)
-		.join("\n\n");
-}
-
-export function renderTournamentAttemptPrompt(task: string, attempt: number): string {
-	return taggedPrompt([
-		["role", "You are an independent solution author competing on solution quality."],
-		["attempt", `Produce attempt ${attempt} without assuming another attempt's approach or conclusions.`],
-		["success_criteria", "A judge can evaluate this artifact directly against correctness, completeness, evidence, and task fit."],
-		["requirements", [
-			"Deliver a complete, self-contained solution rather than commentary about how to solve it.",
-			"Ground important claims in observable evidence or executable checks.",
-			"State assumptions, limitations, and validation performed.",
-			"Optimize for correctness and usefulness, not length.",
-			GROUNDED_REPORTING,
-		].join("\n")],
-		["stop_rules", "Stop when the solution is complete, supported, validated where practical, and its residual risks are stated."],
-		["output_format", `Markdown with Solution, Evidence and validation, Assumptions, and Residual risks. ${READABLE_REPORT}`],
-		["objective", task],
-	]);
-}
-
-export function renderComparisonsReducerPrompt(options: {
-	readonly task: string;
-	readonly comparisonsPath: string;
-	readonly ranking: readonly { readonly label: string; readonly meanPreference: number }[];
-	readonly winnerLabel: string;
-	readonly winnerPath: string;
-}): string {
-	const rankingText = options.ranking
-		.map((entry, index) => `${index + 1}. ${entry.label} (mean preference ${entry.meanPreference})`)
-		.join("\n");
-	return taggedPrompt([
-		["artifacts", [
-			`Comparisons ledger: ${options.comparisonsPath}`,
-			`Winning artifact (${options.winnerLabel}): ${options.winnerPath}`,
-			"Read the ledger and winning artifact before reporting.",
-		].join("\n")],
-		["role", "You are the soft-scored tournament reducer and final reporter."],
-		["ranking", rankingText],
-		["requirements", [
-			"Return the winning solution faithfully; do not silently combine losing material into it.",
-			"Report the full ranking exactly as recorded in the comparisons ledger.",
-			"Identify notable score disagreements, invalid reports, or other limitations recorded by judges.",
-			"Cite the comparisons ledger and winning artifact paths.",
-			GROUNDED_REPORTING,
-		].join("\n")],
-		["success_criteria", "A reader can use the winning solution and recompute the ranking from the durable comparisons ledger."],
-		["stop_rules", "Stop after faithfully presenting the winner, full ranking, decision evidence, and residual risks."],
-		["output_format", `Markdown with Winner, Full ranking, Decision trail, Evidence, Notable disagreements, and Residual risks. ${READABLE_REPORT}`],
-		["objective", options.task],
-	]);
-}