instar 1.3.190 → 1.3.192

package/dist/core/crossModelReviewer.d.ts

@@ -0,0 +1,310 @@
+/**
+ * crossModelReviewer — Step B of the tiered development process.
+ *
+ * Re-platforms the `/spec-converge` external "cross-model" reviewer onto the
+ * agent's own installed `codex` CLI. The external pass that the skill used to
+ * describe as running "via the /crossreview pattern" (a never-built
+ * placeholder) is now a grounded mechanism: detect whether a supported reviewer
+ * framework is installed + authed, assemble the cross-model reviewer prompt
+ * (spec + referenced context, bounded to a budget), and run it THROUGH the
+ * existing `CodexCliIntelligenceProvider` (the factory with
+ * `framework: 'codex-cli'`, model `capable` → GPT-tier).
+ *
+ * Design invariants (see docs/specs/codex-crossreview-stepB-spec.md):
+ *   - Detection is a pure function with injectable inputs (no real spawns in
+ *     unit tests). It is SIGNAL-ONLY — it never throws and never blocks.
+ *   - Reviewer invocation reuses the provider (its scratch-dir clean-notepad,
+ *     env allowlist, `--skip-git-repo-check`, and the account-global circuit
+ *     breaker the factory wraps it in). The ONLY new spawn-adjacent code is
+ *     prompt assembly + result parsing.
+ *   - Every failure mode routes toward internal-only convergence or a captured
+ *     raw finding — never a stall. `unavailable` (no framework) is distinct
+ *     from `degraded` (framework present, this call failed) and
+ *     `skipped-abbreviated` (author chose the fast path).
+ *
+ * codex is the FIRST supported framework; the registry
+ * (`SUPPORTED_REVIEWER_FRAMEWORKS`) is the single seam for gemini-cli and
+ * others to plug in later (Out of Scope here). Adding a framework is one
+ * registry entry + one `id`-union extension — no skill change.
+ */
+import { type IntelligenceFramework } from './intelligenceProviderFactory.js';
+/**
+ * Per-call timeout for a cross-model spec review. A reasoning review of a
+ * full spec is far heavier than the provider's 30s judgment-call default, so
+ * Step B bumps it to 120s (spec §2).
+ */
+export declare const REVIEW_TIMEOUT_MS = 120000;
+/**
+ * Total context budget (spec + referenced docs) inlined into the reviewer
+ * prompt. codex runs in an empty read-only scratch dir with no repo access,
+ * so referenced context MUST be inlined; this bounds the prompt size (spec §2).
+ * The spec is always included in full; referenced context fills the remainder
+ * and is truncated (with a loud note) if it overflows.
+ */
+export declare const CONTEXT_BUDGET_BYTES: number;
+/**
+ * Deterministic priority ordering for referenced context (spec §2, F4).
+ *
+ * When the 60KB budget can't hold every referenced doc, truncation MUST be
+ * deterministic — the same spec + same docs always drop the same docs — so a
+ * review is reproducible and the "what got dropped" note is stable. The
+ * constitutional / lessons docs are the highest-value context for a reviewer
+ * (they're what the lessons-aware internal reviewer reads), so they are kept
+ * FIRST; everything else keeps the spec-declared link order (the order the
+ * caller passed the docs in, which is the order they appear in the spec).
+ *
+ * A doc whose path contains one of these substrings sorts ahead of the rest,
+ * in THIS order. Ties (and all non-priority docs) preserve the caller's order
+ * via a stable sort.
+ */
+export declare const CONTEXT_PRIORITY_SUBSTRINGS: readonly string[];
+/**
+ * Order referenced context deterministically: constitutional/lessons docs
+ * first (per CONTEXT_PRIORITY_SUBSTRINGS), then the caller's spec-declared link
+ * order for the rest. A stable sort on the priority rank achieves both — equal
+ * ranks keep their input order. Pure; never mutates the input.
+ */
+export declare function orderContextDeterministically(context: readonly ReferencedContextDoc[]): ReferencedContextDoc[];
+/**
+ * Reasons a supported reviewer framework is unavailable. Mirrors the
+ * Rule-1 / auth-probe vocabulary so a report can render a specific
+ * remediation.
+ */
+export type CrossModelUnavailableReason = 'codex-not-installed' | 'codex-not-authed' | 'codex-auth-apikey-forbidden' | 'no-supported-framework';
+export interface CrossModelDetectionResult {
+    available: boolean;
+    /** Present when available; the framework id that will run the review. */
+    framework?: IntelligenceFramework;
+    /** Present when available; the concrete model the review resolves to. */
+    model?: string;
+    /** Present when unavailable; a specific machine-readable reason. */
+    reason?: CrossModelUnavailableReason;
+}
+/**
+ * Injectable inputs for `detectCrossModelReviewer` so the detection logic is
+ * unit-testable without real spawns or a real `~/.codex/auth.json`.
+ */
+export interface CrossModelDetectInputs {
+    /**
+     * Path to the codex binary if detected, else null. Defaults to
+     * `detectCodexPath()` (PATH + asdf/nvm-shim resolution).
+     */
+    codexPathDetected?: string | null;
+    /**
+     * Path to the codex auth.json. Defaults to
+     * `${CODEX_HOME || ~/.codex}/auth.json`.
+     */
+    authJsonPath?: string;
+    /** Process env (for the Rule-1 OPENAI_API_KEY probe). Defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Clock injection for the Rule-1 killswitch sunset check. */
+    now?: Date;
+}
+/**
+ * Detect a codex reviewer. Returns `{ available: true, framework, model }`
+ * iff ALL of: codex binary detected, OAuth `access_token` present, Rule-1
+ * clean (no raw API key in env or auth.json). Any miss → a specific reason.
+ *
+ * Pure-ish: all external inputs are injectable. With no inputs it probes the
+ * real host. It NEVER throws.
+ */
+export declare function detectCodexReviewer(inputs?: CrossModelDetectInputs): CrossModelDetectionResult;
+export interface ReviewerResult {
+    /** Outcome class for the cross-model pass. */
+    status: 'ok' | 'degraded' | 'unavailable';
+    /** The framework that ran (or would have run). */
+    framework?: IntelligenceFramework;
+    /** Concrete model used. */
+    model?: string;
+    /** Parsed verdict, when the review returned. */
+    verdict?: ReviewVerdict;
+    /** Structured findings (one record), folded alongside internal reviewers. */
+    findings?: ReviewFinding[];
+    /** A reason string for degraded/unavailable outcomes. */
+    reason?: string;
+    /** The flag string that gets written to frontmatter + the report banner. */
+    flag: string;
+}
+export type ReviewVerdict = 'CLEAN' | 'MINOR ISSUES' | 'SERIOUS ISSUES' | 'UNKNOWN';
+export interface ReviewFinding {
+    /** Reviewer tag, e.g. 'cross-model:codex-cli:gpt-5.5'. */
+    reviewer: string;
+    verdict: ReviewVerdict;
+    /** The findings body (verbatim text the reviewer produced). */
+    body: string;
+    /** True when the reply could not be parsed into a verdict (captured raw). */
+    unstructured?: boolean;
+}
+interface SupportedReviewerFramework {
+    /** Extend this union (in the type below) to add a framework. */
+    id: IntelligenceFramework;
+    /** Detection — does this framework's reviewer have what it needs to run? */
+    detect(inputs?: CrossModelDetectInputs): CrossModelDetectionResult;
+    /**
+     * Run the review: assemble already done by the caller; this builds the
+     * provider, evaluates the prompt, and parses the result. Returns a
+     * ReviewerResult (never throws — failures map to a degraded result).
+     */
+    review(args: ReviewerInvokeArgs): Promise<ReviewerResult>;
+}
+export interface ReviewerInvokeArgs {
+    /** The fully-assembled cross-model reviewer prompt (prompt + spec + context). */
+    promptText: string;
+    /** Per-call timeout. */
+    timeoutMs: number;
+    /**
+     * Optional provider override — tests inject a stub so no real codex spawn
+     * happens. Production passes nothing and the factory builds the real one.
+     */
+    providerOverride?: {
+        evaluate(prompt: string, options?: {
+            model?: 'fast' | 'balanced' | 'capable';
+            timeoutMs?: number;
+        }): Promise<string>;
+    };
+}
+/**
+ * The supported-reviewer registry. codex first — the order IS the preference
+ * order. gemini-cli and others land here as later steps (Out of Scope).
+ */
+export declare const SUPPORTED_REVIEWER_FRAMEWORKS: SupportedReviewerFramework[];
+/**
+ * Walk the registry in preference order and return the FIRST available
+ * framework's detection result. If none is available, returns the codex
+ * reason when there's exactly one entry (so the report can be specific), else
+ * the generic `no-supported-framework`.
+ *
+ * SIGNAL-ONLY: never throws, never blocks. A `false` simply routes the skill
+ * to the internal-only fallback (spec §4).
+ */
+export declare function detectCrossModelReviewer(inputs?: CrossModelDetectInputs): CrossModelDetectionResult;
+/**
+ * Map a provider rejection into a coarse `degraded` reason. The provider
+ * surfaces timeouts, non-zero exits, and (via the circuit breaker) rate
+ * limits as thrown Errors; we classify on the message text the same way the
+ * rate-limit classifier does.
+ */
+export declare function classifyReviewFailure(err: unknown): string;
+/**
+ * Parse a reviewer reply into a structured finding. The prompt mandates a
+ * `Verdict: CLEAN | MINOR ISSUES | SERIOUS ISSUES` line + a findings list. If
+ * the verdict line is unparseable (or the reply is blank), the whole reply is
+ * captured as one raw "unstructured external review — read manually" finding
+ * (never dropped, never thrown, never zero).
+ */
+export declare function parseReviewerReply(raw: string, reviewerTag: string): ReviewFinding;
+export interface ReferencedContextDoc {
+    /** Repo-relative path used as the `--- CONTEXT: <path> ---` header. */
+    path: string;
+    /** The doc's contents (already read by the caller). */
+    content: string;
+}
+export interface AssemblePromptInputs {
+    /** Contents of skills/spec-converge/templates/reviewer-cross-model.md. */
+    reviewerTemplate: string;
+    /** The full spec markdown. */
+    specMarkdown: string;
+    /** Repo-relative spec path, substituted for {SPEC_PATH} in the template. */
+    specPath: string;
+    /** Referenced architectural context docs (same set internal reviewers see). */
+    context?: ReferencedContextDoc[];
+    /** Total budget in bytes. Defaults to CONTEXT_BUDGET_BYTES. */
+    budgetBytes?: number;
+}
+export interface AssembledPrompt {
+    /** The final prompt string fed to the provider. */
+    promptText: string;
+    /** True when referenced context had to be truncated to fit the budget. */
+    truncated: boolean;
+    /** Byte size of the assembled prompt. */
+    bytes: number;
+}
+/**
+ * Assemble the cross-model reviewer prompt: the reviewer template (with
+ * `{SPEC_PATH}` substituted) + the full spec + as much referenced context as
+ * fits the budget. codex runs with NO repo access, so context is inlined under
+ * `--- CONTEXT: <path> ---` headers. The spec is ALWAYS included in full; if
+ * referenced docs overflow the budget, they are truncated and a loud
+ * truncation note is added so the reviewer knows its view was partial (a
+ * silently-truncated review is a trap; a disclosed-partial one is still signal).
+ *
+ * Truncation is DETERMINISTIC (spec §2, F4): referenced docs are ordered by
+ * `orderContextDeterministically` (constitutional/lessons docs first, then the
+ * spec-declared link order) BEFORE the budget walk, so the same spec + docs
+ * always drop the same docs. When a doc is fully or partially dropped, the
+ * truncation note NAMES the affected docs (which were partial, which were fully
+ * omitted) — a reviewer must know exactly which context it could not see, not
+ * just that "something" was cut.
+ */
+export declare function assembleReviewerPrompt(inputs: AssemblePromptInputs): AssembledPrompt;
+/**
+ * The discrete cross-model review outcome states the report + frontmatter
+ * record. Distinct so "you have no cross-model reviewer" reads differently
+ * from "your reviewer was rate-limited this round" from "you chose the fast
+ * path" from "the framework was present but NOT ONE round ever succeeded".
+ *
+ * `degraded-all-rounds` (spec §2/§4, F2) is the SPEC-LEVEL aggregate: a single
+ * round's `degraded` lives on a ReviewerResult, but convergence runs many
+ * rounds and the spec gets ONE final `cross-model-review:` value. When a
+ * framework was present every round but ZERO rounds produced a successful
+ * external pass (all degraded), the final flag is `degraded-all-rounds` —
+ * treated as loud as `unavailable`, because the spec converged having never
+ * once received a real external opinion. This must surface at SPEC level, not
+ * hide in per-round notes.
+ */
+export type CrossModelFlagStatus = 'available' | 'unavailable' | 'degraded' | 'degraded-all-rounds' | 'skipped-abbreviated';
+export interface CrossModelFlag {
+    status: CrossModelFlagStatus;
+    /** The `cross-model-review:` frontmatter value. */
+    flag: string;
+    /** Optional `cross-model-review-reason:` value. */
+    reason?: string;
+}
+/**
+ * Build the fallback flag for the unavailable / skipped / degraded-all-rounds
+ * states. (The available and per-round degraded flags come back on the
+ * ReviewerResult.) Centralizes the exact strings the frontmatter writer +
+ * report banner consume.
+ *
+ * `degraded-all-rounds` is the spec-level aggregate the skill writes when a
+ * framework was present but no round ever succeeded (see
+ * `aggregateRoundOutcomes`).
+ */
+export declare function buildCrossModelFlag(status: 'unavailable' | 'skipped-abbreviated' | 'degraded-all-rounds', reason?: string): CrossModelFlag;
+/**
+ * Aggregate per-round cross-model outcomes into the ONE final spec-level flag
+ * (spec §2/§4, F2). Convergence runs multiple rounds; each round yields a
+ * `ReviewerResult` (`ok` / `degraded` / `unavailable`). The skill collects the
+ * per-round statuses and calls this to decide what `write-convergence-tag.mjs`
+ * stamps:
+ *
+ *   - `skipped-abbreviated` if the author opted out (passed explicitly) — wins
+ *     over everything, since no external pass was attempted by choice.
+ *   - `codex-cli:<model>` (the LAST successful round's flag) if ANY round got a
+ *     real external pass — one genuine outside opinion is enough to say the spec
+ *     received cross-model review.
+ *   - `degraded-all-rounds` if a framework was present every round but ZERO
+ *     rounds succeeded (all degraded) — as loud as `unavailable`.
+ *   - `unavailable` if no framework was ever available (all rounds unavailable).
+ *
+ * Returns the `{ flag, reason }` the tag writer + report banner consume.
+ */
+export declare function aggregateRoundOutcomes(rounds: ReviewerResult[], opts?: {
+    skippedAbbreviated?: boolean;
+}): CrossModelFlag;
+/**
+ * The high-level entry the skill driver calls: detect, and if available run
+ * the first available framework's reviewer with the assembled prompt;
+ * otherwise return the `unavailable` flag. NEVER throws, NEVER blocks.
+ *
+ * `assembled` is produced by `assembleReviewerPrompt`. `detectInputs` and
+ * `providerOverride` exist for tests; production omits them.
+ */
+export declare function runCrossModelReview(args: {
+    assembled: AssembledPrompt;
+    timeoutMs?: number;
+    detectInputs?: CrossModelDetectInputs;
+    providerOverride?: ReviewerInvokeArgs['providerOverride'];
+}): Promise<ReviewerResult>;
+export {};
+//# sourceMappingURL=crossModelReviewer.d.ts.map

package/dist/core/crossModelReviewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crossModelReviewer.d.ts","sourceRoot":"","sources":["../../src/core/crossModelReviewer.ts"],"names":[],"mappings":"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"}