@jitsusama/agentic-harness.core 0.1.0

package/dist/review/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Public surface of the review library.
+ *
+ * One substrate for the activity of reviewing code changes,
+ * whatever hosts them and whether anything hosts them at
+ * all. A change, its stack, its reviews, its threads and its
+ * messages are one neutral model; GitHub, Meteorite, GitLab
+ * and a bare git repo are providers behind it.
+ *
+ * The vocabulary is git's wherever git has a word for the
+ * thing: a diff has an old and a new side rather than a left
+ * and a right, an anchor names the commit it was formed
+ * against, and a stack is refs pointing at refs. Forge
+ * inventions stay inside their providers.
+ */
+export type { Exec, ExecResult, ProviderDeps } from "../exec/index.js";
+export { run } from "../exec/index.js";
+export type { Anchor, AnchorCheck, AnchorRefusal, ChangeAnchor, FileAnchor, LineAnchor, } from "./anchor.js";
+export { anchorable, anchorPath, describeAnchor } from "./anchor.js";
+export type { AgentDiscovery, AgentFile, RepoAgent, } from "./ask/agents.js";
+export { discoverAgents, NAMESPACE } from "./ask/agents.js";
+export type { FileRanges, LineRange } from "./ask/anchorable.js";
+export { anchorableRanges, describeRanges } from "./ask/anchorable.js";
+export type { AnswerContext, AnswerLine } from "./ask/answer.js";
+export { describeRun, roundAnswer } from "./ask/answer.js";
+export type { AuditHarvest, AuditRequest, AuditResult, Standing, ThreadAudit, } from "./ask/audit.js";
+export { harvestAudits, runAudit } from "./ask/audit.js";
+export { type CollectDeps, collectRound } from "./ask/collect.js";
+export type { Ask, AskAnswer, AskContext, AskLimit, AskStop, CouncilDeps, CouncilRequest, CouncilResult, } from "./ask/council.js";
+export { runCouncil } from "./ask/council.js";
+export type { Critique, CritiqueDeps, CritiqueHarvest, CritiqueRequest, CritiqueResult, Position, } from "./ask/critique.js";
+export { harvestCritiques, runCritique } from "./ask/critique.js";
+export type { Harvest } from "./ask/harvest.js";
+export { alsoRecorded, harvestFindings } from "./ask/harvest.js";
+export type { ClaimOutcome, IdentityLedger, Participant, ParticipantIdentity, ParticipantRole, } from "./ask/identity.js";
+export { attributedTo, createIdentityLedger, participantIdentity, } from "./ask/identity.js";
+export type { JudgeRequest, JudgeResult } from "./ask/judge.js";
+export { runJudge } from "./ask/judge.js";
+export type { CharterLookup, Persona, PersonaBind, PersonaBinding, PersonaParse, } from "./ask/persona.js";
+export { bindPersonas, parsePersona } from "./ask/persona.js";
+export { type AskProgress, type AskProgressEntry, type AskProgressState, noAskProgress, trackAskProgress, } from "./ask/progress.js";
+export type { AuditPromptInput, CritiquePromptInput, GuidanceState, JudgePromptInput, PromptInput, RepoGuidance, StackChangePrompt, StackPromptInput, } from "./ask/prompt.js";
+export { auditPrompt, councilPrompt, critiquePrompt, judgePrompt, quotable, stackPrompt, } from "./ask/prompt.js";
+export type { ParticipantParse, Roster, RosterParse } from "./ask/roster.js";
+export { overrideRoster, type ParticipantOverride, parseParticipant, parseRoster, } from "./ask/roster.js";
+export type { AskRound, AskRun, AskUsage, ParticipantOutcome, RoundGiven, RunSummary, TreeRead, } from "./ask/run.js";
+export { askedOf, failureLines, newRunId, retryCannotResettle, runSummary, staleRuntimeAdvisory, stoppedNotes, substituteOutcome, whatItRead, } from "./ask/run.js";
+export type { FindingSpan, SpannedFinding, StackHarvest, } from "./ask/span.js";
+export { harvestStackFindings, saidAt } from "./ask/span.js";
+export type { StackCouncilDeps, StackCouncilRequest, } from "./ask/stack-round.js";
+export { runStackCouncil } from "./ask/stack-round.js";
+export { type StartDeps, type StartResult, startCouncil, } from "./ask/start.js";
+export type { OpenRuns, RunStore } from "./ask/store.js";
+export { createRunStore } from "./ask/store.js";
+export type { Attachment, AttachmentStore, ChangeAmbiguous, ChangeInPlay, } from "./attach.js";
+export { changeInPlay, chooseChange, createAttachmentStore, inheritAttachments, pruneAttachments, } from "./attach.js";
+export type { AuthoringIntent, Offerable } from "./authoring.js";
+export { misnamedPeople, offerable } from "./authoring.js";
+export type { Unbacked } from "./backed.js";
+export { BACKED_BY, unbackedDeclarations } from "./backed.js";
+export type { RepoResolution, TargetResolution } from "./bind.js";
+export { bindTarget, clearTargetBindings, resolveRepo, resolveTarget, } from "./bind.js";
+export type { ReviewerBudget, ReviewerClocks } from "./budget.js";
+export { boundsFor, budgetForLimit, REVIEWER_ANSWER_MS, REVIEWER_BACKSTOP_MS, REVIEWER_IDLE_MS, retryWouldRepeat, reviewerBudget, } from "./budget.js";
+export type { AuthoringCapabilities, Capabilities, ConversationCapabilities, PersonForm, ProposalCapabilities, RetargetScope, ReviewersAt, StackingCapabilities, StalenessModel, } from "./capabilities.js";
+export type { Actor, ChangeRef, ChangeState, Proposal, RepoLocator, ReviewTarget, } from "./change.js";
+export type { Check, CheckState, ChecksRollup, RerunOutcome, } from "./checks.js";
+export type { LoadedReviewConfig, ReferenceMapping, RepoMapping, ReviewConfig, } from "./config.js";
+export { parseReviewSection } from "./config.js";
+export { proposalComplaint } from "./conventions.js";
+export type { AnchoredComment, Message, Posted, Reaction, ReactionCount, Review, Thread, Verdict, WireReview, } from "./conversation.js";
+export type { Decision, DecisionLedger, Settlement } from "./decided.js";
+export { createDecisionLedger } from "./decided.js";
+export type { DiffFile, DiffHunk, DiffLine, DiffModel, DiffSide, DiffStatus, } from "./diff.js";
+export { changeCounts, displayPath, filePath, hunkHeader, lineNumberOn, parseUnifiedDiff, } from "./diff.js";
+export type { ChangePublishOutcome, StackPublishEntry, StackPublishOutcome, } from "./draft/fanout.js";
+export { publishAcross } from "./draft/fanout.js";
+export type { DraftDeps, ReviewDraft } from "./draft/handle.js";
+export { openDraft, resumeDraft } from "./draft/handle.js";
+export type { Degradation, PlanContext, PlannedOp, PlanRefusal, PublishPlan, } from "./draft/plan.js";
+export { compilePlan } from "./draft/plan.js";
+export type { OpOutcome, PublishOutcome } from "./draft/publish.js";
+export { publishPlan } from "./draft/publish.js";
+export type { RenderOptions, ReviewDocument } from "./draft/render.js";
+export { renderDraft } from "./draft/render.js";
+export type { DraftItem, DraftState, FindingItem, ReactionItem, ReplyItem, ResolutionItem, UnresolutionItem, } from "./draft/state.js";
+export { addFinding, addReaction, addReply, addResolution, addUnresolution, emptyDraft, removeItem, setVerdict, } from "./draft/state.js";
+export type { DraftStore, DraftSummary } from "./draft/store.js";
+export { createDraftStore } from "./draft/store.js";
+export { repoElsewhere } from "./elsewhere.js";
+export type { BoundTarget, LocalSpec, ReviewEngine, ReviewEngineDeps, ServingRepo, } from "./engine.js";
+export { createReviewEngine } from "./engine.js";
+export type { ReviewSubstrateApi } from "./events.js";
+export { REVIEW_READY, REVIEW_REGISTER_PROVIDER, REVIEW_REQUEST_SUBSTRATE, } from "./events.js";
+export type { FailureContext } from "./failed.js";
+export { explainFailure, readsAsMissing } from "./failed.js";
+export type { ConventionalLabel, Finding, FindingOrigin, FindingSeverity, FindingStore, } from "./finding.js";
+export { createFindingStore } from "./finding.js";
+export type { FixOutcome, FixQueue, FixSubject, FixTally, QueuedFix, QueuedThread, } from "./fix.js";
+export { createFixQueue, describeSubject, subjectOf } from "./fix.js";
+export type { FollowUp, Reception } from "./followup.js";
+export { followUpOn, receptionOf, tallyReceptions, } from "./followup.js";
+export { changeKey, repoKey, targetKey } from "./keys.js";
+export type { Landability } from "./landing.js";
+export { standsAt } from "./landing.js";
+export type { ReadableTree, Touched } from "./lenses.js";
+export { agentsInRepo, chartersOnDisk, givenBy, guidanceFor, guidanceInRepo, lensesFor, touchedBy, } from "./lenses.js";
+export type { CheckoutFacts, ProposalFill, ProposalWanted, } from "./propose-from.js";
+export { fillProposal } from "./propose-from.js";
+export type { AuthoringFacet, ChangeFilter, ConversationFacet, FieldEdit, LocalBranch, MergeOutcome, MergeRequest, ProposalDraft, ProposalEdit, ProposalsFacet, RepoProbe, ReviewProvider, SetEdit, StackingFacet, } from "./provider.js";
+export { createGitProvider } from "./providers/git/index.js";
+export { githubAuthoring } from "./providers/github/authoring.js";
+/**
+ * The GitHub provider's pure helpers, for consumers still
+ * bridging GitHub-shaped code onto the substrate. Neither
+ * touches the network, and both are safe to call before any
+ * provider is registered.
+ */
+export { claimGitHubReference, GITHUB_PROVIDER_ID, githubChange, ownerRepoFromKey, } from "./providers/github/claims.js";
+export { createGitHubProvider } from "./providers/github/index.js";
+export type { QueuePosture, QueueRefusal, QueueState } from "./queue.js";
+export { queueRefusal } from "./queue.js";
+export type { Reactable, ReactableKind, ReactableRefusal, } from "./reactable.js";
+export { findReactable, isReactableRefusal, reactableAddresses, reactableLabel, reactables, } from "./reactable.js";
+export type { ProviderComplaint } from "./register.js";
+export { clearReviewProviders, getReviewProvider, listReviewProviders, registerReviewProvider, unregisterReviewProvider, } from "./register.js";
+export type { Resolution, ResolutionRefusal, ResolveContext, ResolvedVia, } from "./resolve.js";
+export { checkoutFor, resolveReference } from "./resolve.js";
+export type { Retarget, RetargetPlan, RetargetRoute } from "./retarget.js";
+export { retargetPlan, retargetRoute } from "./retarget.js";
+export type { SinceLastVisit, Visit, VisitLog } from "./revisited.js";
+export { createVisitLog, describeVisit, sinceLastVisit, } from "./revisited.js";
+export type { Stack, StackNode, StackProvenance, StackStep, } from "./stack.js";
+export { stackStep } from "./stack.js";

