@open-agent-toolkit/cli 0.2.47 → 0.2.49

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.47"
+  "oatVersion": "0.2.49"
 }

package/assets/docs/cli-utilities/workflow-gates.md

@@ -51,6 +51,17 @@ Fields:
 - `description` - optional context for the agent running the gate.
 - `maxAttempts` - retry bound for `block`; defaults to `2`.
 
+When `oat gate set` recognizes a direct lifecycle `oat gate review` command,
+it requires the canonical global option placement `oat --json gate review`.
+Missing, late, repeated, or subcommand-scoped `--json` is rejected with exit 1
+before the selected shared, local, or user config layer is changed. Arbitrary
+wrappers, unrelated gate commands, and provider exec-target `baseCommand`
+arrays remain outside this validator.
+
+A valid command is stored byte-for-byte. `oat gate resolve` returns that exact
+string, and the lifecycle executes it unchanged; OAT does not inject, reorder,
+or rewrite its shell arguments.
+
 `oat-project-plan`, `oat-project-implement`, `oat-project-quick-start`, and
 `oat-project-import-plan` are currently gate-aware. Gate awareness is declared
 in skill frontmatter with `oat_gateable: true`, and
@@ -284,6 +295,7 @@ and disambiguate re-gate rounds:
 | `ok`                           | 0    | Review completed; gate passed at the threshold.              |
 | `blocked`                      | 1    | Review completed; findings at/above the threshold.           |
 | `review_failed`                | ≠0   | The provider target exited non-zero; no verdict.             |
+| `artifact_missing`             | 1    | The child exited cleanly without producing an artifact.      |
 | `artifact_validation_failed`   | 1    | Artifact format or configured invocation fields are invalid. |
 | `targeting_correlation_failed` | 1    | Identity did not correlate; do not run review-receive.       |
 
@@ -296,6 +308,13 @@ For `artifact_validation_failed`, correct the artifact and rerun the gate; do
 not invoke review-receive until the gate successfully revalidates it as `ok` or
 `blocked`.
 
+`artifact_missing` means the accepted headless child completed without any
+review artifact. It sets `receiveEligible: false`, `remediable: false`, and
+`handoff: null`. Fix the reviewer so review work, artifact creation, and
+bookkeeping finish inline or through a synchronously awaited child, then start
+a new gate run. Do not use review-fix retries or review-receive for the failed
+run.
+
 `ok` and `blocked` also include `receiveEligible: true`, `outcome`,
 `artifactPath`, `counts`, `scope`, `handoff`, `gateInvocation`, and
 `corroboration`. Invoke review-receive only when all three conditions hold:

package/assets/docs/contributing/skills.md

@@ -262,9 +262,11 @@ The Gate Execution step should:
 2. Treat `null` as "no gate configured."
 3. Export the resolved path with `export PROJECT_PATH` before launching the
    command shell.
-4. For `oat gate review`, require the configured command to include
-   `--project "$PROJECT_PATH"`; do not append it at runtime, because the resolved
-   command must execute exactly as configured.
+4. For `oat gate review`, require the configured command to use
+   `oat --json gate review --project "$PROJECT_PATH" ...`, with the global
+   `--json` option before `gate review`. Do not inject, append, or reorder
+   arguments at runtime, because the resolved command must execute exactly as
+   configured.
 5. Run the resolved `command` as the skill's last step and use its exit code as
    the pass/fail signal.
 6. Follow the gate's `onFailure` policy:
@@ -273,7 +275,7 @@ The Gate Execution step should:
    - `warn` - record the failure and continue.
 
 For OAT review gates, prefer putting
-`oat gate review --project "$PROJECT_PATH" "<prompt>"` in the configured gate
+`oat --json gate review --project "$PROJECT_PATH" "<prompt>"` in the configured gate
 command rather than hard-coding a provider CLI directly in the skill. Use
 `oat gate cross-provider-exec "<prompt>"` for generic cross-runtime commands
 that should report only the child process status, not review findings.

package/assets/docs/reference/cli-reference.md

