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

package/dist/services/case-authoring/service.js

@@ -0,0 +1,1456 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { captureGitTreeSnapshotV1, readGitTreeFileV1 } from "../../adapters/git-task-history.js";
+import { RepositoryFoundryError } from "../../errors.js";
+import { repositoryFoundryRoleOutputCeilingV1 } from "../../repository-foundry-plan-protocol.js";
+import { parseRepositorySpecificationContractFactsProposalV1, REPOSITORY_SPECIFICATION_CONTRACT_FACTS_MAXIMUM_QUESTIONS, renderRepositorySpecificationContractFactV1, RepositorySpecificationContractFactClarificationV1, RepositorySpecificationContractFactReviewV1, RepositorySpecificationContractFactsProposalV1, repositorySpecificationContractFactsPacketV1, repositorySpecificationContractFactsScopeV1 } from "../../repository-specification-contract-facts-protocol.js";
+import { RepositorySpecificationBehaviorCoverageV1, RepositorySpecificationCritiqueAxisV1, RepositorySpecificationDimensionFitV1, RepositorySpecificationReferenceCompatibilityV1, RepositorySpecificationReferenceScopeV1 } from "../../repository-specification-critique-protocol.js";
+import { RepositoryFoundryLanguageModel } from "../language-model/service.js";
+import { critiqueRepositoryTaskSpecificationV1 } from "../specification-critic/service.js";
+const RepositoryAnalysisOutput = 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),
+    referenceScope: Schema.optionalKey(RepositorySpecificationReferenceScopeV1)
+});
+const RepositorySpecificationOutput = Schema.Struct({
+    requestText: Schema.String,
+    constraints: Schema.Array(Schema.String)
+});
+const RepositorySpecificationReviewOutput = Schema.Struct({
+    verdict: Schema.Literals(["sufficient", "insufficient"]),
+    detail: Schema.String,
+    criticalBehaviorCoverage: Schema.Array(RepositorySpecificationBehaviorCoverageV1),
+    dimensionFit: Schema.optionalKey(RepositorySpecificationDimensionFitV1),
+    referenceCompatibility: Schema.optionalKey(RepositorySpecificationReferenceCompatibilityV1),
+    findings: Schema.Array(Schema.Struct({
+        axis: RepositorySpecificationCritiqueAxisV1,
+        severity: Schema.Literals(["blocker", "warning"]),
+        detail: Schema.String
+    }))
+});
+// These schemas are selected only by the immutable facts marker. The legacy
+// schemas, prompts, operation IDs, and serialized inputs above remain unchanged.
+const RepositoryContractFactsAnalysisOutput = 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),
+    referenceScope: RepositorySpecificationReferenceScopeV1,
+    contractFacts: RepositorySpecificationContractFactsProposalV1
+}).annotate({ parseOptions: { onExcessProperty: "error" } });
+const RepositoryContractFactsReviewOutput = Schema.Struct({
+    verdict: Schema.Literals(["sufficient", "insufficient"]),
+    detail: Schema.String,
+    criticalBehaviorCoverage: Schema.Array(RepositorySpecificationBehaviorCoverageV1),
+    dimensionFit: Schema.optionalKey(RepositorySpecificationDimensionFitV1),
+    referenceCompatibility: Schema.optionalKey(RepositorySpecificationReferenceCompatibilityV1),
+    findings: Schema.Array(Schema.Struct({
+        axis: RepositorySpecificationCritiqueAxisV1,
+        severity: Schema.Literals(["blocker", "warning"]),
+        detail: Schema.String
+    })),
+    contractFactReview: RepositorySpecificationContractFactReviewV1
+}).annotate({ parseOptions: { onExcessProperty: "error" } });
+const REFERENCE_ANALYST_INSTRUCTIONS = `This historical benchmark has private, complete pinned before/after
+implementation and historical-test evidence. Treat commit subjects and mechanically inferred targetBehavior
+as candidate scope, not authoritative specifications. Identify the actual observable change and the boundaries
+the reference preserves. In particular, a broad input category must not silently include subcategories that
+the reference explicitly bypasses. Return referenceScope with concrete changed/preserved behavioral clauses,
+each citing valid sourceId and one-based inclusive line ranges in both before and after evidence. Cover every
+critical seed requirement and all relevant eligibility/preservation boundaries. unresolvedQuestions must list
+material questions the evidence cannot settle. Focus on the authentic local delta and its necessary preservation
+boundaries, not a complete audit of every provider, endpoint, or downstream consumer in the repository.
+Distinguish unknowns that affect the required observable change from general integration questions outside
+the visible task. The private compatibility critic will determine whether each question must be answered
+for this task. Do not invent behavior or infer intent merely from a commit subject.
+All summary, behavior, constraint, risk, and scope description strings must be public issue-style language,
+without code, commit IDs, evidence IDs, historical test contents, or implementation instructions. Evidence
+references belong only in referenceScope.clauses[].evidence. Select relevantPaths from pre-change inventory.`;
+const REFERENCE_CRITIC_INSTRUCTIONS = `You also own private reference compatibility. Independently compare
+every visible requirement against the supplied complete pinned after implementation and historical tests,
+including eligibility predicates, bypasses, preservation boundaries, and cross-file integration. The analyst's
+scope and the historical commit subject are hypotheses, never proof. A requirement contradicting the pinned
+reference makes this historical benchmark invalid even if the visible prose is otherwise clear.
+Return referenceCompatibility with exactly one scopeCoverage record per supplied behavioralScope id, and
+concrete after-source line references. Mark contradictory or uncertain coverage as verdict insufficient and
+an unsupported-assumption blocker. Overall compatible is allowed only if ALL visible requirements are
+supported by pinned evidence, every scope clause is correctly represented, and no task-relevant ambiguity is unresolved.
+For each private pendingQuestions entry, return exactly one questionResolutions record with its questionId.
+Use answered only with concrete after-source evidence that settles the question. Use not-required only when
+the question affects NO required behavioralScope clause and NO visible obligation: affectedScopeIds must
+then be empty and visibleScopeExclusion must quote exact visible task text and explain why that bounded
+scope excludes the question. A broad integration unknown is not automatically a task blocker, but never
+excuse uncertainty about eligibility, parsing, errors, preservation, or integration that the visible task
+actually requires. Use unresolved if a task-relevant question cannot be settled; that blocks approval.
+List all affected scope IDs for relevant questions. Question IDs belong only in questionResolutions records,
+never in behavioral review prose. A writer revision changes neither the questions nor their IDs: reassess
+every question against each revised visible task independently.
+Review details and findings are behavioral feedback for a writer: never quote private code, commit IDs,
+evidence IDs, historical test contents, or prescribe an implementation. Evidence IDs belong only in the
+referenceCompatibility evidence records. Do not repair the task or see the other critic's output.`;
+const SPECIFICATION_REVISION_INSTRUCTIONS = `This is a bounded specification revision. Revise your previous
+visible task to resolve every supplied behavioral review finding against the evidence-grounded observable
+scope. Remove unsupported requirements, state eligibility and preservation boundaries precisely, and retain
+all authentic critical behavior. Do not widen scope to fit a dimension. You receive no private after-code or
+reference patch; do not infer or mention one. Return the same requestText and constraints object.`;
+const CONTRACT_FACTS_ANALYST_INSTRUCTIONS = `Return contractFacts version 1 with explicit public behavioral
+facts for every referenceScope clause. Use behavior facts for observable obligations, closed-set facts when a
+complete vocabulary or alternative set matters, and eligibility facts for decisions with distinct inside/outside
+behavior. A closed set must enumerate its COMPLETE task-relevant members, applicability, and outside behavior.
+Do not replace those facts with circular words such as supported, recognized, valid, or appropriate. Each fact
+must cite concrete pinned source evidence. Preserve public protocol literals as behavioral values, but never
+copy private code, internal identifiers, historical test contents, or implementation steps. Describe THIS TASK'S
+local compatibility policy, not a universal provider policy. Do not invent an external capability claim.
+Keep fact and scope IDs short and stable. At most 64 facts, 128 members per closed set, 2000 characters per
+behavior field, 256 characters per member, and 8 evidence references per fact. The full public packet plus
+rendered scope must fit 32768 UTF-8 bytes. Do not truncate a set or silently drop an obligation to fit.
+Your packet is a proposal; independent critics, not your own confidence or citations, determine sufficiency.`;
+const CONTRACT_FACTS_WRITER_INSTRUCTIONS = `The supplied contractFacts packet is a proposed explicit local
+task contract. Its facts will also be rendered by the host into candidate-visible constraints and independently
+reviewed with your text. Write compatible issue-style prose; do not omit, contradict, enlarge, or invent a
+closed set or eligibility rule. Do not call this a universal provider policy. You receive no private evidence,
+clarification records, source IDs, or reference implementation. Return only requestText and constraints.`;
+const CONTRACT_FACTS_REVIEW_INSTRUCTIONS = `Return contractFactReview for the exact supplied contractFacts.digest.
+Return exactly one scopeChecks record per behavioralScope id, listing exactly all supplied fact IDs for that
+scope. Complete is a substantive completeness judgment, not a citation or shape check. Check the actual
+assembled visible task, including its host-rendered constraints. Consider omitted alternatives, applicability,
+eligibility exceptions, outside-set treatment, and necessary preservation behavior, rather than only checking
+the listed examples. Mark missing-facts, contradictory, or uncertain and verdict insufficient when the PACKET
+itself lacks a necessary fact or states an unsupported fact. For every such scope emit a concise structured
+clarificationRequests entry (scopeId, affected factIds, reason, question). Request a complete behavioral rule,
+not another isolated counterexample. Do not infer missing policy from general provider knowledge.
+If the PACKET is adequate but the WRITER'S prose omits or contradicts it, keep the packet check complete,
+reject the visible task in ordinary findings, and do not request analyst clarification merely to rewrite prose.
+Maximum 32 scope checks, 600 characters per check detail, 8 evidence references per check, 16 clarification
+requests, and 800 characters per question. Scope check details and questions must be public behavior prose,
+without private code, source IDs, reference commit IDs, test contents, or implementation instructions.`;
+const CONTRACT_FACTS_REFERENCE_REVIEW_INSTRUCTIONS = `Independently derive the task-relevant distinctions from
+the complete pinned after implementation and declared task domain BEFORE comparing them with the analyst's
+packet. The supplied fact list and apparent completeness are hypotheses, never proof: actively identify an
+omitted member or default branch even when every supplied fact has a plausible citation. For each scopeCheck
+cite after-source evidence that supports both the stated rules and their completeness. Do not approve a false
+fact merely because its citation points to existing lines. Distinguish task-local compatibility from external
+provider correctness. Do not force incidental behavior outside a justified declared task domain into the task.
+You do not see the other current-round critic's response. Reassess every fact after clarification.`;
+const CONTRACT_FACTS_CLARIFICATION_INSTRUCTIONS = `You are the private repository analyst answering bounded
+contract-fact clarification requests. Return version 1, a COMPLETE replacement facts array, and exactly one
+resolutions record per supplied requestId. Preserve all unaffected facts and the original frozen scope IDs.
+The supplied privateContractFacts is the exact private repair base: copy unaffected facts and their evidence
+records unchanged rather than choosing new citations for facts that were not questioned.
+Resolve the whole missing rule or closed set, not just the example named by a critic. Each answered request
+must reference facts in its own scope and concrete evidence already present in privateReferenceEvidence.
+Return unresolved when the pinned evidence cannot settle the question; do not invent provider knowledge,
+fetch other sources, widen the task, rewrite the visible request, or supply implementation advice.
+You may correct false facts and add missing facts within an existing scope, but never silently drop unrelated
+obligations. Do not place request IDs in public fact fields. ${CONTRACT_FACTS_ANALYST_INSTRUCTIONS}`;
+const ANALYST_INSTRUCTIONS = `You are the repository-analysis role in a coding benchmark foundry.
+Use only the supplied pre-change repository excerpts and mechanically established behavior evidence.
+Identify the user-observable behavior, integration boundaries, preservation constraints, and ambiguity risks.
+When requestedDimension is supplied, identify how the authentic seed exercises that area or explain why it does
+not fit. Do not invent a different task merely to match the requested dimension. Preserve every critical seed behavior.
+Select at most eight relevantPaths from the supplied contextPathInventory. Select unchanged public surfaces,
+protocols, manifests, or bound tests when they are necessary to understand cross-file integration.
+Do not write the task, tests, reference solution, or implementation advice.
+Do not treat the historical patch as normative. Return only the requested structured object.`;
+const SPECIFICATION_INSTRUCTIONS = `You are the specification-writer role in a coding benchmark foundry.
+Write a realistic issue-style request for a coding agent working in the supplied pre-change checkout.
+State user-observable behavior and necessary preservation constraints, but do not mention hidden tests,
+the reference patch, post-change code, mutations, graders, or exact implementation steps.
+The task must allow multiple behaviorally correct implementations and explicitly cover every supplied critical
+seed behavior, with faithful paraphrases allowed. When requestedDimension is supplied, assess that area through
+the authentic seed change without inventing unrelated requirements. Return only the requested structured object.`;
+const criticInstructions = (perspective) => `You are an independent ${perspective} critic in a coding benchmark foundry.
+Judge whether a capable coding agent can solve the visible task from the pre-change repository context
+without seeing hidden tests or the historical patch. Look for unavailable context, multiple legitimate
+interpretations, hidden-answer leakage, unrealistic phrasing, and unsupported assumptions.
+Return exactly one criticalBehaviorCoverage record for every supplied critical targetBehavior id. Mark a behavior
+covered only when the visible request states its complete requirement; semantic paraphrases are allowed. An omitted
+or uncertain critical requirement is a blocker and requires verdict insufficient, even if the rest of the task is clear.
+When requestedDimension is supplied, return dimensionFit for that exact request with concrete pre-change evidencePaths.
+The task must actually assess that area through the seed change, not merely mention it. Mismatch or uncertainty is
+a blocker and requires verdict insufficient. Do not force a seed to fit an unrelated dimension.
+Do not repair or rewrite the task. Return only the requested structured review.`;
+const boundedExcerpt = (content, remainingBytes) => {
+    if (remainingBytes <= 0)
+        return "";
+    const bytes = Buffer.from(content);
+    if (bytes.byteLength <= remainingBytes)
+        return content;
+    return `${bytes.subarray(0, Math.max(0, remainingBytes - 32)).toString("utf8")}\n[truncated]`;
+};
+const evidencePaths = (seed) => [
+    ...new Set(seed.capabilityEvidence
+        .map((evidence) => evidence.path)
+        .filter((path) => path !== undefined))
+].slice(0, 8);
+const pathWithinRoot = (path, root) => root === "." || path === root || path.startsWith(`${root}/`);
+export const repositoryGenerationContextCandidatesV1 = (input) => {
+    const relationships = new Map();
+    const add = (path, relationship) => {
+        if (path === undefined || path.trim().length === 0)
+            return;
+        const current = relationships.get(path) ?? new Set();
+        current.add(relationship);
+        relationships.set(path, current);
+    };
+    const seedPaths = input.seed.capabilityEvidence
+        .map((evidence) => evidence.path)
+        .filter((path) => path !== undefined);
+    for (const path of seedPaths)
+        add(path, "seed-evidence");
+    const episode = input.map.historyEpisodes.find((candidate) => "changeEpisodeId" in input.seed.source && candidate.id === input.seed.source.changeEpisodeId);
+    for (const changed of episode?.changedPaths ?? []) {
+        add(changed.path, "historical-change");
+        add(changed.previousPath, "historical-previous-path");
+    }
+    const owningPackageIds = new Set(seedPaths.flatMap((path) => {
+        const matches = input.map.packages
+            .filter((entry) => pathWithinRoot(path, entry.path))
+            .sort((left, right) => right.path.length - left.path.length || left.path.localeCompare(right.path));
+        const deepest = matches[0]?.path.length;
+        return deepest === undefined
+            ? []
+            : matches.filter((entry) => entry.path.length === deepest).map((entry) => entry.id);
+    }));
+    const owningPackages = input.map.packages.filter((entry) => owningPackageIds.has(entry.id));
+    for (const owner of owningPackages) {
+        add(owner.manifestPath, "owning-package-manifest");
+    }
+    for (const surface of input.map.publicSurfaces) {
+        if ((surface.packageId !== undefined && owningPackageIds.has(surface.packageId)) ||
+            owningPackages.some((owner) => pathWithinRoot(surface.path, owner.path))) {
+            add(surface.path, "owning-public-surface");
+        }
+    }
+    for (const protocol of input.map.protocols) {
+        if (owningPackages.some((owner) => pathWithinRoot(protocol.path, owner.path))) {
+            add(protocol.path, "owning-protocol");
+        }
+    }
+    const relatedTargetIds = new Set([
+        ...owningPackageIds,
+        ...input.map.publicSurfaces
+            .filter((surface) => surface.packageId !== undefined && owningPackageIds.has(surface.packageId))
+            .map((surface) => surface.id),
+        ...input.map.protocols
+            .filter((protocol) => owningPackages.some((owner) => pathWithinRoot(protocol.path, owner.path)))
+            .map((protocol) => protocol.id)
+    ]);
+    const boundTestIds = new Set(input.map.testBindings
+        .filter((binding) => binding.targetIds.some((targetId) => relatedTargetIds.has(targetId)))
+        .map((binding) => binding.testId));
+    for (const test of input.map.tests) {
+        if (boundTestIds.has(test.id) || seedPaths.includes(test.path)) {
+            add(test.path, "behavior-bound-test");
+        }
+    }
+    return [...relationships.entries()]
+        .map(([path, values]) => ({
+        path,
+        relationships: [...values].sort()
+    }))
+        .sort((left, right) => {
+        const leftSeed = left.relationships.includes("seed-evidence") ? 0 : 1;
+        const rightSeed = right.relationships.includes("seed-evidence") ? 0 : 1;
+        return leftSeed - rightSeed || left.path.localeCompare(right.path);
+    })
+        .slice(0, 64);
+};
+const readContextSources = Effect.fn("CaseAuthoring.readContextSources")(function* (input) {
+    const sources = [];
+    let remainingBytes = input.maximumBytes;
+    for (const path of input.paths.slice(0, input.maximumFiles)) {
+        if (!input.snapshot.files.includes(path) || remainingBytes <= 0)
+            continue;
+        const content = yield* readGitTreeFileV1({
+            snapshot: input.snapshot,
+            path
+        });
+        const bounded = boundedExcerpt(content, Math.min(remainingBytes, input.perFileBytes));
+        if (bounded.length === 0)
+            continue;
+        sources.push({ path, content: bounded });
+        remainingBytes -= Buffer.byteLength(bounded);
+    }
+    return sources;
+});
+const contextFailure = (detail) => new RepositoryFoundryError({
+    operation: "select-generation-context",
+    detail
+});
+export class CaseAuthoring extends Context.Service()("@velum-labs/routekit-eval-setup/CaseAuthoring") {
+}
+export const authorRepositoryCaseSpecificationV1 = Effect.fn("CaseAuthoring.authorSpecification")(function* (input) {
+    if (input.specificationContractFactsVersion !== undefined &&
+        (input.specificationContractFactsVersion !== 1 ||
+            input.maximumSpecificationRevisions === undefined)) {
+        return yield* contextFailure("contract facts require version 1 and an explicit specification revision allowance");
+    }
+    if (input.maximumSpecificationRevisions !== undefined) {
+        const grounded = yield* authorReferenceGroundedSpecification({
+            ...input,
+            maximumSpecificationRevisions: input.maximumSpecificationRevisions
+        });
+        return grounded;
+    }
+    const languageModel = yield* RepositoryFoundryLanguageModel;
+    const dimensionContext = input.requestedDimension === undefined
+        ? {}
+        : { requestedDimension: input.requestedDimension };
+    if (input.requestedDimension !== undefined &&
+        (input.requestedDimension.trim().length === 0 || input.requestedDimension.length > 2000)) {
+        return yield* contextFailure("requested dimension must contain between one and 2000 characters");
+    }
+    const snapshot = yield* captureGitTreeSnapshotV1({
+        repositoryRoot: input.repositoryRoot,
+        requestedRef: input.seed.initialState.commit
+    });
+    const seedEvidencePaths = evidencePaths(input.seed);
+    const excerpts = yield* readContextSources({
+        snapshot,
+        paths: seedEvidencePaths,
+        maximumFiles: 8,
+        maximumBytes: 60_000,
+        perFileBytes: 16_000
+    });
+    const contextPathInventory = repositoryGenerationContextCandidatesV1({
+        map: input.map,
+        seed: input.seed
+    }).filter((candidate) => snapshot.files.includes(candidate.path));
+    const publicEvidence = {
+        ...dimensionContext,
+        seed: {
+            id: input.seed.id,
+            summary: input.seed.summary,
+            source: input.seed.source,
+            targetBehavior: input.seed.targetBehavior,
+            initialCommit: input.seed.initialState.commit
+        },
+        family: {
+            id: input.family.id,
+            capabilityId: input.family.capabilityId,
+            jobStatement: input.family.jobStatement,
+            inputStateFacets: input.family.inputStateFacets,
+            requestedChangeFacets: input.family.requestedChangeFacets,
+            observableFacets: input.family.observableFacets,
+            excludedNearMisses: input.family.excludedNearMisses
+        },
+        excerpts,
+        contextPathInventory
+    };
+    const analysis = yield* languageModel.generateStructured({
+        plan: input.modelPlan,
+        role: "repository-analyst",
+        operationId: `${input.operationId}:repository-analyst`,
+        instructions: ANALYST_INSTRUCTIONS,
+        input: publicEvidence,
+        schemaName: "routekit_repository_analysis_v1",
+        outputSchema: RepositoryAnalysisOutput,
+        maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("repository-analyst")
+    });
+    const selectedPaths = analysis.value.relevantPaths;
+    const availablePaths = new Set(contextPathInventory.map((candidate) => candidate.path));
+    if (selectedPaths.length === 0 ||
+        selectedPaths.length > 8 ||
+        new Set(selectedPaths).size !== selectedPaths.length ||
+        selectedPaths.some((path) => !availablePaths.has(path))) {
+        return yield* contextFailure("repository analyst must select between one and eight unique paths from the bounded context inventory");
+    }
+    const contextPaths = [...new Set([...seedEvidencePaths, ...selectedPaths])];
+    if (contextPaths.length > 12) {
+        return yield* contextFailure("repository analyst selection exceeds the twelve-file generation context bound");
+    }
+    const contextSources = yield* readContextSources({
+        snapshot,
+        paths: contextPaths,
+        maximumFiles: 12,
+        maximumBytes: 80_000,
+        perFileBytes: 20_000
+    });
+    if (contextSources.length !== contextPaths.length ||
+        seedEvidencePaths.some((path) => !contextSources.some((source) => source.path === path))) {
+        return yield* contextFailure("selected generation context is unavailable in the immutable pre-change snapshot");
+    }
+    const authored = yield* languageModel.generateStructured({
+        plan: input.modelPlan,
+        role: "specification-writer",
+        operationId: `${input.operationId}:specification-writer`,
+        instructions: SPECIFICATION_INSTRUCTIONS,
+        input: {
+            ...dimensionContext,
+            targetBehavior: input.seed.targetBehavior,
+            analysis: analysis.value,
+            family: publicEvidence.family,
+            initialCommit: input.seed.initialState.commit,
+            selectedRepositoryContext: contextSources
+        },
+        schemaName: "routekit_repository_specification_v1",
+        outputSchema: RepositorySpecificationOutput,
+        maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-writer")
+    });
+    const visible = {
+        lane: "repository-agent",
+        id: input.caseId,
+        requestText: authored.value.requestText,
+        checkoutCommit: input.seed.initialState.commit,
+        allowedTools: ["read", "search", "edit", "shell", "test"],
+        constraints: [
+            ...new Set([
+                ...authored.value.constraints,
+                "Do not weaken or delete tests to make the task pass.",
+                "Preserve unrelated public behavior."
+            ])
+        ]
+    };
+    const reviewInput = {
+        ...dimensionContext,
+        targetBehavior: input.seed.targetBehavior,
+        visible,
+        analysis: analysis.value,
+        family: publicEvidence.family,
+        initialRepositoryExcerpts: contextSources
+    };
+    const [criticA, criticB] = yield* Effect.all([
+        languageModel.generateStructured({
+            plan: input.modelPlan,
+            role: "specification-critic-a",
+            operationId: `${input.operationId}:specification-critic-a`,
+            instructions: criticInstructions("solver"),
+            input: reviewInput,
+            schemaName: "routekit_repository_specification_review_v1",
+            outputSchema: RepositorySpecificationReviewOutput,
+            maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-critic-a")
+        }),
+        languageModel.generateStructured({
+            plan: input.modelPlan,
+            role: "specification-critic-b",
+            operationId: `${input.operationId}:specification-critic-b`,
+            instructions: criticInstructions("ambiguity"),
+            input: reviewInput,
+            schemaName: "routekit_repository_specification_review_v1",
+            outputSchema: RepositorySpecificationReviewOutput,
+            maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-critic-b")
+        })
+    ], { concurrency: 2 });
+    const reviews = [
+        {
+            reviewerId: criticA.call.operationId,
+            reviewerKind: "independent-solver",
+            independentlyProduced: true,
+            ...criticA.value
+        },
+        {
+            reviewerId: criticB.call.operationId,
+            reviewerKind: "model-critic",
+            independentlyProduced: true,
+            ...criticB.value
+        }
+    ];
+    const critique = yield* critiqueRepositoryTaskSpecificationV1({
+        repositoryRoot: input.repositoryRoot,
+        seed: input.seed,
+        family: input.family,
+        visible,
+        reviews,
+        ...dimensionContext
+    });
+    if (critique.outcome !== "pass") {
+        return yield* contextFailure(`generated specification failed independent review: ${critique.rejectionReasons.join("; ")}`);
+    }
+    const result = {
+        version: 1,
+        caseId: input.caseId,
+        analysis: analysis.value,
+        contextSources,
+        visible,
+        reviews,
+        modelCalls: [analysis.call, authored.call, criticA.call, criticB.call]
+    };
+    return result;
+});
+// Absence is explicit for added/deleted files. Present files are never excerpted: an
+// incomplete eligibility predicate is insufficient evidence for a historical task.
+const readCompleteReferenceSources = Effect.fn("CaseAuthoring.readCompleteReferenceSources")(function* (input) {
+    const paths = [...new Set(input.paths)].sort();
+    if (paths.length === 0 || paths.length > 24) {
+        return yield* contextFailure("reference grounding requires between one and 24 complete source paths");
+    }
+    const sources = [];
+    let totalBytes = 0;
+    for (const [index, path] of paths.entries()) {
+        if (!input.before.files.includes(path) && !input.after.files.includes(path)) {
+            return yield* contextFailure("required reference-grounding source is unavailable in both pinned snapshots");
+        }
+        for (const phase of ["before", "after"]) {
+            const snapshot = input[phase];
+            const content = snapshot.files.includes(path)
+                ? yield* readGitTreeFileV1({ snapshot, path })
+                : null;
+            const bytes = content === null ? 0 : Buffer.byteLength(content);
+            totalBytes += bytes;
+            if (bytes > 96_000 || totalBytes > 256_000) {
+                return yield* contextFailure("complete reference-grounding sources exceed the 96000-byte file or 256000-byte combined bound; no truncated evidence was submitted");
+            }
+            sources.push({
+                sourceId: `private-reference-${phase}-${String(index)}`,
+                phase,
+                path,
+                content
+            });
+        }
+    }
+    return sources;
+});
+const referenceEvidenceValid = (evidence, sources, phase) => {
+    const source = sources.find((candidate) => candidate.sourceId === evidence.sourceId);
+    return (source !== undefined &&
+        source.content !== null &&
+        (phase === undefined || source.phase === phase) &&
+        Number.isSafeInteger(evidence.startLine) &&
+        Number.isSafeInteger(evidence.endLine) &&
+        evidence.startLine >= 1 &&
+        evidence.endLine >= evidence.startLine &&
+        evidence.endLine <= source.content.split("\n").length &&
+        source.content
+            .split("\n")
+            .slice(evidence.startLine - 1, evidence.endLine)
+            .join("\n")
+            .trim().length > 0);
+};
+const referenceScopeFailures = (scope, sources, seed) => {
+    if (scope === undefined)
+        return ["private analyst did not return evidence-grounded behavioral scope"];
+    const knownBehaviorIds = new Set(seed.targetBehavior.map((behavior) => behavior.id));
+    if (scope.clauses.length === 0 ||
+        scope.clauses.length > 32 ||
+        new Set(scope.clauses.map((clause) => clause.id)).size !== scope.clauses.length ||
+        !scope.clauses.some((clause) => clause.kind === "changed") ||
+        scope.unresolvedQuestions.length > 16 ||
+        scope.unresolvedQuestions.some((question) => question.trim().length === 0 || question.length > 8000) ||
+        scope.clauses.some((clause) => clause.id.trim().length === 0 ||
+            clause.description.trim().length === 0 ||
+            clause.behaviorIds.length === 0 ||
+            new Set(clause.behaviorIds).size !== clause.behaviorIds.length ||
+            clause.behaviorIds.some((id) => !knownBehaviorIds.has(id)) ||
+            clause.evidence.length === 0 ||
+            clause.evidence.some((entry) => !referenceEvidenceValid(entry, sources)) ||
+            !clause.evidence.some((entry) => referenceEvidenceValid(entry, sources, "after")) ||
+            !clause.evidence.some((entry) => referenceEvidenceValid(entry, sources, "before"))) ||
+        seed.targetBehavior.some((behavior) => !scope.clauses.some((clause) => clause.behaviorIds.includes(behavior.id)))) {
+        return [
+            "private analyst scope is incomplete, malformed, or lacks valid pinned source line evidence for every critical behavior"
+        ];
+    }
+    return [];
+};
+const referenceCompatibilityFailures = (review, scope, sources, pendingQuestions, visible) => {
+    const compatibility = review.referenceCompatibility;
+    if (compatibility === undefined)
+        return ["reference compatibility review is missing"];
+    const ids = compatibility.scopeCoverage.map((coverage) => coverage.scopeId);
+    if (compatibility.outcome !== "compatible" ||
+        compatibility.detail.trim().length === 0 ||
+        ids.length !== scope.clauses.length ||
+        new Set(ids).size !== ids.length ||
+        scope.clauses.some((clause) => !ids.includes(clause.id)) ||
+        compatibility.scopeCoverage.some((coverage) => coverage.outcome !== "supported" ||
+            coverage.detail.trim().length === 0 ||
+            coverage.evidence.length === 0 ||
+            coverage.evidence.some((entry) => !referenceEvidenceValid(entry, sources, "after")))) {
+        return [
+            "visible requirements are contradictory, uncertain, or lack complete pinned reference compatibility evidence"
+        ];
+    }
+    const resolutions = compatibility.questionResolutions ?? [];
+    const questionIds = new Set(pendingQuestions.map((question) => question.id));
+    const resolutionIds = resolutions.map((resolution) => resolution.questionId);
+    const visibleFields = visible.lane === "repository-agent"
+        ? [visible.requestText, ...visible.constraints]
+        : [visible.request.bodyJson];
+    if (resolutions.length !== questionIds.size ||
+        new Set(resolutionIds).size !== resolutionIds.length ||
+        resolutions.some((resolution) => !questionIds.has(resolution.questionId) ||
+            resolution.outcome === "unresolved" ||
+            resolution.detail.trim().length === 0 ||
+            new Set(resolution.affectedScopeIds).size !== resolution.affectedScopeIds.length ||
+            resolution.affectedScopeIds.some((id) => !scope.clauses.some((clause) => clause.id === id)) ||
+            resolution.evidence.some((entry) => !referenceEvidenceValid(entry, sources, "after")) ||
+            (resolution.outcome === "answered" && resolution.evidence.length === 0) ||
+            (resolution.outcome === "not-required" &&
+                (resolution.affectedScopeIds.length > 0 ||
+                    resolution.visibleScopeExclusion === undefined ||
+                    resolution.visibleScopeExclusion.quotation.trim().length === 0 ||
+                    !visibleFields.some((field) => field.includes(resolution.visibleScopeExclusion.quotation)) ||
+                    resolution.visibleScopeExclusion.rationale.trim().length === 0)))) {
+        return [
+            "private analyst questions require complete evidence-backed answers or justified visible-scope exclusions; unresolved or malformed resolutions block approval"
+        ];
+    }
+    return [];
+};
+// This classifies an unsuitable target, never an admissible specification. Both
+// independently requested critics must agree on the exact requested dimension
+// after establishing all authentic critical behavior and grounded scope.
+// Remaining reference uncertainty still blocks admission; it does not require
+// more prose repair of a grounded, unanimous dimension mismatch. This rejection
+// does not establish that every unanswered reference question is ancillary.
+const hasIndependentGroundedDimensionMismatch = (input) => {
+    if (input.requestedDimension === undefined || input.reviews.length !== 2)
+        return false;
+    const criticalIds = new Set(input.targetBehavior.filter((behavior) => behavior.critical).map((behavior) => behavior.id));
+    if (criticalIds.size === 0)
+        return false;
+    const reviewerIds = [
+        `${input.operationPrefix}:specification-critic-a`,
+        `${input.operationPrefix}:specification-critic-b`
+    ];
+    const reviewerKinds = ["independent-solver", "model-critic"];
+    if (new Set(input.reviews.map((review) => review.reviewerId)).size !== 2 ||
+        !input.reviews.every((review, index) => {
+            const fit = review.dimensionFit;
+            const coverage = review.criticalBehaviorCoverage;
+            if (!review.independentlyProduced ||
+                review.reviewerId !== reviewerIds[index] ||
+                review.reviewerKind !== reviewerKinds[index] ||
+                fit === undefined ||
+                fit.requestedDimension !== input.requestedDimension ||
+                fit.outcome !== "mismatch" ||
+                fit.detail.trim().length === 0 ||
+                fit.evidencePaths.length === 0 ||
+                fit.evidencePaths.some((path) => !input.before.files.includes(path)) ||
+                coverage === undefined)
+                return false;
+            const ids = coverage.map((entry) => entry.behaviorId);
+            return (ids.length === criticalIds.size &&
+                new Set(ids).size === ids.length &&
+                ids.every((id) => criticalIds.has(id)) &&
+                coverage.every((entry) => entry.outcome === "covered" && entry.detail.trim().length > 0));
+        }))
+        return false;
+    const compatibility = input.reviews[1].referenceCompatibility;
+    if (compatibility === undefined ||
+        compatibility.outcome === "contradictory" ||
+        compatibility.detail.trim().length === 0 ||
+        input.scope.clauses.length === 0)
+        return false;
+    const scopeIds = compatibility.scopeCoverage.map((coverage) => coverage.scopeId);
+    return (scopeIds.length === input.scope.clauses.length &&
+        new Set(scopeIds).size === scopeIds.length &&
+        input.scope.clauses.every((clause) => scopeIds.includes(clause.id)) &&
+        compatibility.scopeCoverage.every((coverage) => coverage.outcome === "supported" &&
+            coverage.detail.trim().length > 0 &&
+            coverage.evidence.length > 0 &&
+            coverage.evidence.every((entry) => referenceEvidenceValid(entry, input.sources, "after"))));
+};
+// The only reference-derived material allowed across the public author boundary is
+// behavior prose. This catches verbatim private identifiers/code in that projection;
+// structured provenance and complete after sources are never copied into it.
+const containsPrivateReferenceMaterial = (value, sources, referenceCommit) => {
+    const text = JSON.stringify(value);
+    if (text.includes("private-reference-question-") ||
+        text.includes(referenceCommit) ||
+        text.includes(referenceCommit.slice(0, 12)) ||
+        sources.some((source) => text.includes(source.sourceId)))
+        return true;
+    const beforeLines = new Set(sources
+        .filter((source) => source.phase === "before")
+        .flatMap((source) => source.content?.split("\n").map((line) => line.trim()) ?? []));
+    return sources
+        .filter((source) => source.phase === "after")
+        .some((source) => source.content?.split("\n").some((line) => {
+        const normalized = line.trim();
+        return (normalized.length >= 32 &&
+            !beforeLines.has(normalized) &&
+            text.includes(JSON.stringify(normalized).slice(1, -1)));
+    }) === true);
+};
+const assertBoundedReferenceInput = (value) => Buffer.byteLength(JSON.stringify(value)) <= 512_000
+    ? Effect.void
+    : Effect.fail(contextFailure("complete reference-grounded authoring input exceeds 512000 bytes; no evidence was truncated"));
+const authorReferenceGroundedSpecification = Effect.fn("CaseAuthoring.authorReferenceGroundedSpecification")(function* (input) {
+    const maximumRevisions = input.maximumSpecificationRevisions;
+    if (!Number.isSafeInteger(maximumRevisions) || maximumRevisions < 0 || maximumRevisions > 2) {
+        return yield* contextFailure("maximum specification revisions must be an integer between zero and two");
+    }
+    if (input.seed.referenceCommit === undefined ||
+        !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(input.seed.referenceCommit)) {
+        return yield* contextFailure("reference-grounded authoring requires a pinned full reference commit");
+    }
+    if (input.requestedDimension !== undefined &&
+        (input.requestedDimension.trim().length === 0 || input.requestedDimension.length > 2000)) {
+        return yield* contextFailure("requested dimension must contain between one and 2000 characters");
+    }
+    const languageModel = yield* RepositoryFoundryLanguageModel;
+    const dimensionContext = input.requestedDimension === undefined ? {} : { requestedDimension: input.requestedDimension };
+    const before = yield* captureGitTreeSnapshotV1({
+        repositoryRoot: input.repositoryRoot,
+        requestedRef: input.seed.initialState.commit
+    });
+    const after = yield* captureGitTreeSnapshotV1({
+        repositoryRoot: input.repositoryRoot,
+        requestedRef: input.seed.referenceCommit
+    });
+    if (before.commit === after.commit) {
+        return yield* contextFailure("reference grounding requires distinct before and after commits");
+    }
+    const episode = input.map.historyEpisodes.find((candidate) => "changeEpisodeId" in input.seed.source && candidate.id === input.seed.source.changeEpisodeId);
+    const requiredPaths = [
+        ...new Set([
+            ...input.seed.capabilityEvidence.flatMap((evidence) => evidence.path === undefined ? [] : [evidence.path]),
+            ...input.seed.targetBehavior.flatMap((behavior) => behavior.evidence.flatMap((evidence) => evidence.path === undefined ? [] : [evidence.path])),
+            ...input.map.tests
+                .filter((entry) => input.seed.candidateTestIds.includes(entry.id))
+                .map((entry) => entry.path),
+            ...(episode?.changedPaths.flatMap((entry) => entry.previousPath === undefined ? [entry.path] : [entry.previousPath, entry.path]) ?? [])
+        ])
+    ];
+    let privateSources = yield* readCompleteReferenceSources({ before, after, paths: requiredPaths });
+    const contextPathInventory = repositoryGenerationContextCandidatesV1({
+        map: input.map,
+        seed: input.seed
+    }).filter((candidate) => before.files.includes(candidate.path));
+    const familyContext = {
+        id: input.family.id,
+        capabilityId: input.family.capabilityId,
+        jobStatement: input.family.jobStatement,
+        inputStateFacets: input.family.inputStateFacets,
+        requestedChangeFacets: input.family.requestedChangeFacets,
+        observableFacets: input.family.observableFacets,
+        excludedNearMisses: input.family.excludedNearMisses
+    };
+    const analystInput = {
+        ...dimensionContext,
+        targetBehavior: input.seed.targetBehavior,
+        family: familyContext,
+        contextPathInventory,
+        privateReferenceEvidence: {
+            beforeCommit: before.commit,
+            referenceCommit: after.commit,
+            sources: privateSources
+        }
+    };
+    yield* assertBoundedReferenceInput(analystInput);
+    const analysisRequest = {
+        plan: input.modelPlan,
+        role: "repository-analyst",
+        operationId: `${input.operationId}:repository-analyst`,
+        instructions: `${REFERENCE_ANALYST_INSTRUCTIONS}\nSelect at most eight relevantPaths from contextPathInventory. Preserve authentic requestedDimension fit without inventing a different task. Each scope clause must name its related target behaviorIds; preserve the IDs while grounding the actual observable requirement.`,
+        input: analystInput,
+        schemaName: "routekit_repository_analysis_v1",
+        outputSchema: RepositoryAnalysisOutput,
+        maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("repository-analyst")
+    };
+    const analysis = yield* (input.specificationContractFactsVersion === 1
+        ? languageModel.generateStructured({
+            ...analysisRequest,
+            instructions: `${analysisRequest.instructions}\n\n${CONTRACT_FACTS_ANALYST_INSTRUCTIONS}`,
+            schemaName: "routekit_repository_analysis_contract_facts_v1",
+            outputSchema: RepositoryContractFactsAnalysisOutput
+        })
+        : languageModel.generateStructured(analysisRequest));
+    const scopeErrors = referenceScopeFailures(analysis.value.referenceScope, privateSources, input.seed);
+    if (scopeErrors.length > 0 || analysis.value.referenceScope === undefined) {
+        return yield* contextFailure(scopeErrors.join("; "));
+    }
+    const scope = analysis.value.referenceScope;
+    const pendingQuestions = scope.unresolvedQuestions.map((question, index) => ({
+        id: `private-reference-question-${String(index + 1)}`,
+        question
+    }));
+    const availablePaths = new Set(contextPathInventory.map((candidate) => candidate.path));
+    const selectedPaths = analysis.value.relevantPaths;
+    if (selectedPaths.length === 0 ||
+        selectedPaths.length > 8 ||
+        new Set(selectedPaths).size !== selectedPaths.length ||
+        selectedPaths.some((path) => !availablePaths.has(path))) {
+        return yield* contextFailure("repository analyst must select between one and eight unique paths from the bounded context inventory");
+    }
+    const contextPaths = [
+        ...new Set([...requiredPaths.filter((path) => before.files.includes(path)), ...selectedPaths])
+    ];
+    if (contextPaths.length > 12) {
+        return yield* contextFailure("complete pre-change generation context exceeds twelve files");
+    }
+    privateSources = yield* readCompleteReferenceSources({
+        before,
+        after,
+        paths: [...requiredPaths, ...selectedPaths]
+    });
+    // IDs derive from sorted path ordinals. Reloading with selected paths must not
+    // rebind the analyst's evidence to another file.
+    const analystSources = analystInput.privateReferenceEvidence.sources;
+    privateSources = privateSources.map((source) => ({
+        ...source,
+        sourceId: analystSources.find((entry) => entry.phase === source.phase && entry.path === source.path)
+            ?.sourceId ??
+            `private-reference-selected-${source.phase}-${String(contextPaths.indexOf(source.path))}`
+    }));
+    const contextSources = privateSources
+        .filter((source) => source.phase === "before" && source.content !== null && contextPaths.includes(source.path))
+        .map((source) => ({ path: source.path, content: source.content }));
+    const publicAnalysis = {
+        summary: analysis.value.summary,
+        userObservableBehaviors: analysis.value.userObservableBehaviors,
+        constraints: analysis.value.constraints,
+        risks: analysis.value.risks,
+        relevantPaths: analysis.value.relevantPaths
+    };
+    const behavioralScope = scope.clauses.map((clause) => ({
+        id: clause.id,
+        kind: clause.kind,
+        behaviorIds: clause.behaviorIds,
+        description: clause.description
+    }));
+    if (containsPrivateReferenceMaterial({ publicAnalysis, behavioralScope }, privateSources, after.commit)) {
+        return yield* contextFailure("private reference material leaked into the analyst's public behavioral projection");
+    }
+    if (input.specificationContractFactsVersion === 1) {
+        const markedAnalysis = yield* Effect.try({
+            try: () => Schema.decodeUnknownSync(RepositoryContractFactsAnalysisOutput, {
+                onExcessProperty: "error"
+            })(analysis.value),
+            catch: () => contextFailure("marked analyst did not return strict contract facts")
+        });
+        return yield* authorContractFactsSpecification({
+            request: input,
+            analysis: markedAnalysis,
+            analystCall: analysis.call,
+            before,
+            after,
+            privateSources,
+            contextSources,
+            publicAnalysis,
+            familyContext
+        });
+    }
+    const groundedTargetBehavior = input.seed.targetBehavior.map((behavior) => ({
+        ...behavior,
+        description: scope.clauses
+            .filter((clause) => clause.behaviorIds.includes(behavior.id))
+            .map((clause) => clause.description)
+            .join(" ")
+    }));
+    const publicContext = {
+        ...dimensionContext,
+        targetBehavior: groundedTargetBehavior,
+        analysis: publicAnalysis,
+        behavioralScope,
+        family: familyContext
+    };
+    const history = [];
+    const modelCalls = [analysis.call];
+    let revisionFeedback = [];
+    let previousVisible;
+    for (let sequence = 0; sequence <= maximumRevisions; sequence += 1) {
+        const operationPrefix = sequence === 0
+            ? input.operationId
+            : `${input.operationId}:specification-revision:${String(sequence)}`;
+        const writerInput = {
+            ...publicContext,
+            initialCommit: before.commit,
+            selectedRepositoryContext: contextSources,
+            ...(sequence === 0 ? {} : { previousVisible, behavioralReviewFeedback: revisionFeedback })
+        };
+        yield* assertBoundedReferenceInput(writerInput);
+        const authored = yield* languageModel.generateStructured({
+            plan: input.modelPlan,
+            role: "specification-writer",
+            operationId: `${operationPrefix}:specification-writer`,
+            instructions: `${SPECIFICATION_INSTRUCTIONS}\nThe supplied behavioralScope is grounded in the repository's observable behavior. State its eligibility and preservation boundaries explicitly. Mechanically inferred targetBehavior descriptions are hypotheses; preserve their authentic requirements without broadening the grounded scope.${sequence === 0 ? "" : `\n${SPECIFICATION_REVISION_INSTRUCTIONS}`}`,
+            input: writerInput,
+            schemaName: "routekit_repository_specification_v1",
+            outputSchema: RepositorySpecificationOutput,
+            maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-writer")
+        });
+        modelCalls.push(authored.call);
+        const visible = {
+            lane: "repository-agent",
+            id: input.caseId,
+            requestText: authored.value.requestText,
+            checkoutCommit: before.commit,
+            allowedTools: ["read", "search", "edit", "shell", "test"],
+            constraints: [
+                ...new Set([
+                    ...authored.value.constraints,
+                    "Do not weaken or delete tests to make the task pass.",
+                    "Preserve unrelated public behavior."
+                ])
+            ]
+        };
+        if (containsPrivateReferenceMaterial(visible, privateSources, after.commit)) {
+            return yield* contextFailure("private reference material leaked into the visible specification");
+        }
+        const reviewInput = { ...publicContext, visible, initialRepositoryExcerpts: contextSources };
+        const privateReviewInput = {
+            ...reviewInput,
+            privateReferenceEvidence: {
+                beforeCommit: before.commit,
+                referenceCommit: after.commit,
+                sources: privateSources,
+                pendingQuestions
+            }
+        };
+        yield* assertBoundedReferenceInput(privateReviewInput);
+        const [criticA, criticB] = yield* Effect.all([
+            languageModel.generateStructured({
+                plan: input.modelPlan,
+                role: "specification-critic-a",
+                operationId: `${operationPrefix}:specification-critic-a`,
+                instructions: `${criticInstructions("solver")}\nThe supplied behavioralScope defines authentic eligibility and preservation boundaries. Check the visible task covers every grounded clause, retaining critical behavior IDs without expanding scope from a mechanically inferred summary. You remain blind to the reference implementation.`,
+                input: reviewInput,
+                schemaName: "routekit_repository_specification_review_v1",
+                outputSchema: RepositorySpecificationReviewOutput,
+                maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-critic-a")
+            }),
+            languageModel.generateStructured({
+                plan: input.modelPlan,
+                role: "specification-critic-b",
+                operationId: `${operationPrefix}:specification-critic-b`,
+                instructions: `${criticInstructions("ambiguity")}\n\n${REFERENCE_CRITIC_INSTRUCTIONS}`,
+                input: privateReviewInput,
+                schemaName: "routekit_repository_specification_review_v1",
+                outputSchema: RepositorySpecificationReviewOutput,
+                maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-critic-b")
+            })
+        ], { concurrency: 2 });
+        modelCalls.push(criticA.call, criticB.call);
+        const compatibilityFailures = referenceCompatibilityFailures(criticB.value, scope, privateSources, pendingQuestions, visible);
+        const reviews = [
+            {
+                reviewerId: criticA.call.operationId,
+                reviewerKind: "independent-solver",
+                independentlyProduced: true,
+                ...criticA.value
+            },
+            {
+                reviewerId: criticB.call.operationId,
+                reviewerKind: "model-critic",
+                independentlyProduced: true,
+                ...criticB.value,
+                ...(compatibilityFailures.length === 0
+                    ? {}
+                    : {
+                        verdict: "insufficient",
+                        detail: [criticB.value.detail, ...compatibilityFailures].join(" "),
+                        findings: [
+                            ...criticB.value.findings,
+                            ...compatibilityFailures.map((detail) => ({
+                                axis: "unsupported-assumption",
+                                severity: "blocker",
+                                detail
+                            }))
+                        ]
+                    })
+            }
+        ];
+        const critique = yield* critiqueRepositoryTaskSpecificationV1({
+            repositoryRoot: input.repositoryRoot,
+            seed: { ...input.seed, targetBehavior: groundedTargetBehavior },
+            family: input.family,
+            visible,
+            reviews,
+            ...dimensionContext
+        });
+        history.push({ sequence, visible, reviews, rejectionReasons: critique.rejectionReasons });
+        if (critique.outcome === "pass") {
+            return {
+                version: 1,
+                caseId: input.caseId,
+                analysis: analysis.value,
+                contextSources,
+                visible,
+                reviews,
+                modelCalls,
+                groundedTargetBehavior,
+                referenceGrounding: {
+                    beforeCommit: before.commit,
+                    referenceCommit: after.commit,
+                    sources: privateSources,
+                    scope
+                },
+                specificationRevisions: history
+            };
+        }
+        if (hasIndependentGroundedDimensionMismatch({
+            ...dimensionContext,
+            operationPrefix,
+            before,
+            targetBehavior: groundedTargetBehavior,
+            reviews,
+            scope,
+            sources: privateSources
+        })) {
+            return yield* new RepositoryFoundryError({
+                operation: "select-generation-context",
+                detail: "generated specification cannot assess the pinned requested dimension: two independent critics established a definite mismatch with complete grounded scope and critical behavior evidence",
+                generationRejection: {
+                    code: "specification-dimension-mismatch",
+                    completedRevisions: sequence
+                }
+            });
+        }
+        if (sequence === maximumRevisions) {
+            const publicReasons = critique.rejectionReasons.map((detail) => containsPrivateReferenceMaterial(detail, privateSources, after.commit)
+                ? "A private reference compatibility finding blocks this specification."
+                : detail);
+            return yield* new RepositoryFoundryError({
+                operation: "select-generation-context",
+                detail: `generated specification failed independent review after ${String(sequence)} bounded revisions: ${publicReasons.join("; ")}`,
+                generationRejection: {
+                    code: "specification-review-exhausted",
+                    completedRevisions: sequence
+                }
+            });
+        }
+        // The writer receives prose findings only, never source refs, full private
+        // review objects, or raw repository snippets from the compatibility critic.
+        revisionFeedback = reviews
+            .flatMap((review) => [
+            review.detail,
+            ...(review.dimensionFit === undefined ? [] : [review.dimensionFit.detail]),
+            ...review.findings.map((finding) => finding.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) ?? [])
+        ])
+            .filter((detail) => detail.trim().length > 0)
+            .map((detail) => containsPrivateReferenceMaterial(detail, privateSources, after.commit)
+            ? "The prior specification lacks a supported, unambiguous statement of the supplied behavioral scope; restate its exact eligibility and preservation boundaries."
+            : detail);
+        previousVisible = visible;
+    }
+    return yield* contextFailure("reference-grounded specification exhausted its bounded review loop");
+});
+const contractFactsBoundary = (evaluate, detail) => Effect.try({ try: evaluate, catch: () => contextFailure(detail) });
+const requireContractFacts = (condition) => {
+    if (!condition)
+        throw new Error("invalid contract-fact evidence");
+};
+const sameContractFactIds = (left, right) => left.length === right.length &&
+    new Set(left).size === left.length &&
+    left.every((id) => right.includes(id));
+const contractFactsArePrivate = (value, sources, referenceCommit) => containsPrivateReferenceMaterial(value, sources, referenceCommit) ||
+    JSON.stringify(value).includes("private-contract-fact-question-") ||
+    JSON.stringify(value).includes("```");
+const prepareContractFacts = (input) => {
+    const proposal = parseRepositorySpecificationContractFactsProposalV1(input.value);
+    requireContractFacts(proposal.facts.every((fact) => fact.evidence.every((entry) => referenceEvidenceValid(entry, input.sources)) &&
+        fact.evidence.some((entry) => referenceEvidenceValid(entry, input.sources, "after"))));
+    const scope = repositorySpecificationContractFactsScopeV1(input.originalScope, proposal);
+    const packet = repositorySpecificationContractFactsPacketV1(scope, proposal);
+    requireContractFacts(!contractFactsArePrivate(packet, input.sources, input.referenceCommit));
+    return { proposal, scope, packet };
+};
+/**
+ * Mechanical completeness and identity checks do not prove semantic truth.
+ * The reference critic must independently establish it from the pinned source.
+ */
+const checkContractFactReview = (input) => {
+    const { review, packet } = input;
+    const scopeIds = input.scope.clauses.map((clause) => clause.id);
+    requireContractFacts(review.packetDigest === packet.digest &&
+        sameContractFactIds(review.scopeChecks.map((check) => check.scopeId), scopeIds) &&
+        review.clarificationRequests.length <=
+            REPOSITORY_SPECIFICATION_CONTRACT_FACTS_MAXIMUM_QUESTIONS);
+    for (const check of review.scopeChecks) {
+        requireContractFacts(sameContractFactIds(check.factIds, packet.facts.filter((fact) => fact.scopeId === check.scopeId).map((fact) => fact.id)) &&
+            check.detail.trim().length > 0 &&
+            check.detail.length <= 600 &&
+            check.evidence.length <= 8 &&
+            (input.perspective === "solver"
+                ? check.evidence.length === 0
+                : (check.outcome !== "complete" || check.evidence.length > 0) &&
+                    check.evidence.every((entry) => referenceEvidenceValid(entry, input.sources, "after"))) &&
+            (check.outcome === "complete" ||
+                review.clarificationRequests.some((question) => question.scopeId === check.scopeId)));
+    }
+    const questionKeys = review.clarificationRequests.map((question) => JSON.stringify(question));
+    requireContractFacts(new Set(questionKeys).size === questionKeys.length);
+    for (const question of review.clarificationRequests) {
+        requireContractFacts(scopeIds.includes(question.scopeId) &&
+            question.question.trim().length > 0 &&
+            question.question.length <= 800 &&
+            new Set(question.factIds).size === question.factIds.length &&
+            question.factIds.every((id) => packet.facts.some((fact) => fact.id === id && fact.scopeId === question.scopeId)) &&
+            review.scopeChecks.some((check) => check.scopeId === question.scopeId && check.outcome !== "complete"));
+    }
+    requireContractFacts(!contractFactsArePrivate({
+        details: review.scopeChecks.map((check) => check.detail),
+        questions: review.clarificationRequests
+    }, input.sources, input.referenceCommit));
+    return review.scopeChecks
+        .filter((check) => check.outcome !== "complete")
+        .map((check) => `The independent ${input.perspective} contract-fact check for ${check.scopeId} is ${check.outcome}: ${check.detail}`);
+};
+const contractFactClarificationRequests = (reviews, sequence) => {
+    const questions = reviews.flatMap((review) => review.contractFactReview.clarificationRequests);
+    const unique = questions.filter((question, index) => questions.findIndex((other) => other.scopeId === question.scopeId &&
+        other.reason === question.reason &&
+        other.question === question.question &&
+        sameContractFactIds(other.factIds, question.factIds)) === index);
+    requireContractFacts(unique.length <= REPOSITORY_SPECIFICATION_CONTRACT_FACTS_MAXIMUM_QUESTIONS);
+    return unique.map((question, index) => ({
+        requestId: `private-contract-fact-question-${String(sequence)}-${String(index + 1)}`,
+        scopeId: question.scopeId,
+        factIds: [...question.factIds],
+        reason: question.reason,
+        question: question.question
+    }));
+};
+const validateContractFactClarification = (input) => {
+    requireContractFacts(sameContractFactIds(input.clarification.resolutions.map((resolution) => resolution.requestId), input.requests.map((request) => request.requestId)));
+    const affectedScopes = new Set(input.requests.map((request) => request.scopeId));
+    // A missing-fact repair cannot change unrelated scopes or silently remove their
+    // facts. The independent reference review rechecks the whole replacement.
+    for (const previous of input.previous.facts.filter((fact) => !affectedScopes.has(fact.scopeId))) {
+        requireContractFacts(JSON.stringify(input.next.facts.find((fact) => fact.id === previous.id)) ===
+            JSON.stringify(previous));
+    }
+    for (const next of input.next.facts.filter((fact) => !affectedScopes.has(fact.scopeId))) {
+        requireContractFacts(JSON.stringify(input.previous.facts.find((fact) => fact.id === next.id)) ===
+            JSON.stringify(next));
+    }
+    for (const resolution of input.clarification.resolutions) {
+        const request = input.requests.find((entry) => entry.requestId === resolution.requestId);
+        requireContractFacts(resolution.outcome === "answered" &&
+            resolution.detail.trim().length > 0 &&
+            resolution.detail.length <= 800 &&
+            resolution.factIds.length > 0 &&
+            new Set(resolution.factIds).size === resolution.factIds.length &&
+            resolution.factIds.every((id) => input.next.facts.some((fact) => fact.id === id && fact.scopeId === request.scopeId)));
+    }
+};
+const markedReviewWithFailures = (review, call, reviewerKind, failures) => ({
+    ...review,
+    reviewerId: call.operationId,
+    reviewerKind,
+    independentlyProduced: true,
+    ...(failures.length === 0
+        ? {}
+        : {
+            verdict: "insufficient",
+            detail: [review.detail, ...failures].join(" "),
+            findings: [
+                ...review.findings,
+                ...failures.map((detail) => ({
+                    axis: "unsupported-assumption",
+                    severity: "blocker",
+                    detail
+                }))
+            ]
+        })
+});
+const authorContractFactsSpecification = Effect.fn("CaseAuthoring.authorContractFacts")(function* (input) {
+    const languageModel = yield* RepositoryFoundryLanguageModel;
+    const request = input.request;
+    const maximumRevisions = request.maximumSpecificationRevisions;
+    const originalScope = input.analysis.referenceScope;
+    const originalBehavioralScope = originalScope.clauses.map((clause) => ({
+        id: clause.id,
+        kind: clause.kind,
+        behaviorIds: clause.behaviorIds,
+        description: clause.description
+    }));
+    const pendingQuestions = originalScope.unresolvedQuestions.map((question, index) => ({
+        id: `private-reference-question-${String(index + 1)}`,
+        question
+    }));
+    const dimensionContext = request.requestedDimension === undefined
+        ? {}
+        : { requestedDimension: request.requestedDimension };
+    const privateReferenceEvidence = {
+        beforeCommit: input.before.commit,
+        referenceCommit: input.after.commit,
+        sources: input.privateSources,
+        pendingQuestions
+    };
+    let current = yield* contractFactsBoundary(() => prepareContractFacts({
+        value: input.analysis.contractFacts,
+        originalScope,
+        sources: input.privateSources,
+        referenceCommit: input.after.commit
+    }), "contract-fact proposal is malformed, ungrounded, oversized, or contains private material");
+    let analystOperationId = input.analystCall.operationId;
+    let clarificationRequests = [];
+    let previousVisible;
+    let revisionFeedback = [];
+    const modelCalls = [input.analystCall];
+    const history = [];
+    const factsHistory = [];
+    for (let sequence = 0; sequence <= maximumRevisions; sequence += 1) {
+        const operationPrefix = sequence === 0
+            ? request.operationId
+            : `${request.operationId}:specification-revision:${String(sequence)}`;
+        const answeredRequestIds = sequence === 0 ? [] : clarificationRequests.map((question) => question.requestId);
+        if (sequence > 0 && clarificationRequests.length > 0) {
+            // The plan reserves at most one existing-role analyst call per revision,
+            // not one call per question and never another retry/continuation owner.
+            const clarificationInput = {
+                ...dimensionContext,
+                targetBehavior: request.seed.targetBehavior,
+                behavioralScope: originalBehavioralScope,
+                contractFacts: current.packet,
+                privateContractFacts: current.proposal,
+                clarificationRequests,
+                previousVisible,
+                privateReferenceEvidence
+            };
+            yield* assertBoundedReferenceInput(clarificationInput);
+            const clarified = yield* languageModel.generateStructured({
+                plan: request.modelPlan,
+                role: "repository-analyst",
+                operationId: `${operationPrefix}:contract-facts-analyst`,
+                instructions: CONTRACT_FACTS_CLARIFICATION_INSTRUCTIONS,
+                input: clarificationInput,
+                schemaName: "routekit_repository_contract_fact_clarification_v1",
+                outputSchema: RepositorySpecificationContractFactClarificationV1,
+                maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("repository-analyst")
+            });
+            modelCalls.push(clarified.call);
+            const next = yield* contractFactsBoundary(() => {
+                const prepared = prepareContractFacts({
+                    value: { version: clarified.value.version, facts: clarified.value.facts },
+                    originalScope,
+                    sources: input.privateSources,
+                    referenceCommit: input.after.commit
+                });
+                validateContractFactClarification({
+                    clarification: clarified.value,
+                    requests: clarificationRequests,
+                    previous: current.proposal,
+                    next: prepared.proposal
+                });
+                return prepared;
+            }, "contract-fact clarification is unresolved, malformed, ungrounded, or changes unrelated scope");
+            current = next;
+            analystOperationId = clarified.call.operationId;
+        }
+        const behavioralScope = current.scope.clauses.map((clause) => ({
+            id: clause.id,
+            kind: clause.kind,
+            behaviorIds: clause.behaviorIds,
+            description: clause.description
+        }));
+        const groundedTargetBehavior = request.seed.targetBehavior.map((behavior) => ({
+            ...behavior,
+            description: current.scope.clauses
+                .filter((clause) => clause.behaviorIds.includes(behavior.id))
+                .map((clause) => clause.description)
+                .join(" ")
+        }));
+        const publicContext = {
+            ...dimensionContext,
+            targetBehavior: groundedTargetBehavior,
+            analysis: input.publicAnalysis,
+            behavioralScope,
+            family: input.familyContext,
+            contractFacts: current.packet
+        };
+        const writerInput = {
+            ...publicContext,
+            initialCommit: input.before.commit,
+            selectedRepositoryContext: input.contextSources,
+            ...(sequence === 0 ? {} : { previousVisible, behavioralReviewFeedback: revisionFeedback })
+        };
+        yield* assertBoundedReferenceInput(writerInput);
+        const authored = yield* languageModel.generateStructured({
+            plan: request.modelPlan,
+            role: "specification-writer",
+            operationId: `${operationPrefix}:specification-writer`,
+            instructions: `${SPECIFICATION_INSTRUCTIONS}\n\n${CONTRACT_FACTS_WRITER_INSTRUCTIONS}${sequence === 0 ? "" : `\n${SPECIFICATION_REVISION_INSTRUCTIONS}`}`,
+            input: writerInput,
+            schemaName: "routekit_repository_specification_v1",
+            outputSchema: RepositorySpecificationOutput,
+            maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-writer")
+        });
+        modelCalls.push(authored.call);
+        const visible = {
+            lane: "repository-agent",
+            id: request.caseId,
+            requestText: authored.value.requestText,
+            checkoutCommit: input.before.commit,
+            allowedTools: ["read", "search", "edit", "shell", "test"],
+            constraints: [
+                ...new Set([
+                    ...authored.value.constraints,
+                    ...current.packet.facts.map(renderRepositorySpecificationContractFactV1),
+                    "Do not weaken or delete tests to make the task pass.",
+                    "Preserve unrelated public behavior."
+                ])
+            ]
+        };
+        if (contractFactsArePrivate(visible, input.privateSources, input.after.commit)) {
+            return yield* contextFailure("private material leaked into the marked visible specification");
+        }
+        const reviewInput = {
+            ...publicContext,
+            visible,
+            initialRepositoryExcerpts: input.contextSources
+        };
+        const privateReviewInput = {
+            ...reviewInput,
+            privateReferenceEvidence,
+            privateContractFacts: current.proposal
+        };
+        yield* assertBoundedReferenceInput(privateReviewInput);
+        const [criticA, criticB] = yield* Effect.all([
+            languageModel.generateStructured({
+                plan: request.modelPlan,
+                role: "specification-critic-a",
+                operationId: `${operationPrefix}:specification-critic-a`,
+                instructions: `${criticInstructions("solver")}\n\n${CONTRACT_FACTS_REVIEW_INSTRUCTIONS}\nYou remain blind to the reference. Return empty evidence arrays in every contractFactReview.scopeChecks record; evaluate the actual visible contract and supplied pre-change context.`,
+                input: reviewInput,
+                schemaName: "routekit_repository_specification_facts_review_v1",
+                outputSchema: RepositoryContractFactsReviewOutput,
+                maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-critic-a")
+            }),
+            languageModel.generateStructured({
+                plan: request.modelPlan,
+                role: "specification-critic-b",
+                operationId: `${operationPrefix}:specification-critic-b`,
+                instructions: `${criticInstructions("ambiguity")}\n\n${REFERENCE_CRITIC_INSTRUCTIONS}\n\n${CONTRACT_FACTS_REVIEW_INSTRUCTIONS}\n\n${CONTRACT_FACTS_REFERENCE_REVIEW_INSTRUCTIONS}`,
+                input: privateReviewInput,
+                schemaName: "routekit_repository_specification_facts_review_v1",
+                outputSchema: RepositoryContractFactsReviewOutput,
+                maximumOutputTokens: repositoryFoundryRoleOutputCeilingV1("specification-critic-b")
+            })
+        ], { concurrency: 2 });
+        modelCalls.push(criticA.call, criticB.call);
+        const factFailures = yield* contractFactsBoundary(() => [criticA, criticB].map((critic, index) => checkContractFactReview({
+            review: critic.value.contractFactReview,
+            packet: current.packet,
+            scope: current.scope,
+            sources: input.privateSources,
+            referenceCommit: input.after.commit,
+            perspective: index === 0 ? "solver" : "reference"
+        })), "contract-fact review has stale identity, incomplete evidence, malformed questions, or private material");
+        const compatibilityFailures = referenceCompatibilityFailures(criticB.value, current.scope, input.privateSources, pendingQuestions, visible);
+        const reviews = [
+            markedReviewWithFailures(criticA.value, criticA.call, "independent-solver", factFailures[0]),
+            markedReviewWithFailures(criticB.value, criticB.call, "model-critic", [
+                ...factFailures[1],
+                ...compatibilityFailures
+            ])
+        ];
+        const critique = yield* critiqueRepositoryTaskSpecificationV1({
+            repositoryRoot: request.repositoryRoot,
+            seed: { ...request.seed, targetBehavior: groundedTargetBehavior },
+            family: request.family,
+            visible,
+            reviews,
+            ...dimensionContext
+        });
+        history.push({
+            sequence,
+            visible,
+            reviews,
+            rejectionReasons: critique.rejectionReasons,
+            contractFactsDigest: current.packet.digest
+        });
+        factsHistory.push({
+            sequence,
+            packetDigest: current.packet.digest,
+            analystOperationId,
+            clarificationRequestIds: answeredRequestIds
+        });
+        if (critique.outcome === "pass") {
+            return {
+                version: 1,
+                caseId: request.caseId,
+                analysis: input.analysis,
+                contextSources: input.contextSources,
+                visible,
+                reviews,
+                modelCalls,
+                groundedTargetBehavior,
+                referenceGrounding: {
+                    beforeCommit: input.before.commit,
+                    referenceCommit: input.after.commit,
+                    sources: input.privateSources,
+                    scope: current.scope
+                },
+                specificationRevisions: history,
+                contractFacts: {
+                    version: 1,
+                    packet: current.packet,
+                    independentlyReviewed: true,
+                    reviewerOperationIds: [criticA.call.operationId, criticB.call.operationId],
+                    history: factsHistory
+                }
+            };
+        }
+        if (factFailures.every((failures) => failures.length === 0) &&
+            hasIndependentGroundedDimensionMismatch({
+                ...dimensionContext,
+                operationPrefix,
+                before: input.before,
+                targetBehavior: groundedTargetBehavior,
+                reviews,
+                scope: current.scope,
+                sources: input.privateSources
+            })) {
+            return yield* new RepositoryFoundryError({
+                operation: "select-generation-context",
+                detail: "generated specification cannot assess the pinned requested dimension: two independent critics established a definite mismatch with complete grounded scope and contract-fact evidence",
+                generationRejection: {
+                    code: "specification-dimension-mismatch",
+                    completedRevisions: sequence
+                }
+            });
+        }
+        if (sequence === maximumRevisions) {
+            const publicReasons = critique.rejectionReasons.map((detail) => contractFactsArePrivate(detail, input.privateSources, input.after.commit)
+                ? "A private reference compatibility finding blocks this specification."
+                : detail);
+            return yield* new RepositoryFoundryError({
+                operation: "select-generation-context",
+                detail: `generated specification failed independent review after ${String(sequence)} bounded revisions: ${publicReasons.join("; ")}`,
+                generationRejection: {
+                    code: "specification-review-exhausted",
+                    completedRevisions: sequence
+                }
+            });
+        }
+        clarificationRequests = yield* contractFactsBoundary(() => contractFactClarificationRequests([criticA.value, criticB.value], sequence), "contract-fact clarification requests exceed their immutable per-revision bound");
+        revisionFeedback = reviews
+            .flatMap((review) => [
+            review.detail,
+            ...(review.dimensionFit === undefined ? [] : [review.dimensionFit.detail]),
+            ...review.findings.map((finding) => finding.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.contractFactReview?.scopeChecks
+                .filter((check) => check.outcome !== "complete")
+                .map((check) => check.detail) ?? [])
+        ])
+            .filter((detail) => detail.trim().length > 0)
+            .map((detail) => contractFactsArePrivate(detail, input.privateSources, input.after.commit)
+            ? "Resolve the remaining behavioral finding using only the supplied public contract facts."
+            : detail);
+        previousVisible = visible;
+    }
+    return yield* contextFailure("marked contract-fact authoring exhausted its bounded review loop");
+});
+export const makeCaseAuthoring = Effect.gen(function* () {
+    const languageModel = yield* RepositoryFoundryLanguageModel;
+    return CaseAuthoring.of({
+        authorSpecification: (input) => authorRepositoryCaseSpecificationV1(input).pipe(Effect.provideService(RepositoryFoundryLanguageModel, languageModel))
+    });
+});
+export const CaseAuthoringLive = Layer.effect(CaseAuthoring, makeCaseAuthoring);