package/dist/review/index.js

@@ -0,0 +1,80 @@
+/**
+ * Public surface of the review library.
+ *
+ * One substrate for the activity of reviewing code changes,
+ * whatever hosts them and whether anything hosts them at
+ * all. A change, its stack, its reviews, its threads and its
+ * messages are one neutral model; GitHub, Meteorite, GitLab
+ * and a bare git repo are providers behind it.
+ *
+ * The vocabulary is git's wherever git has a word for the
+ * thing: a diff has an old and a new side rather than a left
+ * and a right, an anchor names the commit it was formed
+ * against, and a stack is refs pointing at refs. Forge
+ * inventions stay inside their providers.
+ */
+export { run } from "../exec/index.js";
+export { anchorable, anchorPath, describeAnchor } from "./anchor.js";
+export { discoverAgents, NAMESPACE } from "./ask/agents.js";
+export { anchorableRanges, describeRanges } from "./ask/anchorable.js";
+export { describeRun, roundAnswer } from "./ask/answer.js";
+export { harvestAudits, runAudit } from "./ask/audit.js";
+export { collectRound } from "./ask/collect.js";
+export { runCouncil } from "./ask/council.js";
+export { harvestCritiques, runCritique } from "./ask/critique.js";
+export { alsoRecorded, harvestFindings } from "./ask/harvest.js";
+export { attributedTo, createIdentityLedger, participantIdentity, } from "./ask/identity.js";
+export { runJudge } from "./ask/judge.js";
+export { bindPersonas, parsePersona } from "./ask/persona.js";
+export { noAskProgress, trackAskProgress, } from "./ask/progress.js";
+export { auditPrompt, councilPrompt, critiquePrompt, judgePrompt, quotable, stackPrompt, } from "./ask/prompt.js";
+export { overrideRoster, parseParticipant, parseRoster, } from "./ask/roster.js";
+export { askedOf, failureLines, newRunId, retryCannotResettle, runSummary, staleRuntimeAdvisory, stoppedNotes, substituteOutcome, whatItRead, } from "./ask/run.js";
+export { harvestStackFindings, saidAt } from "./ask/span.js";
+export { runStackCouncil } from "./ask/stack-round.js";
+export { startCouncil, } from "./ask/start.js";
+export { createRunStore } from "./ask/store.js";
+export { changeInPlay, chooseChange, createAttachmentStore, inheritAttachments, pruneAttachments, } from "./attach.js";
+export { misnamedPeople, offerable } from "./authoring.js";
+export { BACKED_BY, unbackedDeclarations } from "./backed.js";
+export { bindTarget, clearTargetBindings, resolveRepo, resolveTarget, } from "./bind.js";
+export { boundsFor, budgetForLimit, REVIEWER_ANSWER_MS, REVIEWER_BACKSTOP_MS, REVIEWER_IDLE_MS, retryWouldRepeat, reviewerBudget, } from "./budget.js";
+export { parseReviewSection } from "./config.js";
+export { proposalComplaint } from "./conventions.js";
+export { createDecisionLedger } from "./decided.js";
+export { changeCounts, displayPath, filePath, hunkHeader, lineNumberOn, parseUnifiedDiff, } from "./diff.js";
+export { publishAcross } from "./draft/fanout.js";
+export { openDraft, resumeDraft } from "./draft/handle.js";
+export { compilePlan } from "./draft/plan.js";
+export { publishPlan } from "./draft/publish.js";
+export { renderDraft } from "./draft/render.js";
+export { addFinding, addReaction, addReply, addResolution, addUnresolution, emptyDraft, removeItem, setVerdict, } from "./draft/state.js";
+export { createDraftStore } from "./draft/store.js";
+export { repoElsewhere } from "./elsewhere.js";
+export { createReviewEngine } from "./engine.js";
+export { REVIEW_READY, REVIEW_REGISTER_PROVIDER, REVIEW_REQUEST_SUBSTRATE, } from "./events.js";
+export { explainFailure, readsAsMissing } from "./failed.js";
+export { createFindingStore } from "./finding.js";
+export { createFixQueue, describeSubject, subjectOf } from "./fix.js";
+export { followUpOn, receptionOf, tallyReceptions, } from "./followup.js";
+export { changeKey, repoKey, targetKey } from "./keys.js";
+export { standsAt } from "./landing.js";
+export { agentsInRepo, chartersOnDisk, givenBy, guidanceFor, guidanceInRepo, lensesFor, touchedBy, } from "./lenses.js";
+export { fillProposal } from "./propose-from.js";
+export { createGitProvider } from "./providers/git/index.js";
+export { githubAuthoring } from "./providers/github/authoring.js";
+/**
+ * The GitHub provider's pure helpers, for consumers still
+ * bridging GitHub-shaped code onto the substrate. Neither
+ * touches the network, and both are safe to call before any
+ * provider is registered.
+ */
+export { claimGitHubReference, GITHUB_PROVIDER_ID, githubChange, ownerRepoFromKey, } from "./providers/github/claims.js";
+export { createGitHubProvider } from "./providers/github/index.js";
+export { queueRefusal } from "./queue.js";
+export { findReactable, isReactableRefusal, reactableAddresses, reactableLabel, reactables, } from "./reactable.js";
+export { clearReviewProviders, getReviewProvider, listReviewProviders, registerReviewProvider, unregisterReviewProvider, } from "./register.js";
+export { checkoutFor, resolveReference } from "./resolve.js";
+export { retargetPlan, retargetRoute } from "./retarget.js";
+export { createVisitLog, describeVisit, sinceLastVisit, } from "./revisited.js";
+export { stackStep } from "./stack.js";