@@ -126,7 +126,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. For `targeting_correlation_failed`, do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
+- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
 - `oat gate route --expect-runtime <runtime> --expect-model <model> --can-await <true|false> --json` - return the headless child route (`inline`, `delegate-sync`, or `refuse`) from provider-marker and model evidence. Ambiguous or contradictory evidence never routes inline.
 - `oat gate exec <prompt...>` / `oat gate cross-provider-exec <prompt...>` - run a generic target prompt. `--timeout-ms` uses the same validated CLI override; untyped runs otherwise retain the legacy default path.
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.47",
-  "docs-config": "0.2.47",
-  "docs-theme": "0.2.47",
-  "docs-transforms": "0.2.47"
+  "cli": "0.2.49",
+  "docs-config": "0.2.49",
+  "docs-theme": "0.2.49",
+  "docs-transforms": "0.2.49"
 }

package/assets/skills/oat-project-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-design
-version: 2.3.1
+version: 2.3.2
 description: Use when discovery is complete and implementation-ready decisions are needed. Runs a collaborative, selective collaborative, or draft-and-review design flow, confirms requirements and produces both `spec.md` and `design.md`, and commits artifacts before the user-review gate.
 disable-model-invocation: true
 user-invocable: true
@@ -658,11 +658,18 @@ gate as the last check before the completion boundary:
    ```
 
    If the resolved command invokes `oat gate review`, the configured review
-   command must already include `--project "$PROJECT_PATH"` and must not include
-   `--target <id>`. A valid reusable shape is
-   `oat gate review --project "$PROJECT_PATH" ...`. If the declaration is
-   missing, stop and migrate the stored gate command; do not inject or append
-   arguments at execution time.
+   command must already include `--project "$PROJECT_PATH"` as part of the
+   structured-output contract. Its canonical form is:
+
+   ```bash
+   oat --json gate review --project "$PROJECT_PATH" ...
+   ```
+
+   This requires global `--json` before `gate review`. Reusable declarations
+   must not include
+   `--target <id>`. Reject `oat gate review ...` without the global `--json`
+   placement. Stop and migrate an invalid stored declaration before execution;
+   never inject or append execution-time argv.
 
 3. Execute the resolved command exactly as configured. Capture stdout, stderr,
    the exit code, and the structured JSON result. A zero exit code means the

package/assets/skills/oat-project-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-discover
-version: 2.2.1
+version: 2.2.2
 description: Use when the user explicitly asks to continue discovery for an active spec-driven OAT project — e.g. "continue discovery", "run discovery", or confirms a previously offered discovery step. Do NOT auto-invoke for new ideas or quick-mode projects. Gathers requirements and context before spec/design.
 disable-model-invocation: false
 user-invocable: true
@@ -445,11 +445,18 @@ gate as the last check before the completion boundary:
    ```
 
    If the resolved command invokes `oat gate review`, the configured review
-   command must already include `--project "$PROJECT_PATH"` and must not include
-   `--target <id>`. A valid reusable shape is
-   `oat gate review --project "$PROJECT_PATH" ...`. If the declaration is
-   missing, stop and migrate the stored gate command; do not inject or append
-   arguments at execution time.
+   command must already include `--project "$PROJECT_PATH"` as part of the
+   structured-output contract. Its canonical form is:
+
+   ```bash
+   oat --json gate review --project "$PROJECT_PATH" ...
+   ```
+
+   This requires global `--json` before `gate review`. Reusable declarations
+   must not include
+   `--target <id>`. Reject `oat gate review ...` without the global `--json`
+   placement. Stop and migrate an invalid stored declaration before execution;
+   never inject or append execution-time argv.
 
 3. Execute the resolved command exactly as configured. Capture stdout, stderr,
    the exit code, and the structured JSON result. A zero exit code means the

package/assets/skills/oat-project-import-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.4.10
+version: 1.4.11
 description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
 argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
 oat_gateable: true
