@velum-labs/routekit-eval-setup 1.3.2 → 1.5.0

package/dist/services/pipeline-spec/service.js

@@ -0,0 +1,619 @@
+import { Clock, Effect, Option, Schema } from "effect";
+import { captureGitTreeSnapshotV1, readGitTreeFileV1 } from "../../adapters/git-task-history.js";
+import { checkpointDigestV1, PipelineStageError, pipelineStageToProgressStageV1 } from "../../case-pipeline-protocol.js";
+import { RepositoryFoundryError } from "../../errors.js";
+import { repositoryFoundryRoleOutputCeilingV1 } from "../../repository-foundry-plan-protocol.js";
+import { repositoryFoundryModelAssignmentV1 } from "../../repository-language-model-protocol.js";
+import { RepositorySpecificationBehaviorCoverageV1, RepositorySpecificationCritiqueAxisV1, RepositorySpecificationDimensionFitV1, RepositorySpecificationReferenceCompatibilityV1 } from "../../repository-specification-critique-protocol.js";
+import { generateWithFeedbackV1 } from "../budgeted-model/service.js";
+import { reportFoundryStageV1 } from "../foundry-progress/service.js";
+import { groundedStructuredGenerationV1 } from "../grounded-authoring/service.js";
+import { RepositoryFoundryLanguageModel } from "../language-model/service.js";
+/**
+ * Reference-grounded specification stage for the additive case pipeline.
+ * The analyst and private critic inspect only pinned Git trees. The writer is
+ * deliberately blind to the reference tree and receives only public behavior
+ * prose plus complete pre-change sources. Reviews are advisory specification
+ * evidence; they never constitute benchmark admission evidence.
+ */
+const STAGE = "spec";
+const MAX_CONTEXT_FILES = 12;
+const MAX_CONTEXT_FILE_BYTES = 96_000;
+const MAX_CONTEXT_TOTAL_BYTES = 256_000;
+const DIMENSION_MISMATCH_CONFIRMATIONS = 2;
+const AnalystCitationV1 = Schema.Struct({
+    commit: Schema.Literals(["initial", "reference"]),
+    path: Schema.String,
+    startLine: Schema.Finite,
+    endLine: Schema.Finite
+});
+const AnalystScopeEntryV1 = Schema.Struct({
+    id: Schema.String,
+    kind: Schema.Literals(["changed", "preserved"]),
+    behaviorIds: Schema.Array(Schema.String),
+    description: Schema.String,
+    evidence: Schema.Array(AnalystCitationV1)
+});
+const PipelineSpecificationAnalysisV1 = Schema.Struct({
+    summary: Schema.String,
+    userObservableBehaviors: Schema.Array(Schema.String),
+    constraints: Schema.Array(Schema.String),
+    risks: Schema.Array(Schema.String),
+    relevantPaths: Schema.Array(Schema.String),
+    scope: Schema.Array(AnalystScopeEntryV1)
+});
+const PipelineVisibleTaskProposalV1 = Schema.Struct({
+    requestText: Schema.String,
+    constraints: Schema.Array(Schema.String)
+});
+const PipelineSpecificationReviewOutputV1 = Schema.Struct({
+    verdict: Schema.Literals(["sufficient", "insufficient"]),
+    detail: Schema.String,
+    criticalBehaviorCoverage: Schema.Array(RepositorySpecificationBehaviorCoverageV1),
+    dimensionFit: RepositorySpecificationDimensionFitV1,
+    referenceCompatibility: RepositorySpecificationReferenceCompatibilityV1,
+    findings: Schema.Array(Schema.Struct({
+        axis: RepositorySpecificationCritiqueAxisV1,
+        severity: Schema.Literals(["blocker", "warning"]),
+        detail: Schema.String
+    }))
+});
+const ANALYST_INSTRUCTIONS = `You are the private repository analyst for one coding benchmark case.
+Inspect both pinned Git trees with the grounded tools before submitting. The complete dimension contract is
+supplied as {id, description, includes, excludes}; apply every field and do not broaden the historical change
+to force a fit. Establish the actual user-observable change and the behavior the reference preserves.
+Return at least one changed and one preserved scope clause. Every clause must cite non-empty one-based inclusive
+line ranges in both the initial and reference trees using {commit, path, startLine, endLine}. Cover every supplied
+target behavior id with grounded scope. Select only complete pre-change files that a blind coding agent needs;
+relevantPaths becomes the writer's entire repository context, so keep it focused. Public analysis and scope
+prose must not include commits, private source identifiers, test contents, or implementation instructions.
+Do not write the visible task, fixtures, or a solution. Return one submit action only after grounding the result.`;
+const WRITER_INSTRUCTIONS = `You are the blind specification-writer for a repository coding benchmark.
+You receive public issue scope, the complete dimension contract, and complete files from the pinned pre-change
+checkout. You do not receive the reference tree, historical patch, private citations, tests added by the change,
+or hidden fixtures. Write a realistic issue-style request that states all changed behavior and necessary
+preservation boundaries while allowing any behaviorally correct implementation. Do not invent requirements to
+match the dimension. Do not mention benchmark machinery or prescribe implementation details. On a revision,
+resolve every supplied review finding while preserving the authentic scope. Return only requestText and constraints.`;
+const CRITIC_INSTRUCTIONS = `You are the single private reference critic for a benchmark specification.
+Inspect both pinned Git trees with the grounded tools. Review the visible task against the complete dimension
+contract and every grounded changed and preserved scope clause. Model criticism is advisory: do not claim that
+your review admits or rejects a benchmark. Return exactly one coverage record for every critical behavior id.
+Return dimensionFit for the exact dimension id, supported by paths in the initial tree. Return
+referenceCompatibility with exactly one scopeCoverage record per scope id; every support record must cite
+non-empty one-based inclusive reference-tree lines using the supplied sourceId catalog. Mark the review
+sufficient only when the task covers all critical behavior, fits the complete dimension contract, and is fully
+compatible with the pinned reference. Findings and detail sent to the blind writer must remain public behavior
+prose: do not quote private code, commits, source ids, tests, or prescribe a patch. If the authentic change is
+off-dimension, say mismatch rather than widening it. Return one submit action after grounding the review.`;
+const failure = (detail, cause) => new RepositoryFoundryError({
+    operation: "run-pipeline-stage",
+    detail,
+    ...(cause === undefined ? {} : { cause })
+});
+const assignmentOf = (input) => Effect.try({
+    try: () => repositoryFoundryModelAssignmentV1(input.plan, input.role),
+    catch: (cause) => failure(`could not resolve ${input.role} model assignment`, cause)
+});
+const nonEmpty = (value) => value.trim().length > 0;
+const uniqueNonEmpty = (values) => values.length > 0 && new Set(values).size === values.length && values.every(nonEmpty);
+const citationKey = (citation) => `${citation.commit}:${citation.path}:${String(citation.startLine)}:${String(citation.endLine)}`;
+const readCitationContent = Effect.fnUntraced(function* (input) {
+    const snapshot = input.snapshots[input.citation.commit];
+    const key = `${input.citation.commit}:${input.citation.path}`;
+    const cached = input.cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    if (!snapshot.files.includes(input.citation.path))
+        return undefined;
+    const content = yield* readGitTreeFileV1({ snapshot, path: input.citation.path });
+    input.cache.set(key, content);
+    return content;
+});
+const citationIsValid = Effect.fnUntraced(function* (input) {
+    if (!nonEmpty(input.citation.path) ||
+        !Number.isSafeInteger(input.citation.startLine) ||
+        !Number.isSafeInteger(input.citation.endLine) ||
+        input.citation.startLine < 1 ||
+        input.citation.endLine < input.citation.startLine) {
+        return false;
+    }
+    const content = yield* readCitationContent(input);
+    if (content === undefined)
+        return false;
+    const lines = content.split("\n");
+    return (input.citation.endLine <= lines.length &&
+        lines
+            .slice(input.citation.startLine - 1, input.citation.endLine)
+            .join("\n")
+            .trim().length > 0);
+});
+const validateAnalysis = Effect.fnUntraced(function* (input) {
+    const findings = [];
+    if (!nonEmpty(input.analysis.summary) ||
+        !uniqueNonEmpty(input.analysis.userObservableBehaviors) ||
+        input.analysis.constraints.some((entry) => !nonEmpty(entry)) ||
+        input.analysis.risks.some((entry) => !nonEmpty(entry))) {
+        findings.push({
+            kind: "contract",
+            message: "Analysis requires a summary, user-observable behaviors, and non-empty constraint and risk entries."
+        });
+    }
+    if (!uniqueNonEmpty(input.analysis.relevantPaths) ||
+        input.analysis.relevantPaths.length > MAX_CONTEXT_FILES ||
+        input.analysis.relevantPaths.some((path) => !input.snapshots.initial.files.includes(path))) {
+        findings.push({
+            kind: "contract",
+            message: `Select between one and ${String(MAX_CONTEXT_FILES)} unique files that exist in the pinned initial tree.`
+        });
+    }
+    const scopeIds = input.analysis.scope.map((entry) => entry.id);
+    if (input.analysis.scope.length < 2 ||
+        new Set(scopeIds).size !== scopeIds.length ||
+        input.analysis.scope.some((entry) => !nonEmpty(entry.id) ||
+            !nonEmpty(entry.description) ||
+            !uniqueNonEmpty(entry.behaviorIds) ||
+            entry.behaviorIds.some((id) => !input.behaviorIds.has(id)) ||
+            entry.evidence.length < 2 ||
+            new Set(entry.evidence.map(citationKey)).size !== entry.evidence.length ||
+            !entry.evidence.some((citation) => citation.commit === "initial") ||
+            !entry.evidence.some((citation) => citation.commit === "reference")) ||
+        !input.analysis.scope.some((entry) => entry.kind === "changed") ||
+        !input.analysis.scope.some((entry) => entry.kind === "preserved") ||
+        [...input.behaviorIds].some((behaviorId) => !input.analysis.scope.some((entry) => entry.behaviorIds.includes(behaviorId)))) {
+        findings.push({
+            kind: "contract",
+            message: "Scope needs unique changed and preserved clauses, must cover every target behavior id, and each clause needs initial and reference line citations."
+        });
+    }
+    const citations = input.analysis.scope.flatMap((entry) => entry.evidence);
+    const citationChecks = yield* Effect.forEach(citations, (citation) => citationIsValid({ citation, snapshots: input.snapshots, cache: input.cache }));
+    if (citationChecks.some((valid) => !valid)) {
+        findings.push({
+            kind: "contract",
+            message: "One or more scope citations do not identify non-empty, one-based inclusive lines in the named pinned tree."
+        });
+    }
+    const contextContents = yield* Effect.forEach(input.analysis.relevantPaths, (path) => readCitationContent({
+        citation: { commit: "initial", path, startLine: 1, endLine: 1 },
+        snapshots: input.snapshots,
+        cache: input.cache
+    }));
+    const contextBytes = contextContents.map((content) => content === undefined ? 0 : Buffer.byteLength(content));
+    if (contextBytes.some((bytes) => bytes > MAX_CONTEXT_FILE_BYTES) ||
+        contextBytes.reduce((total, bytes) => total + bytes, 0) > MAX_CONTEXT_TOTAL_BYTES) {
+        findings.push({
+            kind: "contract",
+            message: `Select complete context files within ${String(MAX_CONTEXT_FILE_BYTES)} bytes per file and ${String(MAX_CONTEXT_TOTAL_BYTES)} bytes total. Oversized files are not truncated.`
+        });
+    }
+    return findings;
+});
+const loadContextSources = Effect.fnUntraced(function* (input) {
+    const sources = [];
+    let totalBytes = 0;
+    for (const path of input.paths) {
+        if (!input.initial.files.includes(path)) {
+            return yield* failure(`analyst selected an unavailable initial-tree context path: ${path}`);
+        }
+        const content = yield* readGitTreeFileV1({ snapshot: input.initial, path });
+        const bytes = Buffer.byteLength(content);
+        if (bytes > MAX_CONTEXT_FILE_BYTES) {
+            return yield* failure(`analyst selected ${path}, whose complete ${String(bytes)} bytes exceed the ${String(MAX_CONTEXT_FILE_BYTES)}-byte context-file bound; no truncated file was presented as complete`);
+        }
+        totalBytes += bytes;
+        if (totalBytes > MAX_CONTEXT_TOTAL_BYTES) {
+            return yield* failure(`complete writer context exceeds ${String(MAX_CONTEXT_TOTAL_BYTES)} bytes; no context file was truncated`);
+        }
+        sources.push({ path, content });
+    }
+    return sources;
+});
+const makeSourceCatalog = Effect.fnUntraced(function* (input) {
+    const paths = [...new Set(input.paths)].sort();
+    const sources = [];
+    for (const path of paths) {
+        for (const phase of ["initial", "reference"]) {
+            const content = yield* readCitationContent({
+                citation: { commit: phase, path, startLine: 1, endLine: 1 },
+                snapshots: input.snapshots,
+                cache: input.cache
+            });
+            if (content === undefined)
+                continue;
+            sources.push({
+                sourceId: `spec-source-${checkpointDigestV1({ phase, path }).slice(0, 16)}`,
+                phase,
+                path,
+                content
+            });
+        }
+    }
+    return sources;
+});
+const reviewCitationValid = (evidence, sources) => {
+    const source = sources.find((candidate) => candidate.sourceId === evidence.sourceId && candidate.phase === "reference");
+    if (source === undefined ||
+        !Number.isSafeInteger(evidence.startLine) ||
+        !Number.isSafeInteger(evidence.endLine) ||
+        evidence.startLine < 1 ||
+        evidence.endLine < evidence.startLine) {
+        return false;
+    }
+    const lines = source.content.split("\n");
+    return (evidence.endLine <= lines.length &&
+        lines
+            .slice(evidence.startLine - 1, evidence.endLine)
+            .join("\n")
+            .trim().length > 0);
+};
+const validateReview = (input) => {
+    const findings = [];
+    const coverageIds = input.review.criticalBehaviorCoverage.map((entry) => entry.behaviorId);
+    if (coverageIds.length !== input.criticalBehaviorIds.size ||
+        new Set(coverageIds).size !== coverageIds.length ||
+        coverageIds.some((id) => !input.criticalBehaviorIds.has(id)) ||
+        input.review.criticalBehaviorCoverage.some((entry) => !nonEmpty(entry.detail))) {
+        findings.push({
+            kind: "contract",
+            message: "Return exactly one non-empty criticalBehaviorCoverage record for every critical behavior id."
+        });
+    }
+    const dimensionFit = input.review.dimensionFit;
+    if (dimensionFit.requestedDimension !== input.dimensionId ||
+        !nonEmpty(dimensionFit.detail) ||
+        !uniqueNonEmpty(dimensionFit.evidencePaths) ||
+        dimensionFit.evidencePaths.some((path) => !input.initial.files.includes(path))) {
+        findings.push({
+            kind: "contract",
+            message: "dimensionFit must address the exact supplied dimension id with a substantive explanation and existing initial-tree evidence paths."
+        });
+    }
+    const compatibility = input.review.referenceCompatibility;
+    const compatibilityIds = compatibility.scopeCoverage.map((entry) => entry.scopeId);
+    if (!nonEmpty(compatibility.detail) ||
+        compatibilityIds.length !== input.scopeIds.size ||
+        new Set(compatibilityIds).size !== compatibilityIds.length ||
+        compatibilityIds.some((id) => !input.scopeIds.has(id)) ||
+        compatibility.scopeCoverage.some((entry) => !nonEmpty(entry.detail) ||
+            entry.evidence.length === 0 ||
+            entry.evidence.some((evidence) => !reviewCitationValid(evidence, input.sources)))) {
+        findings.push({
+            kind: "contract",
+            message: "referenceCompatibility needs one substantive, valid reference-line-cited scopeCoverage record for every scope id."
+        });
+    }
+    if (!nonEmpty(input.review.detail) ||
+        input.review.findings.some((finding) => !nonEmpty(finding.detail))) {
+        findings.push({
+            kind: "contract",
+            message: "Review detail and finding detail must be non-empty."
+        });
+    }
+    if (input.review.verdict === "sufficient" &&
+        (dimensionFit.outcome !== "fit" ||
+            compatibility.outcome !== "compatible" ||
+            input.review.criticalBehaviorCoverage.some((entry) => entry.outcome !== "covered") ||
+            input.review.findings.some((finding) => finding.severity === "blocker"))) {
+        findings.push({
+            kind: "contract",
+            message: "A sufficient verdict requires fit, compatible reference evidence, complete critical coverage, and no blocker findings."
+        });
+    }
+    return findings;
+};
+const acceptedReview = (review) => review.verdict === "sufficient" &&
+    review.dimensionFit.outcome === "fit" &&
+    review.referenceCompatibility.outcome === "compatible" &&
+    review.criticalBehaviorCoverage.every((entry) => entry.outcome === "covered") &&
+    review.findings.every((finding) => finding.severity !== "blocker");
+const publicReviewFeedback = (review) => [
+    review.detail,
+    review.dimensionFit.detail,
+    ...review.criticalBehaviorCoverage
+        .filter((entry) => entry.outcome !== "covered")
+        .map((entry) => entry.detail),
+    ...review.referenceCompatibility.scopeCoverage
+        .filter((entry) => entry.outcome !== "supported")
+        .map((entry) => entry.detail),
+    ...(review.referenceCompatibility.questionResolutions ?? [])
+        .filter((entry) => entry.outcome === "unresolved")
+        .map((entry) => entry.detail),
+    ...review.findings.map((finding) => finding.detail)
+].filter(nonEmpty);
+const leakFindingsOf = (reviews) => reviews.flatMap((review) => review.findings
+    .filter((finding) => finding.axis === "hidden-answer-leakage")
+    .map((finding) => finding.detail));
+const reviewOutputOf = (review) => Schema.decodeUnknownOption(PipelineSpecificationReviewOutputV1)({
+    verdict: review.verdict,
+    detail: review.detail,
+    criticalBehaviorCoverage: review.criticalBehaviorCoverage,
+    dimensionFit: review.dimensionFit,
+    referenceCompatibility: review.referenceCompatibility,
+    findings: review.findings
+});
+const checkpointLastReview = (checkpoint, parentDigest) => {
+    if (checkpoint === undefined ||
+        checkpoint.parentDigest !== parentDigest ||
+        checkpoint.reviews.length === 0) {
+        return undefined;
+    }
+    const decoded = reviewOutputOf(checkpoint.reviews.at(-1));
+    return Option.isSome(decoded) && !acceptedReview(decoded.value)
+        ? { checkpoint, review: decoded.value }
+        : undefined;
+};
+const publicBehaviorOf = (seed, scope) => seed.targetBehavior.map((behavior) => ({
+    id: behavior.id,
+    critical: behavior.critical,
+    description: scope
+        .filter((entry) => entry.behaviorIds.includes(behavior.id))
+        .map((entry) => entry.description)
+        .join(" ")
+}));
+/** Source-only authoring also accepts an unqualified draft seed. It never executes repository recipes. */
+export const draftPipelineSpecificationV1 = Effect.fn("PipelineSpec.draft")(function* (input) {
+    const seed = input.seed;
+    const referenceCommit = seed.referenceCommit;
+    if (referenceCommit === undefined || referenceCommit === seed.initialState.commit) {
+        return yield* failure("spec stage requires distinct pinned initial and reference commits");
+    }
+    yield* reportFoundryStageV1(pipelineStageToProgressStageV1(STAGE), "grounding changed and preserved scope against pinned Git trees");
+    const languageModel = yield* RepositoryFoundryLanguageModel;
+    const [analystAssignment, writerAssignment, criticAssignment] = yield* Effect.all([
+        assignmentOf({ plan: input.context.modelPlan, role: "repository-analyst" }),
+        assignmentOf({ plan: input.context.modelPlan, role: "specification-writer" }),
+        assignmentOf({ plan: input.context.modelPlan, role: "specification-critic-b" })
+    ]);
+    const snapshots = {
+        initial: yield* captureGitTreeSnapshotV1({
+            repositoryRoot: input.context.repositoryRoot,
+            requestedRef: seed.initialState.commit
+        }),
+        reference: yield* captureGitTreeSnapshotV1({
+            repositoryRoot: input.context.repositoryRoot,
+            requestedRef: referenceCommit
+        })
+    };
+    const contentCache = new Map();
+    const behaviorIds = new Set(seed.targetBehavior.map((behavior) => behavior.id));
+    const criticalBehaviorIds = new Set(seed.targetBehavior.filter((behavior) => behavior.critical).map((behavior) => behavior.id));
+    const parentDigest = input.parentDigest;
+    const resumable = checkpointLastReview(input.checkpoints.spec, parentDigest);
+    let analysis;
+    let scope;
+    let contextSources;
+    let sourceCatalog;
+    const episode = input.map.historyEpisodes.find((candidate) => "changeEpisodeId" in seed.source && candidate.id === seed.source.changeEpisodeId);
+    const groundedSourcePaths = [
+        ...seed.capabilityEvidence.flatMap((evidence) => evidence.path === undefined ? [] : [evidence.path]),
+        ...seed.targetBehavior.flatMap((behavior) => behavior.evidence.flatMap((evidence) => (evidence.path === undefined ? [] : [evidence.path]))),
+        ...(episode?.changedPaths.flatMap((changed) => changed.previousPath === undefined ? [changed.path] : [changed.previousPath, changed.path]) ?? [])
+    ];
+    if (resumable === undefined) {
+        const analyst = yield* groundedStructuredGenerationV1({
+            checkpointStore: input.workCheckpointStore,
+            languageModel,
+            assignment: analystAssignment,
+            operationId: `${input.context.caseId}:spec:analyst`,
+            instructions: ANALYST_INSTRUCTIONS,
+            task: {
+                dimension: input.context.dimension,
+                seed: {
+                    id: seed.id,
+                    summary: seed.summary,
+                    source: seed.source,
+                    targetBehavior: seed.targetBehavior,
+                    capabilityEvidence: seed.capabilityEvidence
+                },
+                repository: {
+                    initialCommit: snapshots.initial.commit,
+                    referenceCommit: snapshots.reference.commit
+                }
+            },
+            outputSchema: PipelineSpecificationAnalysisV1,
+            schemaName: "routekit_pipeline_spec_analysis_v1",
+            tools: {
+                repositoryRoot: input.context.repositoryRoot,
+                commits: { initial: snapshots.initial.commit, reference: snapshots.reference.commit }
+            },
+            validateSubmission: (candidate) => validateAnalysis({ analysis: candidate, behaviorIds, snapshots, cache: contentCache }),
+            maxTurns: Math.max(1, Math.trunc(input.context.budget.maxModelCalls) + 1),
+            maxToolTurnsBeforeSubmit: 3,
+            maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("repository-analyst")
+        });
+        contextSources = yield* loadContextSources({
+            initial: snapshots.initial,
+            paths: analyst.value.relevantPaths
+        });
+        sourceCatalog = yield* makeSourceCatalog({
+            paths: [...groundedSourcePaths, ...contextSources.map((source) => source.path)],
+            snapshots,
+            cache: contentCache
+        });
+        scope = analyst.value.scope.map(({ evidence: _evidence, ...entry }) => entry);
+        analysis = {
+            summary: analyst.value.summary,
+            userObservableBehaviors: analyst.value.userObservableBehaviors,
+            constraints: analyst.value.constraints,
+            risks: analyst.value.risks
+        };
+    }
+    else {
+        analysis = resumable.checkpoint.analysis;
+        scope = resumable.checkpoint.scope;
+        contextSources = resumable.checkpoint.contextSources;
+        sourceCatalog = yield* makeSourceCatalog({
+            paths: [...groundedSourcePaths, ...contextSources.map((source) => source.path)],
+            snapshots,
+            cache: contentCache
+        });
+    }
+    const scopeIds = new Set(scope.map((entry) => entry.id));
+    const publicTargetBehavior = publicBehaviorOf(seed, scope);
+    let previousVisible = resumable?.checkpoint.visible;
+    let priorReviewFeedback = resumable === undefined ? [] : publicReviewFeedback(resumable.review);
+    const reviews = [
+        ...(resumable?.checkpoint.reviews ?? [])
+    ];
+    let consecutiveDimensionMismatches = 0;
+    for (const prior of [...reviews].reverse()) {
+        const decoded = reviewOutputOf(prior);
+        if (Option.isNone(decoded) || decoded.value.dimensionFit.outcome !== "mismatch")
+            break;
+        consecutiveDimensionMismatches += 1;
+    }
+    let revisions = resumable === undefined ? 0 : resumable.checkpoint.revisions + 1;
+    const startingSequence = reviews.length;
+    for (let sequence = startingSequence;; sequence += 1) {
+        yield* reportFoundryStageV1(pipelineStageToProgressStageV1(STAGE), sequence === 0
+            ? "writing blind visible task"
+            : `revising visible task, round ${String(sequence)}`);
+        const writer = yield* generateWithFeedbackV1({
+            ...(input.workCheckpointStore === undefined ? {} : {
+                checkpoint: {
+                    store: input.workCheckpointStore,
+                    binding: { parentDigest, initialCommit: snapshots.initial.commit }
+                }
+            }),
+            languageModel,
+            assignment: writerAssignment,
+            operationId: `${input.context.caseId}:spec:writer:round-${String(sequence)}`,
+            instructions: WRITER_INSTRUCTIONS,
+            input: {
+                dimension: input.context.dimension,
+                targetBehavior: publicTargetBehavior,
+                analysis,
+                scope,
+                initialRepositoryContext: contextSources,
+                ...(previousVisible === undefined
+                    ? {}
+                    : { previousVisible, behavioralReviewFeedback: priorReviewFeedback })
+            },
+            schemaName: "routekit_pipeline_visible_task_v1",
+            outputSchema: PipelineVisibleTaskProposalV1,
+            maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-writer"),
+            maxAttempts: Math.max(1, Math.trunc(input.context.budget.maxModelCalls) + 1),
+            validate: (proposal) => Effect.succeed(!nonEmpty(proposal.requestText) || proposal.constraints.some((entry) => !nonEmpty(entry))
+                ? [
+                    {
+                        kind: "contract",
+                        message: "Visible request text and every supplied constraint must be non-empty."
+                    }
+                ]
+                : [])
+        });
+        const visible = {
+            lane: "repository-agent",
+            id: input.context.caseId,
+            requestText: writer.value.requestText,
+            checkoutCommit: snapshots.initial.commit,
+            allowedTools: ["read", "search", "edit", "shell", "test"],
+            constraints: [
+                ...new Set([
+                    ...writer.value.constraints,
+                    "Do not weaken or delete tests to make the task pass.",
+                    "Preserve unrelated public behavior."
+                ])
+            ]
+        };
+        yield* reportFoundryStageV1(pipelineStageToProgressStageV1(STAGE), `checking visible task against private reference, round ${String(sequence)}`);
+        const critic = yield* groundedStructuredGenerationV1({
+            checkpointStore: input.workCheckpointStore,
+            languageModel,
+            assignment: criticAssignment,
+            operationId: `${input.context.caseId}:spec:critic:round-${String(sequence)}`,
+            instructions: CRITIC_INSTRUCTIONS,
+            task: {
+                dimension: input.context.dimension,
+                targetBehavior: seed.targetBehavior,
+                analysis,
+                scope,
+                visible,
+                sourceCatalog: sourceCatalog.map(({ content: _content, ...source }) => source)
+            },
+            outputSchema: PipelineSpecificationReviewOutputV1,
+            schemaName: "routekit_pipeline_specification_review_v1",
+            tools: {
+                repositoryRoot: input.context.repositoryRoot,
+                commits: { initial: snapshots.initial.commit, reference: snapshots.reference.commit }
+            },
+            validateSubmission: (review) => Effect.succeed(validateReview({
+                review,
+                criticalBehaviorIds,
+                scopeIds,
+                initial: snapshots.initial,
+                dimensionId: input.context.dimension.id,
+                sources: sourceCatalog
+            })),
+            maxTurns: Math.max(1, Math.trunc(input.context.budget.maxModelCalls) + 1),
+            maxToolTurnsBeforeSubmit: 3,
+            maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-critic-b")
+        });
+        const review = {
+            reviewerId: `${input.context.caseId}:spec:critic:round-${String(sequence)}`,
+            reviewerKind: "model-critic",
+            independentlyProduced: true,
+            ...critic.value
+        };
+        reviews.push(review);
+        const createdAt = new Date(yield* Clock.currentTimeMillis).toISOString();
+        const checkpoint = {
+            version: 1,
+            stage: STAGE,
+            parentDigest,
+            createdAt,
+            visible,
+            analysis,
+            scope,
+            contextSources,
+            reviews,
+            revisions,
+            leakFindings: leakFindingsOf(reviews)
+        };
+        yield* input.checkpoint(checkpoint);
+        if (acceptedReview(critic.value))
+            return checkpoint;
+        if (critic.value.dimensionFit.outcome === "mismatch") {
+            consecutiveDimensionMismatches += 1;
+        }
+        else {
+            consecutiveDimensionMismatches = 0;
+        }
+        if (consecutiveDimensionMismatches >= DIMENSION_MISMATCH_CONFIRMATIONS) {
+            return yield* new RepositoryFoundryError({
+                operation: "run-pipeline-stage",
+                detail: "specification cannot assess the requested dimension: repeated private grounded reviews established a dimension mismatch",
+                cause: new PipelineStageError({
+                    stage: STAGE,
+                    detail: "repeated private grounded reviews established that the authentic change does not fit the requested dimension",
+                    terminal: true
+                }),
+                generationRejection: {
+                    code: "specification-dimension-mismatch",
+                    completedRevisions: revisions
+                }
+            });
+        }
+        // A bounded capability returns its real review/checkpoint to the orchestrator,
+        // not a fabricated acceptance or an unbounded hidden revision waterfall.
+        if (input.maximumReviewRounds !== undefined &&
+            sequence - startingSequence + 1 >= input.maximumReviewRounds) {
+            return checkpoint;
+        }
+        previousVisible = visible;
+        priorReviewFeedback = publicReviewFeedback(critic.value);
+        revisions += 1;
+    }
+});
+/** Legacy callers still require and preserve their qualified seed checkpoint. */
+export const runPipelineSpecStageV1 = (input) => {
+    const seedCheckpoint = input.checkpoints.seed;
+    return seedCheckpoint === undefined
+        ? Effect.fail(failure("spec stage requires an accepted seed checkpoint"))
+        : draftPipelineSpecificationV1({
+            ...input,
+            seed: seedCheckpoint.seed,
+            parentDigest: checkpointDigestV1(seedCheckpoint)
+        });
+};