@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/scripts/lib/review-non-interactive-handoff.js

@@ -0,0 +1,61 @@
+import path from 'node:path';
+import { prepareReviewArtifacts } from './review-launch-attempt.js';
+export function shouldForceNonInteractive(env, stdinIsTTY) {
+    return (!stdinIsTTY ||
+        envFlagEnabled(env.CI) ||
+        envFlagEnabled(env.CODEX_REVIEW_NON_INTERACTIVE) ||
+        envFlagEnabled(env.CODEX_NON_INTERACTIVE) ||
+        envFlagEnabled(env.CODEX_NO_INTERACTIVE) ||
+        envFlagEnabled(env.CODEX_NONINTERACTIVE));
+}
+export function shouldPrintNonInteractiveHandoff(params) {
+    return (params.nonInteractive &&
+        !envFlagEnabled(params.env.FORCE_CODEX_REVIEW) &&
+        (envFlagEnabled(params.env.CI) ||
+            !params.stdinIsTTY ||
+            envFlagEnabled(params.env.CODEX_REVIEW_NON_INTERACTIVE) ||
+            envFlagEnabled(params.env.CODEX_NON_INTERACTIVE) ||
+            envFlagEnabled(params.env.CODEX_NO_INTERACTIVE) ||
+            envFlagEnabled(params.env.CODEX_NONINTERACTIVE)));
+}
+export async function prepareReviewNonInteractiveHandoffShell(options) {
+    const artifactPaths = await prepareReviewArtifacts(options.manifestPath, options.prompt, options.repoRoot);
+    const nonInteractive = options.cliNonInteractive ?? shouldForceNonInteractive(options.env, options.stdinIsTTY);
+    const reviewEnv = { ...options.env };
+    reviewEnv.MANIFEST = options.manifestPath;
+    if (options.runnerLogExists) {
+        reviewEnv.RUNNER_LOG = options.runnerLogPath;
+        reviewEnv.RUN_LOG = options.runnerLogPath;
+    }
+    else {
+        delete reviewEnv.RUNNER_LOG;
+        delete reviewEnv.RUN_LOG;
+    }
+    if (nonInteractive) {
+        reviewEnv.CODEX_NON_INTERACTIVE = reviewEnv.CODEX_NON_INTERACTIVE ?? '1';
+        reviewEnv.CODEX_NO_INTERACTIVE = reviewEnv.CODEX_NO_INTERACTIVE ?? '1';
+        reviewEnv.CODEX_INTERACTIVE = reviewEnv.CODEX_INTERACTIVE ?? '0';
+    }
+    const handedOff = shouldPrintNonInteractiveHandoff({
+        env: options.env,
+        nonInteractive,
+        stdinIsTTY: options.stdinIsTTY
+    });
+    if (handedOff) {
+        const logger = options.logger ?? console;
+        logger.log('Codex review handoff (non-interactive):');
+        logger.log('---');
+        logger.log(options.prompt);
+        logger.log('---');
+        logger.log(`Review prompt saved to: ${path.relative(options.repoRoot, artifactPaths.promptPath)}`);
+        logger.log('Set FORCE_CODEX_REVIEW=1 to invoke `codex review` in this environment.');
+    }
+    return { artifactPaths, nonInteractive, reviewEnv, handedOff };
+}
+function envFlagEnabled(value) {
+    if (value === undefined) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}

package/dist/scripts/lib/review-prompt-context.js