@@ -460,7 +460,13 @@ Before reporting this skill as complete, run the configured gate as the final st
    export PROJECT_PATH
    ```
 
-   If the resolved command invokes `oat gate review`, the configured review command must already include `--project "$PROJECT_PATH"` and must not include `--target <id>`. A valid reusable shape is `oat gate review --project "$PROJECT_PATH" ...`. If the declaration is missing, stop and migrate the stored gate command; do not inject or append arguments at execution time.
+   If the resolved command invokes `oat gate review`, the configured review command must already include `--project "$PROJECT_PATH"` as part of the structured-output contract. Its canonical form is:
+
+   ```bash
+   oat --json gate review --project "$PROJECT_PATH" ...
+   ```
+
+   This requires global `--json` before `gate review`. Reusable declarations must not include `--target <id>`. Reject `oat gate review ...` without the global `--json` placement. Stop and migrate an invalid stored declaration before execution; never inject or append execution-time argv.
 
 3. Resolve the current planning parent's model identity from session context.
    When that identity is non-empty and the resolved configured command invokes

package/assets/skills/oat-project-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.4.5
+version: 1.4.6
 description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
 oat_gateable: true
 disable-model-invocation: true
@@ -544,7 +544,13 @@ the last check before the completion boundary:
    export PROJECT_PATH
    ```
 
-   If the resolved command invokes `oat gate review`, the configured review command must already include `--project "$PROJECT_PATH"` and must not include `--target <id>`. A valid reusable shape is `oat gate review --project "$PROJECT_PATH" ...`. If the declaration is missing, stop and migrate the stored gate command; do not inject or append arguments at execution time.
+   If the resolved command invokes `oat gate review`, the configured review command must already include `--project "$PROJECT_PATH"` as part of the structured-output contract. Its canonical form is:
+
+   ```bash
+   oat --json gate review --project "$PROJECT_PATH" ...
+   ```
+
+   This requires global `--json` before `gate review`. Reusable declarations must not include `--target <id>`. Reject `oat gate review ...` without the global `--json` placement. Stop and migrate an invalid stored declaration before execution; never inject or append execution-time argv.
 
 3. Resolve the current planning parent's model identity from session context.
    When that identity is non-empty and the resolved configured command invokes

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 2.3.6
+version: 2.3.7
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
 oat_gateable: true