package/dist/review/keys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Stable keys for repos, changes and review targets.
+ *
+ * Drafts live on disk and provider bindings stay sticky for
+ * the life of a target, so both need a name for "the thing
+ * being reviewed" that survives a restart and cannot
+ * collide with a different thing. These functions are that
+ * name. They are pure, and the shape they produce is a
+ * path: slashes separate the parts, and any separator inside
+ * a part is folded to a tilde so a part is always exactly
+ * one segment.
+ */
+import type { ChangeRef, RepoLocator, ReviewTarget } from "./change.js";
+/** Stable key for a repo. */
+export declare function repoKey(repo: RepoLocator): string;
+/** Stable key for a hosted change, scoped by provider. */
+export declare function changeKey(ref: ChangeRef): string;
+/**
+ * Stable key for anything a review session can look at. The
+ * leading part is the target's kind, so a range and a stack
+ * over the same refs never collide.
+ */
+export declare function targetKey(target: ReviewTarget): string;

package/dist/review/keys.js

@@ -0,0 +1,40 @@
+/**
+ * Stable keys for repos, changes and review targets.
+ *
+ * Drafts live on disk and provider bindings stay sticky for
+ * the life of a target, so both need a name for "the thing
+ * being reviewed" that survives a restart and cannot
+ * collide with a different thing. These functions are that
+ * name. They are pure, and the shape they produce is a
+ * path: slashes separate the parts, and any separator inside
+ * a part is folded to a tilde so a part is always exactly
+ * one segment.
+ */
+/** Folds path separators so the value is one path segment. */
+function segment(value) {
+    return value.replace(/[/\\]/g, "~");
+}
+/** Stable key for a repo. */
+export function repoKey(repo) {
+    return repo.key;
+}
+/** Stable key for a hosted change, scoped by provider. */
+export function changeKey(ref) {
+    return [ref.provider, segment(repoKey(ref.repo)), segment(ref.id)].join("/");
+}
+/**
+ * Stable key for anything a review session can look at. The
+ * leading part is the target's kind, so a range and a stack
+ * over the same refs never collide.
+ */
+export function targetKey(target) {
+    if (target.kind === "proposal") {
+        return `proposal/${changeKey(target.change)}`;
+    }
+    const repo = segment(repoKey(target.repo));
+    if (target.kind === "range") {
+        const endpoints = `${segment(target.base)}..${segment(target.head)}`;
+        return `range/${repo}/${endpoints}`;
+    }
+    return `stack/${repo}/${target.refs.map(segment).join("+")}`;
+}

