instar 1.3.191 → 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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"}

package/dist/core/crossModelReviewer.js

@@ -0,0 +1,489 @@
+/**
+ * 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 fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { detectCodexPath } from './Config.js';
+import { validateRule1 } from '../providers/adapters/openai-codex/credentials.js';
+import { resolveCliModelFlag } from '../providers/adapters/openai-codex/models.js';
+import { buildIntelligenceProvider, } from './intelligenceProviderFactory.js';
+// ── Constants (tunable) ─────────────────────────────────────────────────
+/**
+ * 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 const REVIEW_TIMEOUT_MS = 120_000;
+/**
+ * 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 const CONTEXT_BUDGET_BYTES = 60 * 1024;
+/**
+ * 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 const CONTEXT_PRIORITY_SUBSTRINGS = [
+    'signal-vs-authority',
+    'INSTAR-DESIGN-PRINCIPLES-AND-LESSONS',
+    'STANDARDS-REGISTRY',
+    'integrated-being',
+];
+/**
+ * Return a deterministic priority rank for a context doc path: a small index
+ * for a constitutional/lessons doc (earlier substring = smaller rank), or a
+ * large sentinel for everything else (so non-priority docs keep their relative
+ * order behind the priority ones under a stable sort).
+ */
+function contextPriorityRank(docPath) {
+    const lower = docPath.toLowerCase();
+    for (let i = 0; i < CONTEXT_PRIORITY_SUBSTRINGS.length; i++) {
+        if (lower.includes(CONTEXT_PRIORITY_SUBSTRINGS[i].toLowerCase()))
+            return i;
+    }
+    return CONTEXT_PRIORITY_SUBSTRINGS.length;
+}
+/**
+ * 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 function orderContextDeterministically(context) {
+    return context
+        .map((doc, idx) => ({ doc, idx, rank: contextPriorityRank(doc.path) }))
+        .sort((a, b) => a.rank - b.rank || a.idx - b.idx)
+        .map((e) => e.doc);
+}
+/** The canonical model tier a heavyweight cross-model review requests. */
+const REVIEW_MODEL_TIER = 'capable';
+/** Resolve the default codex auth.json path (CODEX_HOME-aware). */
+function defaultAuthJsonPath(env) {
+    const home = env['CODEX_HOME'] || path.join(os.homedir(), '.codex');
+    return path.join(home, 'auth.json');
+}
+/**
+ * Is the codex auth.json an OAuth (`tokens.access_token`) shape? This is the
+ * subscription-OAuth shape D3 requires. A missing / unreadable / malformed
+ * file → false (not authed). Uses the same probe shape as the codex smoketest.
+ */
+function authHasOAuthAccessToken(authJsonPath) {
+    try {
+        const raw = fs.readFileSync(authJsonPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed?.tokens?.access_token === 'string' && parsed.tokens.access_token.length > 0;
+    }
+    catch {
+        // missing / unreadable / malformed → not authed.
+        return false;
+    }
+}
+/**
+ * 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 function detectCodexReviewer(inputs = {}) {
+    const env = inputs.env ?? process.env;
+    const now = inputs.now ?? new Date();
+    const codexPath = inputs.codexPathDetected !== undefined ? inputs.codexPathDetected : detectCodexPath();
+    const authJsonPath = inputs.authJsonPath ?? defaultAuthJsonPath(env);
+    // 1. Binary present?
+    if (!codexPath) {
+        return { available: false, reason: 'codex-not-installed' };
+    }
+    // 2. Rule-1 clean? (API-key forbidden — env OPENAI_API_KEY or auth.json
+    //    API-key shape). Reuses existing policy rather than inventing one.
+    const rule1 = validateRule1(env, authJsonPath, now);
+    if (!rule1.ok) {
+        // The killswitch-expired / apikey-detected codes all collapse to the same
+        // policy outcome here: a forbidden credential shape → reviewer unavailable.
+        return { available: false, reason: 'codex-auth-apikey-forbidden' };
+    }
+    // 3. Authed via subscription OAuth?
+    if (!authHasOAuthAccessToken(authJsonPath)) {
+        return { available: false, reason: 'codex-not-authed' };
+    }
+    return {
+        available: true,
+        framework: 'codex-cli',
+        model: resolveCliModelFlag(REVIEW_MODEL_TIER),
+    };
+}
+/**
+ * The codex reviewer entry. Detection delegates to `detectCodexReviewer`;
+ * `review` routes through the factory-built `CodexCliIntelligenceProvider`.
+ */
+const codexReviewer = {
+    id: 'codex-cli',
+    detect: (inputs) => detectCodexReviewer(inputs),
+    review: async (args) => {
+        const detection = detectCodexReviewer();
+        const model = detection.model ?? resolveCliModelFlag(REVIEW_MODEL_TIER);
+        const tag = `cross-model:codex-cli:${model}`;
+        // Build (or accept an injected) provider. The factory wraps it in the
+        // account-global circuit breaker, so a rate-limited review degrades the
+        // same way every other instar LLM call does.
+        const provider = args.providerOverride ??
+            buildIntelligenceProvider({ framework: 'codex-cli' });
+        if (!provider) {
+            // Binary vanished between detect and review (or detection said
+            // unavailable and review was called anyway). Degraded, not a throw.
+            return {
+                status: 'degraded',
+                framework: 'codex-cli',
+                model,
+                reason: 'provider-unavailable',
+                flag: `cross-model-review: codex-cli:${model} (degraded: provider-unavailable)`,
+            };
+        }
+        let raw;
+        try {
+            raw = await provider.evaluate(args.promptText, {
+                model: REVIEW_MODEL_TIER,
+                timeoutMs: args.timeoutMs,
+            });
+        }
+        catch (err) {
+            const reason = classifyReviewFailure(err);
+            return {
+                status: 'degraded',
+                framework: 'codex-cli',
+                model,
+                reason,
+                flag: `cross-model-review: codex-cli:${model} (degraded: ${reason})`,
+            };
+        }
+        const parsed = parseReviewerReply(raw, tag);
+        return {
+            status: 'ok',
+            framework: 'codex-cli',
+            model,
+            verdict: parsed.verdict,
+            findings: [parsed],
+            flag: `cross-model-review: codex-cli:${model}`,
+        };
+    },
+};
+/**
+ * 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 const SUPPORTED_REVIEWER_FRAMEWORKS = [codexReviewer];
+/**
+ * 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 function detectCrossModelReviewer(inputs = {}) {
+    for (const framework of SUPPORTED_REVIEWER_FRAMEWORKS) {
+        const result = framework.detect(inputs);
+        if (result.available)
+            return result;
+    }
+    // Nothing available. Surface the single framework's specific reason when
+    // there's only one entry (codex today); otherwise the generic reason.
+    if (SUPPORTED_REVIEWER_FRAMEWORKS.length === 1) {
+        return SUPPORTED_REVIEWER_FRAMEWORKS[0].detect(inputs);
+    }
+    return { available: false, reason: 'no-supported-framework' };
+}
+// ── Failure classification ──────────────────────────────────────────────
+/**
+ * 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 function classifyReviewFailure(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const lower = msg.toLowerCase();
+    if (/circuit breaker|rate.?limit|usage limit|quota|429|too many requests/.test(lower)) {
+        return 'rate-limited';
+    }
+    if (/timed out|timeout|etimedout|killed/.test(lower)) {
+        return 'timeout';
+    }
+    return 'error';
+}
+// ── Reviewer reply parsing ──────────────────────────────────────────────
+/**
+ * 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 function parseReviewerReply(raw, reviewerTag) {
+    const text = (raw ?? '').trim();
+    if (!text) {
+        return {
+            reviewer: reviewerTag,
+            verdict: 'UNKNOWN',
+            body: '(empty reviewer reply — codex returned no output; read manually)',
+            unstructured: true,
+        };
+    }
+    const verdict = extractVerdict(text);
+    if (verdict === 'UNKNOWN') {
+        return {
+            reviewer: reviewerTag,
+            verdict: 'UNKNOWN',
+            body: `unstructured external review — read manually:\n${text}`,
+            unstructured: true,
+        };
+    }
+    return {
+        reviewer: reviewerTag,
+        verdict,
+        body: text,
+    };
+}
+/**
+ * Extract the verdict from a reviewer reply. Looks for a `Verdict:` line and
+ * matches one of the three canonical values (case-insensitive, tolerant of
+ * surrounding markdown like `**Verdict: SERIOUS ISSUES**`). Returns 'UNKNOWN'
+ * when none is found.
+ */
+function extractVerdict(text) {
+    // Find a line mentioning "Verdict" and inspect its content.
+    const verdictLine = text
+        .split('\n')
+        .find((l) => /verdict/i.test(l));
+    const haystack = (verdictLine ?? text).toUpperCase();
+    // Order matters: check the most specific multi-word verdicts first.
+    if (haystack.includes('SERIOUS ISSUES'))
+        return 'SERIOUS ISSUES';
+    if (haystack.includes('MINOR ISSUES'))
+        return 'MINOR ISSUES';
+    if (haystack.includes('CLEAN'))
+        return 'CLEAN';
+    return 'UNKNOWN';
+}
+/**
+ * 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 function assembleReviewerPrompt(inputs) {
+    const budget = inputs.budgetBytes ?? CONTEXT_BUDGET_BYTES;
+    const template = inputs.reviewerTemplate.replace(/\{SPEC_PATH\}/g, inputs.specPath);
+    const header = `${template}\n\n--- SPEC UNDER REVIEW: ${inputs.specPath} ---\n${inputs.specMarkdown}\n`;
+    const parts = [header];
+    let used = Buffer.byteLength(header, 'utf-8');
+    let truncated = false;
+    // Deterministic priority order: constitutional/lessons docs first, then the
+    // spec-declared link order. Same inputs always drop the same docs.
+    const context = orderContextDeterministically(inputs.context ?? []);
+    // Track exactly which docs were partially included vs fully dropped so the
+    // truncation note can NAME them (F4 — a named-partial review is signal; a
+    // "something was cut" review is a trap).
+    let partialDoc = null;
+    const droppedDocs = [];
+    for (let i = 0; i < context.length; i++) {
+        const doc = context[i];
+        const docHeader = `\n--- CONTEXT: ${doc.path} ---\n`;
+        const docBlock = `${docHeader}${doc.content}\n`;
+        const docBytes = Buffer.byteLength(docBlock, 'utf-8');
+        if (!truncated && used + docBytes <= budget) {
+            parts.push(docBlock);
+            used += docBytes;
+            continue;
+        }
+        // Budget exceeded at this doc. Include as much of THIS doc as the remaining
+        // budget allows (header always; body sliced), record it as PARTIAL, then
+        // mark every remaining doc as fully DROPPED. We do NOT break — we keep
+        // walking so the note can name all the dropped docs, not just the first.
+        if (!truncated) {
+            const remaining = budget - used - Buffer.byteLength(docHeader, 'utf-8');
+            if (remaining > 0) {
+                // Slice by bytes safely (avoid splitting a multibyte char by slicing
+                // the buffer then decoding with replacement tolerated).
+                const sliced = Buffer.from(doc.content, 'utf-8').subarray(0, remaining).toString('utf-8');
+                parts.push(`${docHeader}${sliced}`);
+                partialDoc = doc.path;
+            }
+            else {
+                // Not even the header fits — this doc is fully dropped too.
+                droppedDocs.push(doc.path);
+            }
+            truncated = true;
+            continue;
+        }
+        // Already truncated — every subsequent doc is fully omitted.
+        droppedDocs.push(doc.path);
+    }
+    if (truncated) {
+        const detail = [];
+        if (partialDoc)
+            detail.push(`PARTIAL (cut mid-document): ${partialDoc}`);
+        if (droppedDocs.length > 0)
+            detail.push(`FULLY OMITTED: ${droppedDocs.join(', ')}`);
+        const named = detail.length > 0 ? ` ${detail.join('. ')}.` : '';
+        parts.push('\n\n--- NOTE: referenced context was TRUNCATED to fit the review budget.' +
+            named +
+            ' Your view of the supporting docs is PARTIAL — flag any finding that ' +
+            'depends on context you could not see. ---\n');
+    }
+    const promptText = parts.join('');
+    return {
+        promptText,
+        truncated,
+        bytes: Buffer.byteLength(promptText, 'utf-8'),
+    };
+}
+/**
+ * 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 function buildCrossModelFlag(status, reason) {
+    if (status === 'unavailable') {
+        return { status, flag: 'cross-model-review: unavailable', reason };
+    }
+    if (status === 'degraded-all-rounds') {
+        return { status, flag: 'cross-model-review: degraded-all-rounds', reason };
+    }
+    return { status, flag: 'cross-model-review: skipped-abbreviated', reason };
+}
+/**
+ * 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 function aggregateRoundOutcomes(rounds, opts = {}) {
+    if (opts.skippedAbbreviated) {
+        return buildCrossModelFlag('skipped-abbreviated');
+    }
+    if (rounds.length === 0) {
+        // No rounds recorded at all — treat as no external reviewer available.
+        return buildCrossModelFlag('unavailable', 'no-rounds-recorded');
+    }
+    // Any successful round → the spec received a real external opinion. Use the
+    // LAST successful round's flag (the freshest pass on the most-converged spec).
+    const successful = rounds.filter((r) => r.status === 'ok');
+    if (successful.length > 0) {
+        const last = successful[successful.length - 1];
+        return { status: 'available', flag: last.flag, ...(last.reason ? { reason: last.reason } : {}) };
+    }
+    // No successes. Was a framework ever present? If ANY round degraded (vs
+    // unavailable), the framework was there but never delivered → all-rounds.
+    const anyDegraded = rounds.some((r) => r.status === 'degraded');
+    if (anyDegraded) {
+        // Surface the most recent degraded reason for the `-reason` field.
+        const lastDegraded = [...rounds].reverse().find((r) => r.status === 'degraded');
+        return buildCrossModelFlag('degraded-all-rounds', lastDegraded?.reason);
+    }
+    // Every round was unavailable (no framework, ever).
+    const lastUnavailable = [...rounds].reverse().find((r) => r.status === 'unavailable');
+    return buildCrossModelFlag('unavailable', lastUnavailable?.reason);
+}
+/**
+ * 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 async function runCrossModelReview(args) {
+    const detection = detectCrossModelReviewer(args.detectInputs);
+    if (!detection.available) {
+        const flag = buildCrossModelFlag('unavailable', detection.reason);
+        return {
+            status: 'unavailable',
+            reason: detection.reason,
+            flag: flag.flag,
+        };
+    }
+    const framework = SUPPORTED_REVIEWER_FRAMEWORKS.find((f) => f.id === detection.framework);
+    if (!framework) {
+        // Defensive: detection named a framework with no registry entry.
+        const flag = buildCrossModelFlag('unavailable', 'no-supported-framework');
+        return { status: 'unavailable', reason: 'no-supported-framework', flag: flag.flag };
+    }
+    return framework.review({
+        promptText: args.assembled.promptText,
+        timeoutMs: args.timeoutMs ?? REVIEW_TIMEOUT_MS,
+        ...(args.providerOverride ? { providerOverride: args.providerOverride } : {}),
+    });
+}
+//# sourceMappingURL=crossModelReviewer.js.map

package/dist/core/crossModelReviewer.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.191",
+  "version": "1.3.192",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-01T22:39:21.302Z",
-  "instarVersion": "1.3.191",
+  "generatedAt": "2026-06-02T00:19:44.300Z",
+  "instarVersion": "1.3.192",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.192.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Spec-review-convergence's external **cross-model reviewer** is now real and framework-native:
+instead of a placeholder API path, it detects the installed **codex CLI** and runs a
+GPT-tier second opinion through the existing hardened codex provider — so any instar agent
+with codex gets cross-model review for free, no API keys. When no supported reviewer is
+installed (or a call fails, or convergence is abbreviated) the spec carries a loud,
+honest `cross-model-review:` flag; the review is **signal, never a gate**. Step B of the
+tiered-development project.
+
+## What to Tell Your User
+
+Nothing to do — this only affects how the agent reviews its own instar specs. Specs now get
+a real outside-model opinion when codex is present, and a clearly-marked note when they
+don't, so a spec that never got an external review can't quietly look like it did.
+
+## Summary of New Capabilities
+
+- `src/core/crossModelReviewer.ts` — codex-CLI reviewer detection + a supported-reviewer
+  registry + the reviewer driver (via the existing codex provider) + the honest flag
+  machinery (`codex-cli:<model>` / `degraded` / `degraded-all-rounds` / `unavailable` /
+  `skipped-abbreviated`), with deterministic, named context truncation.
+- `skills/spec-converge/scripts/cross-model-review.mjs` — the CLI the convergence skill
+  calls; `write-convergence-tag.mjs` gains `--cross-model-review`; `SKILL.md` + the reviewer
+  prompt template now describe the real, inlined-context, single-codex-pass mechanism.
+
+## Evidence
+
+- `npx tsc --noEmit` exit 0; Step-B tests 53 green (45 + 5 unit, 3 integration); `npm run
+  lint` green. Detection live-validated on this host: `{"available":true,
+  "framework":"codex-cli","model":"gpt-5.5"}`.
+- Dev-only tooling: `/spec-converge` is not shipped to end-agent homes, so no migration.

package/upgrades/side-effects/codex-crossreview-stepB.md

@@ -0,0 +1,83 @@
+# Side-Effects Review — Cross-model review on the codex CLI (Step B)
+
+**Slug:** `codex-crossreview-stepB`
+**Date:** 2026-06-01
+**Author:** echo
+**Spec:** `docs/specs/codex-crossreview-stepB-spec.md` (approved by Justin + abbreviated convergence, 5 findings folded)
+**Project:** Step B of the Tiered Development Process (`docs/projects/tiered-dev-process/PROJECT.md`)
+
+## Summary of the change
+
+Re-platforms the external **cross-model reviewer** in spec-review-convergence from the
+(placeholder) `/crossreview` API path onto the **installed codex CLI**, so every instar
+agent with codex gets a GPT-tier second opinion for free, no API keys. Honors the
+constitution's **Signal vs. Authority** — the external review is *signal*, never a
+blocking authority; an absent/failed reviewer is disclosed loudly, never faked.
+
+**Files changed (in-scope):**
+- `src/core/crossModelReviewer.ts` (NEW) — detection (`detectCodexReviewer` /
+  `detectCrossModelReviewer`: codex binary present AND OAuth `tokens.access_token` AND
+  Rule-1 clean), the `SUPPORTED_REVIEWER_FRAMEWORKS` registry (codex first; one entry per
+  future framework), the reviewer driver (routes the cross-model prompt through the
+  existing `buildIntelligenceProvider({framework:'codex-cli'})` → gpt-5.5, 120s, reusing
+  the provider's env allowlist + the factory circuit breaker), `assembleReviewerPrompt`
+  (inlines the spec in full + referenced context under a 60KB budget with **deterministic**
+  priority order — constitutional docs first — and a truncation note that **names** the
+  partial + omitted docs), `parseReviewerReply` (never throws/zeroes), and the flag
+  machinery: `buildCrossModelFlag` + `aggregateRoundOutcomes` producing one of
+  `codex-cli:<model>` (ran) / `degraded` / `degraded-all-rounds` / `unavailable` /
+  `skipped-abbreviated`. Never throws, never blocks.
+- `skills/spec-converge/scripts/cross-model-review.mjs` (NEW) — the thin CLI the skill
+  shells out to (does only repo file-I/O — codex is sandboxed with no repo access —
+  delegating logic to compiled `dist/core/crossModelReviewer.js`; always exits 0).
+- `skills/spec-converge/scripts/write-convergence-tag.mjs` — `--cross-model-review` /
+  `--cross-model-reason` args writing the `cross-model-review:` frontmatter field
+  (idempotent, YAML-safe quoting).
+- `skills/spec-converge/SKILL.md` — replaced the `/crossreview` placeholder with the real
+  invocation; Phase 3 documents per-round aggregation (→ `degraded-all-rounds` when a
+  framework was present but **zero** rounds got a successful pass); Phase 4 renders a loud
+  `⚠` banner for **every** non-ran state (a real pass is the only unmarked one); Phase 5
+  the valid flag values. Internal reviewers + the Standards-Conformance Gate unchanged.
+
+**Files changed (not in-scope):** `skills/spec-converge/templates/reviewer-cross-model.md`
+(patched: spec + context are "inlined below" — no file-read instruction codex can't
+follow — and dropped the three-phantom-model GPT/Gemini/Grok framing → one codex pass);
+the spec + ELI16; tests (`tests/unit/crossModelReviewer.test.ts` 45,
+`tests/unit/write-convergence-tag-crossmodel.test.ts` 5,
+`tests/integration/cross-model-review-flow.test.ts` 3).
+
+## Blast radius
+
+Additive. The new module is pure/injectable except the one provider call (reusing the
+hardened codex provider). The convergence flow gains a real external reviewer where it had
+a placeholder; the internal reviewers, the lessons-aware (non-skippable) reviewer, and the
+Standards-Conformance gate are untouched. The reviewer never throws and never blocks — the
+worst case is a loudly-disclosed `unavailable` / `degraded` / `degraded-all-rounds` flag.
+The `cross-model-review:` flag is **disclosure, not a gate**: it does NOT touch the
+`review-convergence` + `approved` enforcement in `instar-dev-precommit.js`.
+
+## Risks considered
+
+- **Could a failed/absent review read as a clean pass?** No (convergence Finding 1/2): every
+  non-ran state carries a loud `⚠` banner, and a convergence where a framework was present
+  but *no* round ever succeeded collapses to a spec-level `degraded-all-rounds` (as loud as
+  `unavailable`) — "never actually got an external opinion" surfaces at spec level.
+- **Silent partial context?** No (Finding 4): truncation is deterministic (constitutional
+  docs first) and the note names the partial + fully-omitted docs.
+- **API-key leak through codex?** No — reuses `buildCodexChildEnv()`'s allowlist; Rule-1
+  (`validateRule1`) forbids an API-key-shaped credential; detection requires OAuth.
+- **Cost?** Worst case ~10 capable-tier calls per spec (the 10-round convergence cap × 1
+  call/round), bounded by the account circuit breaker. Stated in the spec.
+
+## Migration parity
+
+**None needed — verified.** `/spec-converge` is dev-only tooling: it is NOT in
+`package.json` `files[]` and NOT installed by `installBuiltinSkills()`, so it never lands
+in an end-agent home. No `PostUpdateMigrator` change. (The agents that *develop* instar get
+it from the repo.)
+
+## Tests / lint
+
+`npx tsc --noEmit` exit 0; Step-B tests 53 green (45+5 unit, 3 integration); `npm run lint`
+(tsc + destructive/LLM-http/url-log/codex-drift) green. (The worktree's ~28 pre-existing
+local failures — node v25.6.1 + real-config + tunnel — are independent and CI-green.)