@@ -735,7 +735,13 @@ as the last check before plan and project completion:
    export PROJECT_PATH
    ```
 
-   If the resolved command invokes `oat gate review`, the configured review command must already include `--project "$PROJECT_PATH"` and must not include `--target <id>`. A valid reusable shape is `oat gate review --project "$PROJECT_PATH" ...`. If the declaration is missing, stop and migrate the stored gate command; do not inject or append arguments at execution time.
+   If the resolved command invokes `oat gate review`, the configured review command must already include `--project "$PROJECT_PATH"` as part of the structured-output contract. Its canonical form is:
+
+   ```bash
+   oat --json gate review --project "$PROJECT_PATH" ...
+   ```
+
+   This requires global `--json` before `gate review`. Reusable declarations must not include `--target <id>`. Reject `oat gate review ...` without the global `--json` placement. Stop and migrate an invalid stored declaration before execution; never inject or append execution-time argv.
 
 3. Resolve the current planning parent's model identity from session context.
    When that identity is non-empty and the resolved configured command invokes

package/assets/skills/oat-wave-execute/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-wave-execute
-version: 1.8.2
+version: 1.9.0
 description: Use when executing a wave of external implementation plans as a wrapper OAT project — scaffolding, drift refresh, parallel worktree groups, briefs, gates, merge choreography, and closeout.
 argument-hint: '<wave-id> [plan-names...] (e.g. wave-2 http-listener-before-indexing ...)'
 disable-model-invocation: false
@@ -459,7 +459,8 @@ The mechanical caller constructs an `explainer-kit.run-request/v1` document whos
 required keys are exactly:
 `schemaVersion, recipe, slug, outputRoot, factBase, mode`. Set `recipe` to
 `{ "id": "program-recap", "version": "1" }`; this is an object with exactly
-`id` and `version`. Set `outputRoot` to `.oat/repo/explainers/<slug>/`. Bind the
+`id` and `version`. Set `outputRoot` to
+`.oat/repo/reference/explainers/<slug>/`. Bind the
 synthesized fact-base file through `factBase` with the required keys
 `mode, freshnessPolicy`, set `mode` to `"supplied"`, set `freshnessPolicy` to
 `"live-wins"`, and set `path` to that file.

package/assets/skills/oat-wave-program/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-wave-program
-version: 1.4.0
+version: 1.5.0
 description: Use when decomposing a corpus of external implementation plans into an ordered wave program — coverage inventory, dependency mapping, wave composition, and the durable execution-program artifact that oat-wave-execute consumes and updates.
 argument-hint: '[new|refresh|wave-close <wave-id>] (default: refresh against the current artifact)'
 disable-model-invocation: false
@@ -152,7 +152,8 @@ The mechanical caller constructs an `explainer-kit.run-request/v1` document whos
 required keys are exactly:
 `schemaVersion, recipe, slug, outputRoot, factBase, mode`. Set `recipe` to
 `{ "id": "program-recap", "version": "1" }`; this is an object with exactly
-`id` and `version`. Set `outputRoot` to `.oat/repo/explainers/<slug>/`. Bind the
+`id` and `version`. Set `outputRoot` to
+`.oat/repo/reference/explainers/<slug>/`. Bind the
 synthesized fact-base file through `factBase` with the required keys
 `mode, freshnessPolicy`, set `mode` to `"supplied"`, set `freshnessPolicy` to
 `"live-wins"`, and set `path` to that file.

package/dist/commands/gate/__fixtures__/fake-runtime.mjs

@@ -8,6 +8,16 @@ const delayMs = Number(process.env.FAKE_GATE_DELAY_MS ?? '0');
 const exitCode = Number(process.env.FAKE_GATE_EXIT_CODE ?? '0');
 const artifactMode = process.env.FAKE_GATE_ARTIFACT ?? 'none';
 const transcriptIntervalMs = Number(process.env.FAKE_GATE_TRANSCRIPT_INTERVAL_MS ?? '0');
+if (process.env.FAKE_GATE_INVOCATION_LOG) {
+    await appendFile(process.env.FAKE_GATE_INVOCATION_LOG, `${JSON.stringify({
+        pid: process.pid,
+        headless: process.env.OAT_GATE_HEADLESS ?? null,
+        nonInteractive: process.env.OAT_NON_INTERACTIVE ?? null,
+        runId: process.env.OAT_GATE_RUN_ID ?? null,
+        cliPath: process.env.OAT_GATE_CLI_PATH ?? null,
+        routeReceiptPath: process.env.OAT_GATE_ROUTE_RECEIPT_PATH ?? null,
+    })}\n`);
+}
 function promptValue(key) {
     return prompt.match(new RegExp(`^${key}: (.+)$`, 'm'))?.[1] ?? 'unknown';
 }

package/dist/commands/gate/configured-command.d.ts

@@ -0,0 +1,12 @@
+export type GateCommandContractResult = {
+    kind: 'not-applicable';
+} | {
+    kind: 'valid';
+    command: 'gate-review';
+} | {
+    kind: 'invalid';
+    command: 'gate-review';
+    message: string;
+};
+export declare function validateConfiguredGateCommand(command: string): GateCommandContractResult;
+//# sourceMappingURL=configured-command.d.ts.map

package/dist/commands/gate/configured-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configured-command.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/configured-command.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAmIjE,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,GACd,yBAAyB,CAoB3B"}

package/dist/commands/gate/configured-command.js

@@ -0,0 +1,120 @@
+const INVALID_GATE_REVIEW_COMMAND_MESSAGE = 'Configured oat gate review commands must use the structured-output contract `oat --json gate review ...`.';
+function tokenizeCommand(command) {
+    const tokens = [];
+    let token = '';
+    let tokenStarted = false;
+    let quote = null;
+    let escaped = false;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (quote === "'") {
+            if (character === "'") {
+                quote = null;
+            }
+            else {
+                token += character;
+            }
+            continue;
+        }
+        if (escaped) {
+            if (character === '\n') {
+                return null;
+            }
+            token += character;
+            tokenStarted = true;
+            escaped = false;
+            continue;
+        }
+        if (character === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (character === quote) {
+                quote = null;
+            }
+            else {
+                if (character === '`' ||
+                    (character === '$' && command[index + 1] === '(')) {
+                    return null;
+                }
+                token += character;
+            }
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            tokenStarted = true;
+            continue;
+        }
+        if (character === '\n' || character === '`') {
+            return null;
+        }
+        if (/\s/.test(character)) {
+            if (tokenStarted) {
+                tokens.push(token);
+                token = '';
+                tokenStarted = false;
+            }
+            continue;
+        }
+        if ('|;&<>'.includes(character) ||
+            (character === '$' && command[index + 1] === '(')) {
+            return null;
+        }
+        token += character;
+        tokenStarted = true;
+    }
+    if (escaped || quote) {
+        return null;
+    }
+    if (tokenStarted) {
+        tokens.push(token);
+    }
+    return tokens;
+}
+function isDirectGateReview(tokens) {
+    if (tokens[0] !== 'oat') {
+        return false;
+    }
+    let index = 1;
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (token === 'gate') {
+            return (tokens[index + 1] === 'review' ||
+                (tokens[index + 1] === '--json' && tokens[index + 2] === 'review'));
+        }
+        if (token === '--json' ||
+            token === '--verbose' ||
+            token.startsWith('--cwd=')) {
+            index += 1;
+            continue;
+        }
+        if (token === '--cwd') {
+            if (tokens[index + 1] === undefined) {
+                return false;
+            }
+            index += 2;
+            continue;
+        }
+        return false;
+    }
+    return false;
+}
+export function validateConfiguredGateCommand(command) {
+    const tokens = tokenizeCommand(command);
+    if (!tokens || !isDirectGateReview(tokens)) {
+        return { kind: 'not-applicable' };
+    }
+    if (tokens[1] === '--json' &&
+        tokens[2] === 'gate' &&
+        tokens[3] === 'review' &&
+        tokens.filter((token) => token === '--json').length === 1) {
+        return { kind: 'valid', command: 'gate-review' };
+    }
+    return {
+        kind: 'invalid',
+        command: 'gate-review',
+        message: INVALID_GATE_REVIEW_COMMAND_MESSAGE,
+    };
+}

