@kbediako/codex-orchestrator 0.1.31 → 0.1.32

package/README.md

@@ -176,6 +176,7 @@ codex-orchestrator doctor --usage
 ## Downstream usage cheatsheet (agent-first)
 
 - Bootstrap + wire everything: `codex-orchestrator setup --yes`
+- Low-friction docs->implementation guardrails: `codex-orchestrator flow --task <task-id>`
 - Validate + measure adoption locally: `codex-orchestrator doctor --usage --format json`
 - Delegation: `codex-orchestrator doctor --apply --yes`, then enable for a Codex run with: `codex -c 'mcp_servers.delegation.enabled=true' ...`
 - Collab (symbolic RLM subagents): `codex-orchestrator rlm --collab auto "<goal>"` (requires collab feature enabled in Codex)
@@ -189,6 +190,7 @@ codex-orchestrator devtools setup
 ## Common commands
 
 - `codex-orchestrator start <pipeline>` — run a pipeline.
+- `codex-orchestrator flow --task <task-id>` — run `docs-review` then `implementation-gate` in sequence.
 - `codex-orchestrator plan <pipeline>` — preview pipeline stages.
 - `codex-orchestrator exec <cmd>` — run a one-off command with the exec runtime.
 - `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`) into a repo.

package/dist/bin/codex-orchestrator.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { opendir, readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import process from 'node:process';
 import { CodexOrchestrator } from '../orchestrator/src/cli/orchestrator.js';
@@ -44,6 +44,9 @@ async function main() {
             case 'frontend-test':
                 await handleFrontendTest(orchestrator, args);
                 break;
+            case 'flow':
+                await handleFlow(orchestrator, args);
+                break;
             case 'plan':
                 await handlePlan(orchestrator, args);
                 break;
@@ -145,6 +148,132 @@ function resolveTargetStageId(flags) {
     }
     return undefined;
 }
+const FLOW_TARGET_PIPELINE_SCOPES = new Set(['docs-review', 'implementation-gate']);
+function isFlowTargetPipelineScope(scope) {
+    return FLOW_TARGET_PIPELINE_SCOPES.has(scope);
+}
+function normalizeFlowTargetToken(candidate) {
+    const trimmed = candidate.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const tokens = trimmed.split(':');
+    if (tokens.length > 1 && !(tokens[0] ?? '').trim()) {
+        return null;
+    }
+    let scoped = false;
+    let scopeToken = null;
+    let suffixToken = trimmed;
+    if (tokens.length > 1) {
+        const candidateScope = (tokens[0] ?? '').trim().toLowerCase();
+        if (isFlowTargetPipelineScope(candidateScope)) {
+            scoped = true;
+            scopeToken = candidateScope;
+            suffixToken = (tokens[tokens.length - 1] ?? '').trim();
+        }
+    }
+    if (!suffixToken) {
+        return null;
+    }
+    return {
+        literal: trimmed,
+        literalLower: trimmed.toLowerCase(),
+        stageTokenLower: suffixToken.toLowerCase(),
+        scopeLower: scopeToken,
+        scoped
+    };
+}
+function flowPlanItemPipelineId(item) {
+    const metadataPipelineId = item.metadata && typeof item.metadata['pipelineId'] === 'string'
+        ? item.metadata['pipelineId'].trim().toLowerCase()
+        : '';
+    if (metadataPipelineId) {
+        return metadataPipelineId;
+    }
+    const delimiterIndex = item.id.indexOf(':');
+    if (delimiterIndex <= 0) {
+        return null;
+    }
+    return item.id.slice(0, delimiterIndex).trim().toLowerCase() || null;
+}
+function flowPlanItemMatchesTarget(item, candidate) {
+    const normalized = normalizeFlowTargetToken(candidate);
+    if (!normalized) {
+        return false;
+    }
+    if (item.id.toLowerCase() === normalized.literalLower) {
+        return true;
+    }
+    if (normalized.scoped && normalized.scopeLower) {
+        const itemPipelineId = flowPlanItemPipelineId(item);
+        if (itemPipelineId && itemPipelineId !== normalized.scopeLower) {
+            return false;
+        }
+    }
+    const metadataStageId = item.metadata && typeof item.metadata['stageId'] === 'string'
+        ? item.metadata['stageId'].toLowerCase()
+        : null;
+    const aliases = Array.isArray(item.metadata?.['aliases'])
+        ? item.metadata?.['aliases']
+        : [];
+    const aliasTokens = aliases.filter((alias) => typeof alias === 'string')
+        .map((alias) => alias.toLowerCase());
+    if (normalized.scoped) {
+        if (metadataStageId
+            && (metadataStageId === normalized.literalLower || metadataStageId === normalized.stageTokenLower)) {
+            return true;
+        }
+        return aliasTokens.some((alias) => alias === normalized.literalLower || alias === normalized.stageTokenLower);
+    }
+    if (item.id.toLowerCase().endsWith(`:${normalized.stageTokenLower}`)) {
+        return true;
+    }
+    if (metadataStageId
+        && (metadataStageId === normalized.stageTokenLower
+            || metadataStageId.endsWith(`:${normalized.stageTokenLower}`))) {
+        return true;
+    }
+    return aliasTokens.some((alias) => alias === normalized.stageTokenLower || alias.endsWith(`:${normalized.stageTokenLower}`));
+}
+function planIncludesStageId(plan, stageId) {
+    if (!stageId.trim()) {
+        return false;
+    }
+    return plan.plan.items.some((item) => flowPlanItemMatchesTarget(item, stageId));
+}
+function resolveFlowTargetScope(stageId) {
+    const delimiterIndex = stageId.indexOf(':');
+    if (delimiterIndex <= 0) {
+        return null;
+    }
+    const scope = stageId.slice(0, delimiterIndex).trim().toLowerCase();
+    if (!isFlowTargetPipelineScope(scope)) {
+        return null;
+    }
+    return scope;
+}
+async function resolveFlowTargetStageSelection(orchestrator, taskId, requestedTargetStageId) {
+    if (!requestedTargetStageId) {
+        return {};
+    }
+    const [docsPlan, implementationPlan] = (await Promise.all([
+        orchestrator.plan({ pipelineId: 'docs-review', taskId }),
+        orchestrator.plan({ pipelineId: 'implementation-gate', taskId })
+    ]));
+    const requestedScope = resolveFlowTargetScope(requestedTargetStageId);
+    const docsScopeMatch = !requestedScope || requestedScope === 'docs-review';
+    const implementationScopeMatch = !requestedScope || requestedScope === 'implementation-gate';
+    const docsReviewTargetStageId = docsScopeMatch && planIncludesStageId(docsPlan, requestedTargetStageId)
+        ? requestedTargetStageId
+        : undefined;
+    const implementationGateTargetStageId = implementationScopeMatch && planIncludesStageId(implementationPlan, requestedTargetStageId)
+        ? requestedTargetStageId
+        : undefined;
+    if (!docsReviewTargetStageId && !implementationGateTargetStageId) {
+        throw new Error(`Target stage "${requestedTargetStageId}" is not defined in docs-review or implementation-gate.`);
+    }
+    return { docsReviewTargetStageId, implementationGateTargetStageId };
+}
 function readStringFlag(flags, key) {
     const value = flags[key];
     if (typeof value !== 'string') {
@@ -313,6 +442,84 @@ async function handleFrontendTest(orchestrator, rawArgs) {
         }
     }
 }
+async function handleFlow(orchestrator, rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printFlowHelp();
+        return;
+    }
+    if (positionals.length > 0) {
+        throw new Error(`flow does not accept positional arguments: ${positionals.join(' ')}`);
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const executionMode = resolveExecutionModeFlag(flags);
+    const taskId = typeof flags['task'] === 'string' ? flags['task'] : undefined;
+    const parentRunId = typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined;
+    const approvalPolicy = typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined;
+    const targetStageId = resolveTargetStageId(flags);
+    const { docsReviewTargetStageId, implementationGateTargetStageId } = await resolveFlowTargetStageSelection(orchestrator, taskId, targetStageId);
+    await withRunUi(flags, format, async (runEvents) => {
+        const docsReviewResult = await orchestrator.start({
+            pipelineId: 'docs-review',
+            taskId,
+            parentRunId,
+            approvalPolicy,
+            targetStageId: docsReviewTargetStageId,
+            executionMode,
+            runEvents
+        });
+        const docsPayload = toRunOutputPayload(docsReviewResult);
+        if (format === 'text') {
+            emitRunOutput(docsReviewResult, format, 'Docs-review run');
+        }
+        if (docsReviewResult.manifest.status !== 'succeeded') {
+            process.exitCode = 1;
+            if (format === 'json') {
+                const payload = {
+                    status: docsReviewResult.manifest.status,
+                    failed_stage: 'docs-review',
+                    docs_review: docsPayload,
+                    implementation_gate: null
+                };
+                console.log(JSON.stringify(payload, null, 2));
+            }
+            else {
+                console.log('Flow halted: docs-review failed.');
+            }
+            return;
+        }
+        const implementationGateResult = await orchestrator.start({
+            pipelineId: 'implementation-gate',
+            taskId,
+            parentRunId: docsReviewResult.manifest.run_id,
+            approvalPolicy,
+            targetStageId: implementationGateTargetStageId,
+            executionMode,
+            runEvents
+        });
+        const implementationPayload = toRunOutputPayload(implementationGateResult);
+        if (format === 'json') {
+            const payload = {
+                status: implementationGateResult.manifest.status,
+                failed_stage: implementationGateResult.manifest.status === 'succeeded' ? null : 'implementation-gate',
+                docs_review: docsPayload,
+                implementation_gate: implementationPayload
+            };
+            console.log(JSON.stringify(payload, null, 2));
+            if (implementationGateResult.manifest.status !== 'succeeded') {
+                process.exitCode = 1;
+            }
+            return;
+        }
+        emitRunOutput(implementationGateResult, format, 'Implementation-gate run');
+        if (implementationGateResult.manifest.status !== 'succeeded') {
+            process.exitCode = 1;
+            console.log('Flow halted: implementation-gate failed.');
+            return;
+        }
+        console.log('Flow complete: docs-review -> implementation-gate.');
+    });
+}
 async function handlePlan(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const pipelineId = positionals[0];
@@ -464,14 +671,7 @@ async function withRunUi(flags, format, action) {
     }
 }
 function emitRunOutput(result, format, label) {
-    const payload = {
-        run_id: result.manifest.run_id,
-        status: result.manifest.status,
-        artifact_root: result.manifest.artifact_root,
-        manifest: `${result.manifest.artifact_root}/manifest.json`,
-        log_path: result.manifest.log_path,
-        summary: result.manifest.summary ?? null
-    };
+    const payload = toRunOutputPayload(result);
     if (format === 'json') {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -487,6 +687,16 @@ function emitRunOutput(result, format, label) {
         }
     }
 }
+function toRunOutputPayload(result) {
+    return {
+        run_id: result.manifest.run_id,
+        status: result.manifest.status,
+        artifact_root: result.manifest.artifact_root,
+        manifest: `${result.manifest.artifact_root}/manifest.json`,
+        log_path: result.manifest.log_path,
+        summary: result.manifest.summary ?? null
+    };
+}
 async function handleExec(rawArgs) {
     const parsed = parseExecArgs(rawArgs);
     if (parsed.commandTokens.length === 0) {
@@ -519,6 +729,55 @@ async function handleExec(rawArgs) {
     else if (result.status !== 'succeeded') {
         process.exitCode = 1;
     }
+    if (outputMode === 'interactive') {
+        await maybeEmitExecAdoptionHint(env.taskId);
+    }
+}
+async function shouldScanExecAdoptionHint(taskFilter) {
+    if (!taskFilter) {
+        return false;
+    }
+    const env = resolveEnvironmentPaths();
+    const taskCliRunsRoot = join(env.runsRoot, taskFilter, 'cli');
+    let handle = null;
+    try {
+        handle = await opendir(taskCliRunsRoot);
+        let runCount = 0;
+        for await (const entry of handle) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            runCount += 1;
+            if (runCount > 150) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (handle) {
+            await handle.close().catch(() => undefined);
+        }
+    }
+}
+async function maybeEmitExecAdoptionHint(taskFilter) {
+    try {
+        if (!(await shouldScanExecAdoptionHint(taskFilter))) {
+            return;
+        }
+        const usage = await runDoctorUsage({ windowDays: 7, taskFilter });
+        const recommendation = usage.adoption.recommendations[0];
+        if (!recommendation) {
+            return;
+        }
+        console.log(`Adoption hint: ${recommendation}`);
+    }
+    catch {
+        // Exec command behavior should not fail when usage telemetry cannot be read.
+    }
 }
 async function handleSelfCheck(rawArgs) {
     const { flags } = parseArgs(rawArgs);
@@ -599,6 +858,7 @@ Options:
         throw new Error('No bundled skills detected; cannot run setup.');
     }
     const forceSkills = bundledSkills.filter((skill) => skill !== 'chrome-devtools');
+    const guidance = buildSetupGuidance();
     if (!apply) {
         const forceOnly = forceSkills.join(',');
         const forceCommand = forceOnly ? `codex-orchestrator skills install --force --only ${forceOnly}` : null;
@@ -615,7 +875,8 @@ Options:
                     note: 'Installs bundled skills into $CODEX_HOME/skills (setup avoids overwriting chrome-devtools when already present).'
                 },
                 delegation,
-                devtools
+                devtools,
+                guidance
             }
         };
         if (format === 'json') {
@@ -629,6 +890,9 @@ Options:
         }
         console.log(`- Delegation: codex-orchestrator delegation setup --yes${delegationRepoArg}`);
         console.log('- DevTools: codex-orchestrator devtools setup --yes');
+        for (const line of formatSetupGuidanceSummary(guidance)) {
+            console.log(line);
+        }
         console.log('Run with --yes to apply this setup.');
         return;
     }