package/dist/review/landing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Whether a change could land, and what is in the way.
+ *
+ * Every backend surveyed answers this, and every one of them answers it with more than a
+ * boolean: a word for the state plus flags for the things holding it up. Reducing that to
+ * `mergeable: false` throws away the only part anybody can act on, and worse, it reads the
+ * same whether the fix is a review, a rebase or a green build.
+ *
+ * So the flags are separate and all optional, because absent means unreported. A backend
+ * with no view on whether a required check is failing must not be read as saying none is.
+ */
+/** Where a change stands with landing, as the backend describes it. */
+export interface Landability {
+    /**
+     * The backend's own word, passed through.
+     *
+     * Kept because a backend can know a reason this model has no flag for, and losing
+     * it would turn a specific answer into an unexplained silence.
+     */
+    reason?: string;
+    /** At least one approving review. */
+    approved?: boolean;
+    /** A review asked for changes. */
+    changesRequested?: boolean;
+    /** A check the base branch requires is failing. */
+    failingRequiredCheck?: boolean;
+    /** The branch no longer merges cleanly into its base. */
+    conflicted?: boolean;
+}
+/**
+ * Say where a change stands with landing, in one line, or nothing at all.
+ *
+ * Every blocker is named rather than only the first, because a change with changes
+ * requested and a failing check needs two fixes and being told about one of them sends
+ * somebody back a second time.
+ */
+export declare function standsAt(landing: Landability | undefined): string;