@@ -0,0 +1,376 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { buildRunMemoryPromptLines, selectRunMemoryForRole } from '../../orchestrator/src/cli/run/runMemoryController.js';
+import { buildRunBlockMemoryPromptLines, readRunBlockMemoryDescriptor, readRunBlockMemoryIndex } from '../../orchestrator/src/cli/run/blockMemory.js';
+import { normalizeTaskKey, pathExists } from './docs-helpers.js';
+const DEFAULT_SCOPED_REVIEW_TITLE_MAX_LENGTH = 180;
+const BOUNDED_SCOPED_REVIEW_TITLE_SEGMENT = 'Bounded: no validation; list follow-up commands only';
+async function readTaskIndexEntries(repoRoot) {
+    const taskIndexPath = path.join(repoRoot, 'tasks', 'index.json');
+    if (!(await pathExists(taskIndexPath))) {
+        return [];
+    }
+    try {
+        const raw = await readFile(taskIndexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed?.items) ? parsed.items : [];
+    }
+    catch {
+        return [];
+    }
+}
+function extractTaskChecklistCandidate(item) {
+    const directTaskPath = typeof item.paths?.task === 'string'
+        ? item.paths.task.trim()
+        : typeof item.relates_to === 'string'
+            ? item.relates_to.trim()
+            : '';
+    if (directTaskPath.length > 0) {
+        return directTaskPath;
+    }
+    const legacyPath = typeof item.path === 'string' ? item.path.trim() : '';
+    const candidate = /(?:^|\/)tasks-[0-9]{4}-[A-Za-z0-9-]+\.md$/u.test(legacyPath) ? legacyPath : '';
+    return candidate.length > 0 ? candidate : null;
+}
+async function resolveRegisteredTaskChecklistPath(repoRoot, taskKey) {
+    const items = await readTaskIndexEntries(repoRoot);
+    if (items.length === 0) {
+        return null;
+    }
+    const keyedItems = items
+        .map((item) => ({
+        key: normalizeTaskKey(item),
+        checklistPath: extractTaskChecklistCandidate(item)
+    }))
+        .filter((entry) => typeof entry.key === 'string' &&
+        entry.key.length > 0 &&
+        typeof entry.checklistPath === 'string' &&
+        entry.checklistPath.length > 0)
+        .sort((left, right) => right.key.length - left.key.length);
+    const exact = keyedItems.find((entry) => entry.key === taskKey);
+    const prefix = keyedItems.find((entry) => taskKey.startsWith(`${entry.key}-`));
+    const selected = exact ?? prefix;
+    if (!selected) {
+        return null;
+    }
+    const absolute = path.resolve(repoRoot, selected.checklistPath);
+    return (await pathExists(absolute)) ? absolute : null;
+}
+async function resolveCanonicalTaskKey(repoRoot, taskKey) {
+    if (!taskKey) {
+        return null;
+    }
+    const items = await readTaskIndexEntries(repoRoot);
+    if (items.length === 0) {
+        return taskKey;
+    }
+    const keyedItems = items
+        .map((item) => ({ key: normalizeTaskKey(item) }))
+        .filter((entry) => typeof entry.key === 'string' && entry.key.length > 0)
+        .sort((left, right) => right.key.length - left.key.length);
+    const exact = keyedItems.find((entry) => entry.key === taskKey);
+    const prefix = keyedItems.find((entry) => taskKey.startsWith(`${entry.key}-`));
+    return exact?.key ?? prefix?.key ?? taskKey;
+}
+async function resolveTaskChecklistPath(repoRoot, taskKey) {
+    const direct = path.join(repoRoot, 'tasks', `tasks-${taskKey}.md`);
+    if (await pathExists(direct)) {
+        return direct;
+    }
+    if (!/^\d{4}$/.test(taskKey)) {
+        return null;
+    }
+    const tasksDir = path.join(repoRoot, 'tasks');
+    let entries = [];
+    try {
+        entries = await readdir(tasksDir);
+    }
+    catch {
+        return null;
+    }
+    const candidates = entries
+        .filter((name) => name.startsWith(`tasks-${taskKey}-`) && name.endsWith('.md'))
+        .map((name) => path.join(tasksDir, name))
+        .sort();
+    if (candidates.length === 1) {
+        return candidates[0] ?? null;
+    }
+    return null;
+}
+function extractTaskHeaderBulletLines(taskChecklist) {
+    const lines = taskChecklist.split('\n');
+    const checklistIndex = lines.findIndex((line) => line.trim() === '## Checklist');
+    const headerLines = checklistIndex === -1 ? lines : lines.slice(0, checklistIndex);
+    return headerLines
+        .map((line) => line.trimEnd())
+        .filter((line) => line.startsWith('- '));
+}
+function extractBacktickedPath(line) {
+    const match = line.match(/`([^`]+)`/);
+    return match?.[1] ?? null;
+}
+function extractTaskHeaderDocPath(headerBullets, patterns) {
+    const match = headerBullets.find((line) => {
+        const normalized = line.toLowerCase();
+        return patterns.some((pattern) => normalized.includes(pattern));
+    });
+    return match ? extractBacktickedPath(match) : null;
+}
+async function buildTaskContext(options) {
+    const checklistPath = (await resolveRegisteredTaskChecklistPath(options.repoRoot, options.taskKey)) ??
+        (await resolveTaskChecklistPath(options.repoRoot, options.taskKey));
+    if (!checklistPath) {
+        return { lines: [], architectureSurfacePaths: [] };
+    }
+    const relativeChecklist = path.relative(options.repoRoot, checklistPath);
+    const checklist = await readFile(checklistPath, 'utf8');
+    const headerBullets = extractTaskHeaderBulletLines(checklist);
+    const architectureSurfacePaths = options.surface === 'architecture' ? [checklistPath] : [];
+    const lines = ['Task context:', `- Task checklist: \`${relativeChecklist}\``];
+    const prdPath = extractTaskHeaderDocPath(headerBullets, ['primary prd:']);
+    if (prdPath) {
+        lines.push(`- Primary PRD: \`${prdPath}\``);
+        const absolutePrdPath = path.resolve(options.repoRoot, prdPath);
+        if (options.surface === 'architecture' && (await pathExists(absolutePrdPath))) {
+            architectureSurfacePaths.push(absolutePrdPath);
+        }
+    }
+    if (options.surface === 'architecture') {
+        const techSpecPath = extractTaskHeaderDocPath(headerBullets, ['tech_spec:', 'tech spec:']);
+        if (techSpecPath) {
+            lines.push(`- TECH_SPEC: \`${techSpecPath}\``);
+            const absoluteTechSpecPath = path.resolve(options.repoRoot, techSpecPath);
+            if (await pathExists(absoluteTechSpecPath)) {
+                architectureSurfacePaths.push(absoluteTechSpecPath);
+            }
+        }
+        const actionPlanPath = extractTaskHeaderDocPath(headerBullets, ['action_plan:', 'action plan:']);
+        if (actionPlanPath) {
+            lines.push(`- ACTION_PLAN: \`${actionPlanPath}\``);
+            const absoluteActionPlanPath = path.resolve(options.repoRoot, actionPlanPath);
+            if (await pathExists(absoluteActionPlanPath)) {
+                architectureSurfacePaths.push(absoluteActionPlanPath);
+            }
+        }
+        const architecturePath = path.join(options.repoRoot, '.agent', 'system', 'architecture.md');
+        if (await pathExists(architecturePath)) {
+            lines.push(`- Repo architecture baseline: \`${path.relative(options.repoRoot, architecturePath)}\``);
+            architectureSurfacePaths.push(architecturePath);
+        }
+    }
+    return { lines, architectureSurfacePaths };
+}
+async function resolveActiveCloseoutBundleRoots(repoRoot, taskKey) {
+    const canonicalTaskKey = await resolveCanonicalTaskKey(repoRoot, taskKey);
+    if (!canonicalTaskKey) {
+        return [];
+    }
+    const manualDir = path.join(repoRoot, 'out', canonicalTaskKey, 'manual');
+    if (!(await pathExists(manualDir))) {
+        return [];
+    }
+    let entries = [];
+    try {
+        entries = await readdir(manualDir);
+    }
+    catch {
+        return [];
+    }
+    const closeoutDirs = [];
+    for (const entry of entries) {
+        if (!(entry === 'TODO-closeout' || entry.endsWith('-closeout'))) {
+            continue;
+        }
+        const absolute = path.join(manualDir, entry);
+        try {
+            if ((await stat(absolute)).isDirectory()) {
+                closeoutDirs.push(absolute);
+            }
+        }
+        catch {
+            // ignore disappearing or unreadable entries
+        }
+    }
+    closeoutDirs.sort();
+    if (closeoutDirs.length === 0) {
+        return [];
+    }
+    const roots = new Set();
+    const todoCloseout = closeoutDirs.find((entry) => path.basename(entry) === 'TODO-closeout');
+    if (todoCloseout) {
+        roots.add(todoCloseout);
+    }
+    const completedCloseouts = closeoutDirs.filter((entry) => path.basename(entry) !== 'TODO-closeout');
+    const latestCompletedCloseout = completedCloseouts.at(-1);
+    if (latestCompletedCloseout) {
+        roots.add(latestCompletedCloseout);
+    }
+    return [...roots];
+}
+export function buildActiveCloseoutProvenanceLines(repoRoot, activeCloseoutBundleRoots) {
+    if (activeCloseoutBundleRoots.length === 0) {
+        return [];
+    }
+    return [
+        'Active closeout provenance:',
+        ...activeCloseoutBundleRoots.map((root) => `- Resolved active closeout root: \`${path.relative(repoRoot, root)}\``),
+        '- These roots are already-resolved self-referential review surfaces for this task; do not re-derive or re-enumerate them unless directly necessary to assess code correctness.'
+    ];
+}
+export function resolveReviewNotes(options) {
+    if (options.notes) {
+        return options.notes;
+    }
+    const fallback = `Goal: standalone review handoff | ` +
+        `Summary: auto-generated NOTES fallback (task=${options.taskLabel}, surface=${options.surface}) | ` +
+        'Risks: missing custom intent details may reduce review precision';
+    console.warn('[run-review] NOTES was not provided; using a generated fallback. ' +
+        'Set NOTES="Goal: ... | Summary: ... | Risks: ... | Questions (optional): ..." for higher-signal review context.');
+    return fallback;
+}
+function normalizeScopedReviewTitleSegment(value) {
+    return value.replace(/\s+/g, ' ').replace(/\s*\|\s*/g, ' | ').trim();
+}
+function compactScopedReviewTitleSegments(value) {
+    return value
+        .split('|')
+        .map((segment) => segment.replace(/\s+/g, ' ').trim())
+        .filter((segment) => segment.length > 0)
+        .join(' | ');
+}
+function removeBoundedScopedReviewTitleSegment(title) {
+    return compactScopedReviewTitleSegments(title.split(BOUNDED_SCOPED_REVIEW_TITLE_SEGMENT).join(' '));
+}
+function truncateScopedReviewTitle(title, maxLength) {
+    const normalizedMax = Number.isFinite(maxLength) ? Math.max(1, Math.trunc(maxLength)) : 1;
+    if (title.length <= normalizedMax) {
+        return title;
+    }
+    if (normalizedMax === 1) {
+        return '…';
+    }
+    return `${title.slice(0, normalizedMax - 1).trimEnd()}…`;
+}
+export function addBoundedReviewConstraintsToScopedTitle(options) {
+    const normalizedTitle = normalizeScopedReviewTitleSegment(options.title);
+    const maxLength = options.maxLength ?? DEFAULT_SCOPED_REVIEW_TITLE_MAX_LENGTH;
+    const untaggedTitle = removeBoundedScopedReviewTitleSegment(normalizedTitle);
+    if (untaggedTitle.length === 0) {
+        return truncateScopedReviewTitle(BOUNDED_SCOPED_REVIEW_TITLE_SEGMENT, maxLength);
+    }
+    const title = `${untaggedTitle} | ${BOUNDED_SCOPED_REVIEW_TITLE_SEGMENT}`;
+    if (title.length <= maxLength) {
+        return title;
+    }
+    const suffix = ` | ${BOUNDED_SCOPED_REVIEW_TITLE_SEGMENT}`;
+    const prefixBudget = maxLength - suffix.length;
+    if (prefixBudget <= 1) {
+        return truncateScopedReviewTitle(BOUNDED_SCOPED_REVIEW_TITLE_SEGMENT, maxLength);
+    }
+    return `${truncateScopedReviewTitle(untaggedTitle, prefixBudget)}${suffix}`;
+}
+export function buildScopedReviewTitle(options) {
+    const normalizedNotes = normalizeScopedReviewTitleSegment(options.notes);
+    const title = [
+        `Surface: ${options.reviewSurface}`,
+        options.includeBoundedReviewConstraints ? BOUNDED_SCOPED_REVIEW_TITLE_SEGMENT : '',
+        normalizedNotes
+    ]
+        .filter((segment) => segment.length > 0)
+        .join(' | ');
+    return truncateScopedReviewTitle(title, options.maxLength ?? DEFAULT_SCOPED_REVIEW_TITLE_MAX_LENGTH);
+}
+export async function buildReviewPromptContext(options) {
+    const notes = resolveReviewNotes({
+        notes: options.notes?.trim(),
+        taskLabel: options.taskLabel,
+        surface: options.reviewSurface
+    });
+    const scopedReviewerVisibleTitle = buildScopedReviewTitle({
+        notes,
+        reviewSurface: options.reviewSurface,
+        includeBoundedReviewConstraints: options.includeBoundedReviewConstraints
+    });
+    const activeCloseoutBundleRoots = options.reviewSurface === 'diff'
+        ? await resolveActiveCloseoutBundleRoots(options.repoRoot, options.taskKey)
+        : [];
+    const promptLines = [
+        `Review task: ${options.taskLabel}`,
+        `Review surface: ${options.reviewSurface}`
+    ];
+    let reviewTaskContext = { lines: [], architectureSurfacePaths: [] };
+    if (options.reviewSurface === 'audit') {
+        promptLines.push(`Evidence manifest: ${options.relativeManifest}`);
+        if (options.runnerLogExists) {
+            promptLines.push(`Evidence runner log: ${options.relativeRunnerLog}`);
+        }
+    }
+    if ((options.reviewSurface === 'audit' || options.reviewSurface === 'architecture') && options.taskKey) {
+        reviewTaskContext = await buildTaskContext({
+            repoRoot: options.repoRoot,
+            taskKey: options.taskKey,
+            surface: options.reviewSurface
+        });
+        if (reviewTaskContext.lines.length > 0) {
+            promptLines.push('', ...reviewTaskContext.lines);
+        }
+    }
+    const absoluteManifestPath = path.resolve(options.repoRoot, options.relativeManifest);
+    if (await pathExists(absoluteManifestPath)) {
+        try {
+            const rawManifest = JSON.parse(await readFile(absoluteManifestPath, 'utf8'));
+            const runMemoryPromptLines = buildRunMemoryPromptLines(selectRunMemoryForRole({
+                role: 'reviewer',
+                manifest: rawManifest
+            }));
+            if (runMemoryPromptLines.length > 0) {
+                promptLines.push('', ...runMemoryPromptLines);
+            }
+            const blockMemoryDescriptor = readRunBlockMemoryDescriptor(rawManifest);
+            if (blockMemoryDescriptor) {
+                const blockMemoryIndex = await readRunBlockMemoryIndex(options.repoRoot, blockMemoryDescriptor).catch(() => null);
+                const blockMemoryPromptLines = buildRunBlockMemoryPromptLines({
+                    descriptor: blockMemoryDescriptor,
+                    index: blockMemoryIndex
+                });
+                if (blockMemoryPromptLines.length > 0) {
+                    promptLines.push('', ...blockMemoryPromptLines);
+                }
+            }
+        }
+        catch {
+            // Ignore malformed manifests here and preserve the existing prompt scaffold.
+        }
+    }
+    if (notes) {
+        promptLines.push('', 'Agent notes:', notes);
+    }
+    promptLines.push('', 'Please review the current changes and confirm:', '- The solution is minimal and avoids unnecessary abstraction/scope');
+    if (options.reviewSurface === 'audit') {
+        promptLines.push('- README/SOP docs match the implemented behavior', '- Commands/scripts are non-interactive (no TTY prompts)', '- Evidence + checklist mirroring requirements are satisfied', '- Start with the manifest or runner log before consulting memory, skills, or review docs', '', 'Call out any remaining documentation/code mismatches or guardrail violations.');
+    }
+    else if (options.reviewSurface === 'architecture') {
+        promptLines.push('- Architecture, layering, and boundaries remain coherent for the requested change', '- Use the canonical architecture inputs above as the primary review context before widening further', '- Call out architectural drift, abstraction mismatch, or missing design rationale that is directly relevant to this task', '- Stay on the requested architecture/context surfaces and directly related implementation paths; do not switch into manifest/runner-log evidence audit unless it is explicitly required', '', 'Keep this pass architecture-focused. Do not treat it as a generic evidence or closeout audit.');
+    }
+    else {
+        const startupFocusLine = options.scopeMode === 'uncommitted'
+            ? '- Start with touched paths, scoped diff commands, or nearby changed code before consulting memory, skills, review docs, manifests, or review artifacts'
+            : '- Start with touched paths or nearby changed code before consulting memory, skills, review docs, manifests, or review artifacts';
+        promptLines.push('- Behavior remains correct for changed files and nearby dependencies', '- Call out concrete regressions, risky edge cases, or missing tests in the changed area', startupFocusLine, '- Concrete same-diff progress can be shown by citing touched paths with explicit locations such as `path:line`, `path:line:col`, `path#Lline`, or `path#LlineCcol`.', '- If you already have that diff-local citation evidence, do not search the wider repo for other examples of the rendering.', '', 'Keep this pass diff-focused. Do not audit checklist/docs/evidence surfaces unless they are directly required to assess code correctness.');
+    }
+    if (options.includeBoundedReviewConstraints) {
+        const boundedFocusLine = options.reviewSurface === 'audit'
+            ? '- Keep this review focused on the requested audit surfaces, supporting evidence, and directly related code/docs paths.'
+            : options.reviewSurface === 'architecture'
+                ? '- Keep this review focused on the requested architecture surfaces, canonical task docs, and directly relevant implementation paths.'
+                : '- Keep this review focused on changed files and nearby dependencies.';
+        promptLines.push('', 'Execution constraints (bounded review mode):', boundedFocusLine, '- Avoid full validation suites (for example `npm run test`, `npm run lint`, `npm run build`, `npm run docs:check`, `npm run docs:freshness`) during this pass.', '- Do not launch direct validation runners (for example `npx vitest`, `npm exec jest`) or nested review/pipeline/delegation flows during this pass.', '- If changed docs, task packets, or checklists mention validation commands, treat them as evidence or follow-up suggestions only; do not execute those commands during bounded review.', '- If broader validation would improve confidence, list follow-up commands instead of executing them.');
+    }
+    return {
+        promptLines,
+        reviewTaskContext,
+        activeCloseoutBundleRoots,
+        resolvedNotes: notes,
+        scopedReviewerVisibleTitle
+    };
+}