@@ -659,8 +923,41 @@ Options:
     for (const line of formatDevtoolsSetupSummary(devtools)) {
         console.log(line);
     }
+    for (const line of formatSetupGuidanceSummary(guidance)) {
+        console.log(line);
+    }
     console.log('Next: codex-orchestrator doctor --usage');
 }
+function buildSetupGuidance() {
+    return {
+        note: 'Agent-first default: run docs-review before implementation and implementation-gate before handoff.',
+        references: [
+            'https://github.com/Kbediako/CO#downstream-usage-cheatsheet-agent-first',
+            'https://github.com/Kbediako/CO/blob/main/docs/AGENTS.md',
+            'https://github.com/Kbediako/CO/blob/main/docs/guides/collab-vs-mcp.md'
+        ],
+        recommended_commands: [
+            'codex-orchestrator flow --task <task-id>',
+            'codex-orchestrator doctor --usage'
+        ]
+    };
+}
+function formatSetupGuidanceSummary(guidance) {
+    const lines = ['Setup guidance:', `- ${guidance.note}`];
+    if (guidance.recommended_commands.length > 0) {
+        lines.push('- Recommended commands:');
+        for (const command of guidance.recommended_commands) {
+            lines.push(`  - ${command}`);
+        }
+    }
+    if (guidance.references.length > 0) {
+        lines.push('- References:');
+        for (const reference of guidance.references) {
+            lines.push(`  - ${reference}`);
+        }
+    }
+    return lines;
+}
 async function handleDoctor(rawArgs) {
     const { flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
@@ -1159,6 +1456,17 @@ Commands:
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
 
+  flow                      Run docs-review then implementation-gate sequentially.
+    --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+    --parent-run <id>       Link docs-review run to parent run id.
+    --approval-policy <p>   Record approval policy metadata.
+    --format json           Emit machine-readable output summary for both runs.
+    --execution-mode <mcp|cloud>  Force execution mode for both runs.
+    --cloud                 Shortcut for --execution-mode cloud.
+    --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
+    --interactive | --ui    Enable read-only HUD when running in a TTY.
+    --no-interactive        Force disable HUD (default is off unless requested).
+
   plan [pipeline]           Preview pipeline stages without executing.
     --task <id>             Override task identifier.
     --format json           Emit machine-readable output.
@@ -1324,3 +1632,20 @@ Options:
   --help                  Show this message.
 `);
 }
+function printFlowHelp() {
+    console.log(`Usage: codex-orchestrator flow [options]
+
+Runs docs-review first, then implementation-gate. Stops on the first failure.
+
+Options:
+  --task <id>               Override task identifier.
+  --parent-run <id>         Link docs-review run to parent run id.
+  --approval-policy <p>     Record approval policy metadata.
+  --format json             Emit machine-readable output for both runs.
+  --execution-mode <mcp|cloud>  Force execution mode for both runs.
+  --cloud                   Shortcut for --execution-mode cloud.
+  --target <stage-id>       Focus plan/build metadata (applies where the stage exists).
+  --interactive | --ui      Enable read-only HUD when running in a TTY.
+  --no-interactive          Force disable HUD.
+`);
+}

package/dist/scripts/lib/pr-watch-merge.js

@@ -15,6 +15,12 @@ const REQUIRED_BUCKET_FAILED = new Set(['fail', 'cancel', 'skipping']);
 const MERGEABLE_STATES = new Set(['CLEAN', 'HAS_HOOKS', 'UNSTABLE']);
 const BLOCKED_REVIEW_DECISIONS = new Set(['CHANGES_REQUESTED', 'REVIEW_REQUIRED']);
 const DO_NOT_MERGE_LABEL = /do[\s_-]*not[\s_-]*merge/i;
+const ACTIONABLE_BOT_LOGINS = new Set([
+    'chatgpt-codex-connector',
+    'chatgpt-codex-connector[bot]',
+    'coderabbitai',
+    'coderabbitai[bot]'
+]);
 const PR_QUERY = `
 query($owner:String!, $repo:String!, $number:Int!) {
   repository(owner:$owner, name:$repo) {
@@ -73,6 +79,29 @@ function normalizeEnum(value) {
 function normalizeBucket(value) {
     return typeof value === 'string' ? value.trim().toLowerCase() : '';
 }
+function normalizeLogin(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+function isActionableBot(login) {
+    return ACTIONABLE_BOT_LOGINS.has(normalizeLogin(login));
+}
+export function isHumanReviewActor(user) {
+    if (!user || typeof user !== 'object') {
+        return false;
+    }
+    const login = normalizeLogin(user.login);
+    if (!login) {
+        return false;
+    }
+    if (isActionableBot(login)) {
+        return false;
+    }
+    const accountType = typeof user.type === 'string' ? user.type.trim().toUpperCase() : '';
+    if (accountType) {
+        return accountType === 'USER';
+    }
+    return !login.endsWith('[bot]');
+}
 function formatDuration(ms) {
     if (ms <= 0) {
         return '0s';
@@ -218,6 +247,15 @@ async function runGhJson(args) {
         throw new Error(`Failed to parse JSON from gh ${args.join(' ')}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+async function runGhJsonSlurped(args) {
+    const result = await runGh([...args, '--paginate', '--slurp']);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse paginated JSON from gh ${args.join(' ')}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 async function ensureGhAuth() {
     const result = await runGh(['auth', 'status', '-h', 'github.com'], { allowFailure: true });
     if (result.exitCode !== 0) {
@@ -378,7 +416,7 @@ export function resolveCachedRequiredChecksSummary(previousCache, currentHeadOid
     }
     return hasRequiredChecksSummary(previousCache.summary) ? previousCache.summary : null;
 }
-export function buildStatusSnapshot(response, requiredChecks = null) {
+export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFeedback = null) {
     const pr = response?.data?.repository?.pullRequest;
     if (!pr) {
         throw new Error('GraphQL response missing pullRequest payload.');
@@ -391,10 +429,15 @@ export function buildStatusSnapshot(response, requiredChecks = null) {
     const hasDoNotMergeLabel = labels.some((label) => DO_NOT_MERGE_LABEL.test(label));
     const threads = Array.isArray(pr.reviewThreads?.nodes) ? pr.reviewThreads.nodes : [];
     const unresolvedThreadCount = threads.filter((thread) => thread && !thread.isResolved && !thread.isOutdated).length;
+    const hasUnresolvedThread = unresolvedThreadCount > 0;
     const contexts = pr.commits?.nodes?.[0]?.commit?.statusCheckRollup?.contexts?.nodes;
     const checkNodes = Array.isArray(contexts) ? contexts : [];
     const checks = summarizeChecks(checkNodes);
     const requiredCheckSummary = requiredChecks && typeof requiredChecks === 'object' && requiredChecks.total > 0 ? requiredChecks : null;
+    const unacknowledgedBotFeedbackCount = inlineBotFeedback && typeof inlineBotFeedback.unacknowledgedCount === 'number'
+        ? inlineBotFeedback.unacknowledgedCount
+        : 0;
+    const botFeedbackFetchError = inlineBotFeedback?.fetchError === true;
     const gateChecks = requiredCheckSummary ?? checks;
     const gateChecksSource = requiredCheckSummary ? 'required' : 'rollup';
     const reviewDecision = normalizeEnum(pr.reviewDecision);
@@ -422,9 +465,15 @@ export function buildStatusSnapshot(response, requiredChecks = null) {
     if (BLOCKED_REVIEW_DECISIONS.has(reviewDecision)) {
         gateReasons.push(`review=${reviewDecision}`);
     }
-    if (unresolvedThreadCount > 0) {
+    if (hasUnresolvedThread) {
         gateReasons.push(`unresolved_threads=${unresolvedThreadCount}`);
     }
+    if (botFeedbackFetchError) {
+        gateReasons.push('bot_feedback=unknown');
+    }
+    else if (unacknowledgedBotFeedbackCount > 0) {
+        gateReasons.push(`unacknowledged_bot_feedback=${unacknowledgedBotFeedbackCount}`);
+    }
     return {
         number: Number(pr.number),
         url: typeof pr.url === 'string' ? pr.url : null,
@@ -437,6 +486,8 @@ export function buildStatusSnapshot(response, requiredChecks = null) {
         labels,
         hasDoNotMergeLabel,
         unresolvedThreadCount,
+        unacknowledgedBotFeedbackCount,
+        botFeedbackFetchError,
         checks,
         requiredChecks: requiredCheckSummary,
         gateChecksSource,
@@ -467,6 +518,8 @@ function formatStatusLine(snapshot, quietRemainingMs) {
         `required_checks_pending=${requiredChecks ? requiredChecks.pending.length : 'n/a'}`,
         `required_checks_failed=${requiredChecks ? requiredChecks.failed.length : 'n/a'}`,
         `unresolved_threads=${snapshot.unresolvedThreadCount}`,
+        `unack_bot_feedback=${snapshot.unacknowledgedBotFeedbackCount}`,
+        `bot_feedback_fetch_error=${snapshot.botFeedbackFetchError ? 'yes' : 'no'}`,
         `quiet_remaining=${formatDuration(quietRemainingMs)}`,
         `blocked_by=${reasons}`,
         `pending=[${pendingNames}]`,
@@ -501,6 +554,77 @@ async function fetchRequiredChecks(owner, repo, prNumber) {
         };
     }
 }
+function flattenReviewCommentPages(pagesPayload) {
+    if (!Array.isArray(pagesPayload)) {
+        return [];
+    }
+    const comments = [];
+    for (const page of pagesPayload) {
+        if (Array.isArray(page)) {
+            comments.push(...page);
+            continue;
+        }
+        if (page && typeof page === 'object') {
+            comments.push(page);
+        }
+    }
+    return comments;
+}
+async function fetchInlineBotFeedback(owner, repo, prNumber, headOid) {
+    if (!headOid) {
+        return { fetchError: false, unacknowledgedCount: 0 };
+    }
+    try {
+        const pagedPayload = await runGhJsonSlurped([
+            'api',
+            `repos/${owner}/${repo}/pulls/${prNumber}/comments`
+        ]);
+        const comments = flattenReviewCommentPages(pagedPayload);
+        const repliesByParentId = new Map();
+        for (const comment of comments) {
+            if (!comment || typeof comment !== 'object') {
+                continue;
+            }
+            const parentId = Number(comment.in_reply_to_id);
+            if (!Number.isInteger(parentId) || parentId <= 0) {
+                continue;
+            }
+            const bucket = repliesByParentId.get(parentId) ?? [];
+            bucket.push(comment);
+            repliesByParentId.set(parentId, bucket);
+        }
+        let unacknowledgedCount = 0;
+        for (const comment of comments) {
+            if (!comment || typeof comment !== 'object') {
+                continue;
+            }
+            const commentId = Number(comment.id);
+            if (!Number.isInteger(commentId) || commentId <= 0) {
+                continue;
+            }
+            if (comment.in_reply_to_id !== null && comment.in_reply_to_id !== undefined) {
+                continue;
+            }
+            if (!isActionableBot(comment.user?.login)) {
+                continue;
+            }
+            const commitId = typeof comment.commit_id === 'string' ? comment.commit_id : null;
+            const originalCommitId = typeof comment.original_commit_id === 'string' ? comment.original_commit_id : null;
+            if (commitId !== headOid && originalCommitId !== headOid) {
+                continue;
+            }
+            const replies = repliesByParentId.get(commentId) ?? [];
+            const hasHumanReply = replies.some((reply) => isHumanReviewActor(reply?.user));
+            if (!hasHumanReply) {
+                unacknowledgedCount += 1;
+            }
+        }
+        return { fetchError: false, unacknowledgedCount };
+    }
+    catch {
+        return { fetchError: true, unacknowledgedCount: 0 };
+    }
+}
 async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache = null) {
     const response = await runGhJson([
         'api',
@@ -518,8 +642,9 @@ async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache
     const previousRequiredChecks = resolveCachedRequiredChecksSummary(previousRequiredChecksCache, currentHeadOid);
     const requiredChecksResult = await fetchRequiredChecks(owner, repo, prNumber);
     const requiredChecks = resolveRequiredChecksSummary(requiredChecksResult.summary, previousRequiredChecks, requiredChecksResult.fetchError);
+    const inlineBotFeedback = await fetchInlineBotFeedback(owner, repo, prNumber, currentHeadOid);
     return {
-        snapshot: buildStatusSnapshot(response, requiredChecks),
+        snapshot: buildStatusSnapshot(response, requiredChecks, inlineBotFeedback),
         requiredChecksForNextPoll: requiredChecks
             ? {
                 headOid: currentHeadOid,

package/docs/README.md

@@ -101,7 +101,8 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 ## Companion Package Commands
 - `codex-orchestrator mcp serve [--repo <path>] [--dry-run] [-- <extra args>]`: launch the MCP stdio server (delegates to `codex mcp-server`; stdout guard keeps protocol-only output, logs to stderr).
 - `codex-orchestrator init codex [--cwd <path>] [--force]`: copy starter templates into a repo (includes `mcp-client.json` and `AGENTS.md`; no overwrite unless `--force`).
-- `codex-orchestrator setup [--yes]`: one-shot bootstrap for downstream users (installs bundled skills and configures delegation + DevTools wiring).
+- `codex-orchestrator setup [--yes]`: one-shot bootstrap for downstream users (installs bundled skills, configures delegation + DevTools wiring, and prints policy/usage guidance).
+- `codex-orchestrator flow [--task <task-id>]`: runs `docs-review` then `implementation-gate` in sequence; stops on the first failure.
 - `codex-orchestrator doctor [--format json] [--usage] [--apply]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands. `--usage` appends a local usage snapshot (scans `.runs/`). `--apply` plans/applies quick fixes (use with `--yes`).
 - `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
 - `codex-orchestrator delegation setup [--yes]`: configure delegation MCP wiring (`--yes` applies `codex mcp add ...`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "license": "MIT",
   "repository": {
     "type": "git",