package/dist/commands/gate/index.d.ts.map

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

package/dist/commands/gate/index.js

@@ -21,6 +21,7 @@ import YAML from 'yaml';
 import { createGateActivityProbe, } from './activity-probes.js';
 import { createBranchLocalGateCli, currentGateCliLaunch, readGateRouteReceipt, removeBranchLocalGateCli, } from './branch-local-cli.js';
 import { runChildProcess, } from './child-process.js';
+import { validateConfiguredGateCommand } from './configured-command.js';
 import { parseReviewGateVerdict, severityDisplayName, } from './review-verdict.js';
 import { createGateRouteCommand } from './route.js';
 const DEFAULT_DEPENDENCIES = {
@@ -71,6 +72,7 @@ const VALID_IDENTITY_PROVENANCES = [
 ];
 const REVIEW_GATE_CONTEXT_NOTE = [
     'This review is gate-originated. If you run `oat-project-review-provide`, set `oat_review_invocation: gate` in the review artifact. Write a canonical review artifact with `### Critical`, `### Important`, `### Medium`, and `### Minor` headings in that order, using `None` for empty sections.',
+    'Complete the review, artifact write, and required bookkeeping inline or through a synchronously awaited child before this headless process exits. Do not start background tasks, monitors, or waiters that outlive this turn.',
     "Artifact hygiene contract: Before finishing or committing, format every file you created or edited. Use the concrete write/fix formatting command supplied by the governing plan, task, or brief. If none is usable, discover the repository's documented write/fix command from applicable `AGENTS.md`/`CLAUDE.md` instructions and relevant package manifests; do not infer or hardcode a formatter. Prefer a file-scoped invocation when supported, and avoid rewriting unrelated files. If no command is discoverable, warn once with `no format command discovered in repo instructions; skipping`, then continue.",
 ].join('\n\n');
 const GATE_CHECK_TIMEOUT_MS = 5_000;
@@ -1528,6 +1530,32 @@ function writeReviewGateArtifactValidationFailure(context, payload) {
     context.logger.error(`Review completed but artifact validation failed: ${payload.message}`);
     context.logger.error(payload.recovery);
 }
+function writeReviewGateArtifactMissing(context, payload) {
+    const message = `Review target ${payload.target} completed without producing the required correlated review artifact.`;
+    const recovery = 'Fix the accepted headless target so it can write and finalize the review artifact before the process exits, then start a new gate run.';
+    if (context.json) {
+        context.logger.json({
+            status: 'artifact_missing',
+            outcome: 'review_completed_artifact_missing',
+            runId: payload.runId,
+            target: payload.target,
+            project: payload.project,
+            projectResolutionSource: payload.projectResolutionSource,
+            artifactPath: null,
+            generatedAt: null,
+            gateInvocation: payload.gateInvocation,
+            dispatchReport: payload.dispatchReport,
+            receiveEligible: false,
+            remediable: false,
+            handoff: null,
+            message,
+            recovery,
+        });
+        return;
+    }
+    context.logger.error(message);
+    context.logger.error(recovery);
+}
 function writeReviewGateTargetingFailure(context, payload) {
     const corroboration = {
         run: payload.corroboration.run,
@@ -1712,6 +1740,12 @@ async function runGateSet(skillName, options, context, dependencies) {
         const layer = parseLayer(options.layer);
         const normalizedSkill = trimRequired(skillName, '<skill>');
         const gate = parseGateConfig(options);
+        if (gate) {
+            const validation = validateConfiguredGateCommand(gate.command);
+            if (validation.kind === 'invalid') {
+                throw new Error(validation.message);
+            }
+        }
         const warnings = gate
             ? detectDevBuildGateCommandWarnings(gate.command)
             : [];
@@ -2068,6 +2102,23 @@ async function runReviewGate(prompt, options, context, dependencies) {
         const producedArtifact = artifactResolution.artifact;
         if (!producedArtifact) {
             const diagnosticArtifact = artifactResolution.diagnosticArtifact;
+            if (!diagnosticArtifact &&
+                artifactResolution.matchingArtifactPaths.length === 0) {
+                if (projectLogFinalization) {
+                    projectLogFinalization.status = 'artifact_missing';
+                    projectLogFinalization.exitCode = 1;
+                }
+                writeReviewGateArtifactMissing(context, {
+                    runId,
+                    target: selected.id,
+                    project: projectPath,
+                    projectResolutionSource: reviewProject.source,
+                    gateInvocation,
+                    dispatchReport,
+                });
+                process.exitCode = 1;
+                return;
+            }
             const message = artifactResolution.matchingArtifactPaths.length > 1
                 ? `Multiple direct review artifacts carried gate run ID ${runId}.`
                 : initialTargetCorroboration.run === 'mismatched'

package/dist/commands/pjm/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/doctor.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AA4LlE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CAiVxB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/doctor.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AA4MlE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CA2UxB"}

package/dist/commands/pjm/doctor.js

@@ -11,9 +11,25 @@ const ALLOWED_TOP_LEVEL_DIRECTORIES = new Set([
     'analysis',
     'reviews',
 ]);
-// A human-facing `README.md` at the repo-reference root is benign, so it is an
-// allowed top-level file alongside the canonical `AGENTS.md` (F5).
-const ALLOWED_TOP_LEVEL_FILES = new Set(['AGENTS.md', 'README.md']);
+// Human/provider-facing companions to the canonical `AGENTS.md` are benign.
+// Pointer correctness remains the responsibility of `oat instructions
+// validate`; PJM doctor only classifies the repository layout.
+const ALLOWED_TOP_LEVEL_FILES = new Set([
+    'AGENTS.md',
+    'CLAUDE.md',
+    'README.md',
+]);
+// `project-observations.md` is the documented append-only project-log ledger.
+// The remaining names have dedicated migration/duplicate checks below, so the
+// loose-reference classifier must not report them a second time.
+const ALLOWED_REFERENCE_FILES = new Set([
+    'AGENTS.md',
+    'CLAUDE.md',
+    'project-observations.md',
+    'decision-record.md',
+    'roadmap.md',
+    'current-state.md',
+]);
 const LEGACY_MONOLITHS = ['reference/decision-record.md'];
 async function pathExists(path) {
     try {
@@ -265,10 +281,7 @@ export async function runPjmDoctorChecks(repoRoot, options = {}) {
     const referenceEntries = await listDirectoryNames(join(repoRoot, 'reference'));
     const looseReferenceFiles = referenceEntries
         .filter((name) => name.endsWith('.md'))
-        .filter((name) => name !== 'AGENTS.md' &&
-        name !== 'decision-record.md' &&
-        name !== 'roadmap.md' &&
-        name !== 'current-state.md')
+        .filter((name) => !ALLOWED_REFERENCE_FILES.has(name))
         .map((name) => `reference/${name}`);
     checks.push({
         name: 'pjm:loose_reference_files',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.2.47"
+    "@open-agent-toolkit/control-plane": "0.2.49"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",