package/dist/review/landing.js

@@ -0,0 +1,68 @@
+/**
+ * Whether a change could land, and what is in the way.
+ *
+ * Every backend surveyed answers this, and every one of them answers it with more than a
+ * boolean: a word for the state plus flags for the things holding it up. Reducing that to
+ * `mergeable: false` throws away the only part anybody can act on, and worse, it reads the
+ * same whether the fix is a review, a rebase or a green build.
+ *
+ * So the flags are separate and all optional, because absent means unreported. A backend
+ * with no view on whether a required check is failing must not be read as saying none is.
+ */
+/** Blockers in the order somebody has to deal with them. */
+const BLOCKERS = [
+    {
+        of: "conflicted",
+        said: "it conflicts with its base",
+        covers: ["conflicting", "dirty", "conflict"],
+    },
+    {
+        of: "changesRequested",
+        said: "changes were requested",
+        covers: ["changes_requested"],
+    },
+    {
+        of: "failingRequiredCheck",
+        said: "a required check is failing",
+        covers: ["failing_required_check", "blocked", "unstable"],
+    },
+];
+/**
+ * Say where a change stands with landing, in one line, or nothing at all.
+ *
+ * Every blocker is named rather than only the first, because a change with changes
+ * requested and a failing check needs two fixes and being told about one of them sends
+ * somebody back a second time.
+ */
+export function standsAt(landing) {
+    if (landing === undefined)
+        return "";
+    const stopping = BLOCKERS.filter((blocker) => landing[blocker.of] === true);
+    const word = landing.reason?.trim().toLowerCase();
+    const spoken = stopping.some((blocker) => blocker.covers.includes(word ?? ""));
+    // The backend's word only when the flags did not already say it, or the line
+    // reads as the same sentence twice in two vocabularies.
+    const aside = word === undefined || word === "" || spoken ? "" : ` (${word})`;
+    // Approval is said only when it is true. `approved: false` does not mean a
+    // review is required, since plenty of repos ask for none, so reporting the
+    // negative would invent a blocker the backend never claimed. Said even
+    // alongside blockers, because "approved, but a check is failing" is a
+    // different situation from "nobody has looked and a check is failing".
+    const reviewed = landing.approved === true ? ", approved" : "";
+    if (stopping.length > 0) {
+        return `cannot land: ${stopping.map((blocker) => blocker.said).join(", and ")}${aside}${reviewed}`;
+    }
+    // Only the backend can say a change is clear. Nothing in the way is not the
+    // same fact, since this model has no flag for every reason a backend has.
+    if (word !== undefined && word !== "") {
+        return CLEAR.includes(word)
+            ? `can land${aside}${reviewed}`
+            : `cannot land${aside}${reviewed}`;
+    }
+    // Approval on its own is worth saying even when the backend named no state,
+    // since somebody asking whether a change is ready wants to know a human has
+    // looked at it.
+    return reviewed === "" ? "" : "approved";
+}
+/** Backend words that mean nothing is holding the change up. */
+const CLEAR = ["mergeable", "clean", "ready", "has_hooks"];

package/dist/review/lenses.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Which lens each reviewer reads through, gathered from disk.
+ *
+ * A lens can come from two places now: a persona the operator wrote,
+ * which lives beside their config and travels with them, and an agent
+ * the repo under review defined for itself, which lives in the repo
+ * and does not. Binding a roster to charters means reading both and
+ * knowing which is which.
+ *
+ * Its own module because the composition is the part that has been
+ * wrong before. Four PRs in a row shipped a helper with tests and a
+ * call site without any, and the call site is where the bugs were: a
+ * glyph module two imports from a renderer still drawing the old
+ * marks, a spend recorder every test called directly and production
+ * never called at all. A composition inside a tool file can only be
+ * checked by reading it. Here it can be driven.
+ */
+import type { AgentDiscovery, DiffModel, RepoGuidance, Roster, RoundGiven } from "./index.js";
+/**
+ * Where a round reads the change under review from.
+ *
+ * The minimal shape every host adapter's own tree/worktree
+ * abstraction can produce: a path to read from, and an optional
+ * caveat when that path is not provably pinned to the commit under
+ * review. Adapters own the richer `RoundTree`/scaffolding types this
+ * is drawn from; this module only ever needs these two fields.
+ */
+export interface ReadableTree {
+    path: string;
+    /** Said out loud when the tree is not the commit under review. */
+    caveat?: string;
+}
+/**
+ * What the repo under review asks of its contributors.
+ *
+ * Read from the tree the round reads, and handed to the prompt as
+ * quoted material. Before this it arrived by itself, because a pi
+ * child reads the context files in its working directory and a
+ * reviewer's working directory is a tree pinned to the commit under
+ * review. That put the change author's prose above the round's own
+ * instructions, unasked and unrecorded.
+ */
+export declare function guidanceInRepo(tree: ReadableTree, touched: Touched): Promise<RepoGuidance | undefined>;
+/**
+ * What the repo says about itself, shaped for a prompt input.
+ *
+ * The join between the reader and the prompts, which lived in the tool
+ * file where nothing could execute it: both halves had tests and the
+ * thing that puts them together had none. Spread into a prompt input
+ * so a round with no conventions to show says nothing at all rather
+ * than carrying an empty section.
+ */
+export declare function guidanceFor(tree: ReadableTree, diff: DiffModel | {
+    unknown: string;
+}): Promise<{
+    guidance?: RepoGuidance;
+}>;
+/**
+ * What a round handed its reviewers, in the shape a run records it.
+ *
+ * The counterpart of `readFrom`, and it takes the conditions rather
+ * than reading them, so the value recorded and the value passed to the
+ * spawn are one constant used twice rather than two that agree today.
+ *
+ * The path and the edited state, not the text. A reader chasing a
+ * finding needs to know which file was folded into that reviewer's
+ * prompt and whether the change under review had written it; the bytes
+ * are in the tree at the witness, and tens of thousands of characters
+ * per round would cost more than the whole ledger.
+ */
+export declare function givenBy(isolated: boolean, conventions: {
+    guidance?: RepoGuidance;
+}): {
+    given: RoundGiven;
+};
+/**
+ * Every charter the operator wrote, by persona id.
+ *
+ * Read once per round rather than per participant, since six reviewers
+ * naming three personas should not be six directory walks. A file that
+ * will not parse stops the round: a roster naming it would otherwise
+ * fail with "no such persona" while the file sits right there, which
+ * sends somebody looking in the wrong place.
+ */
+export declare function chartersOnDisk(dir: string): Promise<Map<string, string>>;
+/**
+ * Lenses the repo under review already had, by namespaced id.
+ *
+ * Read from the tree the round will actually read, not from the
+ * session's directory, since those are two repos often enough to have
+ * cost $75.63 finding out.
+ */
+export declare function agentsInRepo(treePath: string, touched: readonly string[]): Promise<AgentDiscovery>;
+/**
+ * What the change under review writes to, or why that is not known.
+ *
+ * Not knowing is a real answer and has to be spellable. A stack whose
+ * nodes are not all proposed is read at the tip, which holds every
+ * node's work, while only the proposed ones carry diffs: the set of
+ * touched paths is then a subset pretending to be the whole, and a
+ * subset is the wrong shape for a rule that says "unless the change
+ * wrote it".
+ */
+export type Touched = readonly string[] | {
+    unknown: string;
+};
+/**
+ * What a change writes to, on either side of a rename, or why that is
+ * not known.
+ *
+ * A diff carrying no paths at all is the second answer and not the
+ * first. Every real change writes to something, so an empty list means
+ * the provider did not say, and reading that as "touches nothing" is
+ * the most permissive answer available for the one rule that keeps the
+ * change under review out of the reviewer's prompt.
+ */
+export declare function touchedBy(diff: DiffModel): Touched;
+/**
+ * Each participant's charter, by participant id.
+ *
+ * Keyed by participant rather than by persona, because a round asks by
+ * participant id and the same lens can be on a roster twice at two
+ * thinking levels. A missing persona stops the round here, before
+ * anybody is asked, since a reviewer running without its lens files
+ * generic findings under a specialist's name.
+ *
+ * The repo's own agents are looked up alongside the personas and
+ * cannot shadow one: their ids carry a namespace, so asking for a
+ * repo's lens and asking for your own are different requests, and one
+ * can never quietly answer the other.
+ */
+export declare function lensesFor(roster: Roster, personaDir: string, touched: Touched, tree: ReadableTree): Promise<Map<string, string>>;