@open-agent-toolkit/cli 0.1.69 → 0.1.72

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/assets/docs/cli-utilities/configuration.md +27 -0
  2. package/assets/docs/cli-utilities/index.md +1 -1
  3. package/assets/docs/cli-utilities/workflow-gates.md +126 -3
  4. package/assets/docs/reference/cli-reference.md +5 -1
  5. package/assets/docs/workflows/projects/dispatch-ceiling.md +14 -5
  6. package/assets/docs/workflows/projects/orchestration-model.md +21 -0
  7. package/assets/docs/workflows/projects/review-flavors.md +9 -0
  8. package/assets/public-package-versions.json +4 -4
  9. package/assets/skills/oat-dispatch-subagents/SKILL.md +21 -1
  10. package/assets/skills/oat-dispatch-subagents/references/provider-claude.md +21 -0
  11. package/assets/skills/oat-dispatch-subagents/references/provider-codex.md +16 -0
  12. package/assets/skills/oat-dispatch-subagents/references/provider-cursor.md +21 -0
  13. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +3 -0
  14. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +3 -0
  15. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +3 -0
  16. package/assets/skills/oat-project-plan-writing/SKILL.md +23 -33
  17. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +3 -0
  18. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +3 -0
  19. package/assets/skills/oat-project-review-provide/SKILL.md +62 -1
  20. package/dist/commands/config/index.d.ts.map +1 -1
  21. package/dist/commands/config/index.js +65 -1
  22. package/dist/commands/gate/__fixtures__/fake-runtime.d.mts +3 -0
  23. package/dist/commands/gate/__fixtures__/fake-runtime.d.mts.map +1 -0
  24. package/dist/commands/gate/__fixtures__/fake-runtime.mjs +167 -0
  25. package/dist/commands/gate/activity-probes.d.ts +35 -0
  26. package/dist/commands/gate/activity-probes.d.ts.map +1 -0
  27. package/dist/commands/gate/activity-probes.js +135 -0
  28. package/dist/commands/gate/branch-local-cli.d.ts +31 -0
  29. package/dist/commands/gate/branch-local-cli.d.ts.map +1 -0
  30. package/dist/commands/gate/branch-local-cli.js +116 -0
  31. package/dist/commands/gate/index.d.ts +29 -0
  32. package/dist/commands/gate/index.d.ts.map +1 -1
  33. package/dist/commands/gate/index.js +438 -32
  34. package/dist/commands/gate/route.d.ts +22 -0
  35. package/dist/commands/gate/route.d.ts.map +1 -0
  36. package/dist/commands/gate/route.js +109 -0
  37. package/dist/commands/project/dispatch-ceiling/index.d.ts.map +1 -1
  38. package/dist/commands/project/dispatch-ceiling/index.js +100 -16
  39. package/dist/config/oat-config.d.ts +9 -0
  40. package/dist/config/oat-config.d.ts.map +1 -1
  41. package/dist/config/oat-config.js +23 -0
  42. package/dist/config/resolve.js +7 -0
  43. package/package.json +2 -2
package/assets/docs/cli-utilities/configuration.md CHANGED
@@ -87,6 +87,7 @@ Common keys in `.oat/config.json`:
87
87
  - `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
88
88
  - `tools.<pack>` — whether a bundled tool pack is currently installed in the repo or user scopes after lifecycle reconciliation
89
89
  - `workflow.gates.skills` / `workflow.gates.execTargets` — per-skill gates and cross-runtime exec targets; manage with `oat gate`
90
+ - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — default review budgets in milliseconds
90
91
 
91
92
  Tool-pack state example:
92
93
 
@@ -101,6 +102,31 @@ Workflow gate objects are structured config and use their own command group
101
102
  instead of the scalar `oat config set` surface. See
102
103
  [Workflow Gates](workflow-gates.md) for the full command surface and examples.
103
104
 
105
+ Gate budgets resolve per run in this order: CLI `--timeout-ms`, selected
106
+ target `timeoutMs`, `workflow.gateTimeouts` by review type,
107
+ `OAT_GATE_EXEC_TIMEOUT_MS`, then the built-in type-and-scope default. Values
108
+ must be integer milliseconds from `1,000` through `14,400,000`.
109
+
110
+ ```json
111
+ {
112
+ "workflow": {
113
+ "gateTimeouts": {
114
+ "code": 2400000,
115
+ "artifact": 900000
116
+ },
117
+ "gates": {
118
+ "execTargets": {
119
+ "cursor-large-review": {
120
+ "runtime": "cursor",
121
+ "baseCommand": ["cursor-agent", "-p", "--force"],
122
+ "timeoutMs": 3600000
123
+ }
124
+ }
125
+ }
126
+ }
127
+ }
128
+ ```
129
+
104
130
  Archive example:
105
131
 
106
132
  ```bash
@@ -467,6 +493,7 @@ Workflow preference keys live under the `workflow.*` namespace:
467
493
  - `workflow.dispatchCeiling.providers.<provider>.<tier>` — one matrix cell for `economy`, `balanced`, `high`, or `frontier`.
468
494
  - `workflow.dispatchCeiling.recommendationVersion` — version of the adopted recommended matrix.
469
495
  - `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, `oat gate review`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
496
+ - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — validated default gate-review budgets in milliseconds. Both resolve through `local > shared > user`.
470
497
 
471
498
  ### HiLL plan-field semantics
472
499
 
package/assets/docs/cli-utilities/index.md CHANGED
@@ -16,7 +16,7 @@ Use this section when you want bootstrap guidance, tool-pack lifecycle details,
16
16
  - [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
17
17
  - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
18
18
  - [Backlog Lifecycle](backlog-lifecycle.md) - Backlog item states, atomic close-out with `oat backlog archive`, and lifecycle drift detection in `oat pjm doctor`.
19
- - [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch with `oat gate`.
19
+ - [Workflow Gates](workflow-gates.md) - Completion-safe headless reviews, budgets, liveness evidence, and cross-runtime dispatch with `oat gate`.
20
20
 
21
21
  ## What Lives Here
22
22
 
package/assets/docs/cli-utilities/workflow-gates.md CHANGED
@@ -94,6 +94,51 @@ model that ran, and the reviewer must not replace them with self-identification.
94
94
  The CLI compares the copied values with its gate-owned record before it applies
95
95
  the severity threshold.
96
96
 
97
+ ### Headless completion safety
98
+
99
+ Every `oat gate review` child receives the same headless contract through two
100
+ channels:
101
+
102
+ - environment: `OAT_GATE_HEADLESS=1`, `OAT_NON_INTERACTIVE=1`,
103
+ `OAT_GATE_RUN_ID=<runId>`, immutable `OAT_GATE_RUNTIME` and
104
+ `OAT_INVOCATION_MODEL` values, and checkout-local CLI/receipt paths
105
+ - prompt frontmatter: `oat_gate_headless: true` plus the target runtime and
106
+ model
107
+
108
+ In headless mode, `oat-project-review-provide` calls the executable routing
109
+ helper instead of deciding from prose:
110
+
111
+ ```bash
112
+ "$OAT_GATE_CLI_PATH" gate route \
113
+ --expect-runtime "$OAT_GATE_RUNTIME" \
114
+ --expect-model "$OAT_INVOCATION_MODEL" \
115
+ --can-await true \
116
+ --json
117
+ ```
118
+
119
+ The helper returns `inline`, `delegate-sync`, or `refuse`. Inline review is
120
+ allowed when a provider marker for the expected/current child runtime is
121
+ present and trustworthy model evidence does not contradict the expected model.
122
+ That current-target marker takes precedence over inherited parent-provider
123
+ markers. Generic model variables and model variables belonging to other
124
+ providers are ignored because they may be inherited from the parent;
125
+ current-provider model evidence remains fail-closed. A missing current-target
126
+ marker or trustworthy contradiction delegates only through an awaited child
127
+ route. If no awaited route exists, the reviewer emits
128
+ `OAT_GATE_REFUSAL: <reason>` on its own line and fails closed. Headless review
129
+ never uses fire-and-forget background dispatch.
130
+
131
+ The route command must use the gate-provided checkout-local CLI; it must not
132
+ retry through bare or installed `oat`. The helper writes
133
+ `OAT_GATE_ROUTE_RECEIPT_PATH`, and the parent accepts it only when the JSON
134
+ decision shape is valid, `cliRoot` equals the checkout that launched the gate,
135
+ and `runtime` equals the selected invocation runtime. Missing, malformed,
136
+ cross-checkout, or runtime-mismatched receipts fail closed.
137
+
138
+ The gate recognizes refusal lines independently of the child exit code. A
139
+ validated run-correlated artifact still wins; without one, the envelope has
140
+ `status: review_failed`, includes `refusal`, and is not receive-eligible.
141
+
97
142
  ### Gate dispatch report semantics
98
143
 
99
144
  When gate dispatch is represented in a `DispatchReportV1`, consumers require
@@ -521,9 +566,76 @@ available target. Once a target actually runs, its exit code is the gate result;
521
566
  OAT does not try another target after a failed review.
522
567
 
523
568
  Gate target execution has a child-process timeout. Set
524
- `OAT_GATE_EXEC_TIMEOUT_MS` to a positive integer number of milliseconds to
525
- override the 900,000 ms (15-minute) default. An unset, non-integer, or
526
- non-positive value uses the default.
569
+ the budget at the narrowest useful level. The first valid value wins:
570
+
571
+ 1. command `--timeout-ms`
572
+ 2. selected exec target `timeoutMs`
573
+ 3. `workflow.gateTimeouts.code` or `workflow.gateTimeouts.artifact`
574
+ 4. `OAT_GATE_EXEC_TIMEOUT_MS`
575
+ 5. built-in type-and-scope default
576
+ 6. legacy `GATE_EXEC_TIMEOUT_MS` behavior for untyped `gate exec` runs
577
+
578
+ All configured values must be integer milliseconds from `1,000` through
579
+ `14,400,000`. Invalid persisted values are ignored with a warning and
580
+ resolution continues to the next source. Code reviews at `final`, phase
581
+ (`pNN`), or phase-range (`pNN-pMM`) scope default to 1,800,000 ms (30 minutes).
582
+ Task-scoped code reviews (`pNN-tNN`) and artifact reviews default to 900,000 ms
583
+ (15 minutes). Startup output reports both the resolved value and source.
584
+
585
+ Example migration from the former single environment override:
586
+
587
+ ```json
588
+ {
589
+ "workflow": {
590
+ "gateTimeouts": {
591
+ "code": 2400000,
592
+ "artifact": 900000
593
+ },
594
+ "gates": {
595
+ "execTargets": {
596
+ "cursor-large-review": {
597
+ "runtime": "cursor",
598
+ "baseCommand": ["cursor-agent", "-p", "--force"],
599
+ "timeoutMs": 3600000
600
+ }
601
+ }
602
+ }
603
+ }
604
+ }
605
+ ```
606
+
607
+ Use a one-off override without changing config:
608
+
609
+ ```bash
610
+ oat gate review --timeout-ms 2700000 \
611
+ --project "$PROJECT_PATH" \
612
+ --review-type code \
613
+ --review-scope final \
614
+ "Use oat-project-review-provide code final for the declared project"
615
+ ```
616
+
617
+ ### Liveness and post-mortem evidence
618
+
619
+ Each liveness tick keeps stdout-idle time and also reports `processAlive` plus
620
+ the latest metadata-only transcript activity as `lastActivityEvidence` when
621
+ available. The probe performs bounded depth-two traversal and compares newest
622
+ mtime plus total size with its spawn baseline. It never reads transcript
623
+ contents, never extends a budget, and never changes pass/fail or receive
624
+ eligibility.
625
+
626
+ Claude and Cursor evidence has `scope: project-dir`. Codex's date-sharded
627
+ sessions directory is shared across the runtime, so its evidence has
628
+ `scope: ambient-runtime`; human output labels it “ambient runtime activity (not
629
+ attributable to this gate child).” Probe errors fail soft to process and stdout
630
+ telemetry.
631
+
632
+ Timeout and child-failure envelopes include the latest `activityEvidence`.
633
+ Before spawn, the gate also writes a transient marker under the system temp
634
+ directory at `oat-gate-runs/<runId>.json`; startup diagnostics print its path.
635
+ The marker records target, runtime, project, review type/scope, start time,
636
+ budget, and budget source. It is deleted at terminal completion. An orphaned
637
+ marker indicates the gate parent itself stopped unexpectedly, but markers are
638
+ diagnostic only and are never used for artifact validation.
527
639
 
528
640
  After a review target times out, OAT re-scans the project reviews for exactly
529
641
  one artifact carrying that invocation's `oat_gate_run_id`. A recovered artifact
@@ -545,6 +657,17 @@ carrying the run ID, or a changed artifact carrying a mismatched run ID, return
545
657
  `targeting_correlation_failed` with `receiveEligible: false`. Do not receive
546
658
  those artifacts; correct the project/run correlation and start a new gate run.
547
659
 
660
+ ### Incident-to-regression mapping
661
+
662
+ | Observed failure | Regression coverage |
663
+ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
664
+ | Headless reviewer could not complete an async delegation | route unit matrix plus canonical checkout-local command, strict receipt, headless inline, and structured-refusal cases |
665
+ | Large final review exceeded the old 15-minute budget | scope-aware resolver tests plus scaled final-scope fake-runtime case |
666
+ | Silent child looked idle while transcripts grew | metadata-probe tests plus timeout-with-advancing-transcript fixture |
667
+ | Timeout or child failure produced no artifact | fail-closed `noOutputProduced` fixture |
668
+ | Artifact carried the wrong gate run ID | provenance-mismatch fixture |
669
+ | Passing artifact lost receive routing | handoff and `receiveEligible` fixture |
670
+
548
671
  ## Current limits
549
672
 
550
673
  Family diversity is selected before dispatch. If the selected provider command
package/assets/docs/reference/cli-reference.md CHANGED
@@ -68,8 +68,11 @@ Notable commands introduced in the current CLI surface:
68
68
  - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
69
69
  - `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#plan-declared-parallelism).
70
70
  - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
71
- - `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. 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. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. For `artifact_validation_failed`, correct the artifact and rerun the gate for successful revalidation before receive. `targeting_correlation_failed` sets `receiveEligible: false`; do not run review-receive even if it reports an artifact path. The child-process timeout defaults to 900,000 ms (15 minutes); set `OAT_GATE_EXEC_TIMEOUT_MS` to a positive integer number of milliseconds to override it. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. A timeout with no matching run-ID path and no changed diagnostic artifact returns `review_failed` with additive `noOutputProduced`, which is `true` only when the child emitted zero stdout and stderr bytes. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Neither additive field changes receive routing: continue to use `status`, `receiveEligible`, and `handoff`. Orchestrators should read the structured result rather than poll the filesystem. The command runs standalone (for example, `--review-scope final`), not only inside `oat-project-implement`. See [Workflow Gates → Gate completion signal](../cli-utilities/workflow-gates.md#gate-completion-signal).
71
+ - `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).
72
+ - `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.
73
+ - `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.
72
74
  - `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.
75
+ - `oat gate target set <id> --timeout-ms <milliseconds>` - persist a validated per-target gate budget.
73
76
  - `oat gate target list --json` - inspect resolved gate targets without selecting or executing a reviewer. Each entry reports its config origin, whether it is explicitly configured and enabled, current availability, and normalized configured invocation values (`unknown` when omitted).
74
77
  - `oat gate cross-provider-exec <prompt...>` - choose an available exec target while avoiding the current runtime by default, then run the prompt with the chosen target's configured base command and exit with the child status.
75
78
 
@@ -98,5 +101,6 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
98
101
  - `workflow.autoNarrowReReviewScope` (`boolean`) — auto-narrow re-review scope to fix-task commits
99
102
  - `workflow.autoArtifactReview.plan` (`boolean`, default `true`) — auto-run the bounded `plan.md` artifact-review loop before implementation handoff
100
103
  - `workflow.autoArtifactReview.analysis` (`boolean`, default `true`) — auto-run the bounded accuracy-review loop for generated analysis artifacts before apply workflows consume them
104
+ - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` (integer milliseconds from 1,000–14,400,000) — review-type budget defaults below CLI and target overrides
101
105
 
102
106
  These workflow keys resolve through config files and defaults (`local > shared > user > default`). Some config keys have explicit environment aliases, but `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not. See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.
package/assets/docs/workflows/projects/dispatch-ceiling.md CHANGED
@@ -71,11 +71,20 @@ when the current project has not selected a policy or named ceiling. Adoption
71
71
  is offered only when the resolved provider/tier cells are actually missing,
72
72
  empty, malformed, or incomplete.
73
73
 
74
- Ladder completeness and project-ceiling selection are separate checks. In
75
- particular, `oat project dispatch-ceiling resolve` returning `matrix: null` can
76
- mean that the project policy or ceiling is unresolved; it does not prove that
77
- the effective reusable ladders are absent. When ladders are complete, planning
78
- proceeds directly to the project-specific policy choice.
74
+ Ladder completeness and project-policy selection are separate checks.
75
+ `oat project dispatch-ceiling resolve --json` reports both:
76
+
77
+ - `unresolvedReason: policy | ladder | both` identifies which side is missing;
78
+ - `ladderCompleteness.complete` evaluates every supported provider/tier cell;
79
+ and
80
+ - `ladderCompleteness.missingCells` identifies the exact cells adoption would
81
+ fill.
82
+
83
+ The resolver preserves the merged effective `matrix` when only policy is
84
+ missing, so a missing project policy no longer looks like a missing reusable
85
+ ladder. Planning offers matrix adoption only for `ladder` or `both`, or when
86
+ `ladderCompleteness.complete` is false. With a complete ladder and only policy
87
+ unresolved, it proceeds directly to the project-specific policy choice.
79
88
 
80
89
  The ownership boundary is deliberate:
81
90
 
package/assets/docs/workflows/projects/orchestration-model.md CHANGED
@@ -127,6 +127,27 @@ phase ownership and task commit authority.
127
127
  Do not use nested dispatch merely to mirror task granularity. The smoke fixture
128
128
  intentionally proves successful execution with no task workers.
129
129
 
130
+ ## Dispatch Mode and Liveness
131
+
132
+ Choose foreground or background mode from expected duration and the host
133
+ interaction model. Short checks may run in foreground when interruption risk is
134
+ negligible. Multi-minute implementers, fix loops, and reviewers should use a
135
+ durable background handle when the host supports one, because ordinary session
136
+ interaction can interrupt a foreground child in Cursor.
137
+
138
+ Background is never fire-and-forget: retain the accepted handle, monitor useful
139
+ progress, and resume that same handle for bounded fixes. For a silent child,
140
+ provider transcript mtime and size can show observable activity without reading
141
+ transcript content; that evidence is liveness telemetry, not a health or
142
+ completion verdict.
143
+
144
+ Claude print mode (`claude -p`) has a separate hazard: background children are
145
+ terminated at its background-wait ceiling (600 seconds by default). Interactive
146
+ Claude Code is unaffected. Headless gate children therefore do not follow the
147
+ ordinary background preference; they use the gate's inline or synchronously
148
+ awaited route and fail closed when neither is available. See
149
+ [Workflow Gates](../../cli-utilities/workflow-gates.md#headless-completion-safety).
150
+
130
151
  ## Catalogs and Exact Selection
131
152
 
132
153
  Native model catalogs are per-dispatch-context snapshots. A root catalog does
package/assets/docs/workflows/projects/review-flavors.md CHANGED
@@ -76,6 +76,15 @@ external, configured, producer-independent target. Phase implementation may run
76
76
  _below_ the review ceiling for cost reasons, but review must never silently
77
77
  inherit the below-ceiling phase agent.
78
78
 
79
+ Pre-plan inheritance has a narrow executable guard. When dispatch resolution
80
+ reports `unresolvedReason: policy`, an artifact review of `discovery`, `design`,
81
+ or `spec` deliberately inherits the current planning context and records
82
+ `selection_reason: inherit (pre-plan; no project policy)`. An explicit project
83
+ policy is still honored at those scopes. Missing or incomplete ladders
84
+ (`unresolvedReason: ladder | both`) fail closed, as do plan-scope artifact
85
+ reviews and every code review without a resolved policy. Gate exec-target
86
+ selection is separate and unaffected.
87
+
79
88
  ## Independence and fail-closed semantics
80
89
 
81
90
  The invariant across all four flavors is that the reviewer runs **at or above
package/assets/public-package-versions.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
- "cli": "0.1.69",
3
- "docs-config": "0.1.69",
4
- "docs-theme": "0.1.69",
5
- "docs-transforms": "0.1.69"
2
+ "cli": "0.1.72",
3
+ "docs-config": "0.1.72",
4
+ "docs-theme": "0.1.72",
5
+ "docs-transforms": "0.1.72"
6
6
  }
package/assets/skills/oat-dispatch-subagents/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-dispatch-subagents
3
- version: 1.1.2
3
+ version: 1.1.3
4
4
  description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
5
5
  disable-model-invocation: true
6
6
  user-invocable: false
@@ -145,6 +145,26 @@ Keep these controls independent in selection and evidence:
145
145
  A materialized role may package defaults, but its record must preserve each
146
146
  configured axis separately.
147
147
 
148
+ ## Deliberate Dispatch Mode
149
+
150
+ Choose foreground or background deliberately from expected duration and the
151
+ host interaction model. Multi-minute implementers, fix loops, and reviewers
152
+ must survive ordinary session interaction and therefore run in background when
153
+ the host supports a durable awaited handle. Reserve foreground dispatch for
154
+ short checks whose interruption risk is negligible. Record the selected mode
155
+ and reason with the launch payload.
156
+
157
+ Background does not mean fire-and-forget. Retain and await the accepted handle,
158
+ apply the Acceptance and Recovery contract below, and surface useful progress.
159
+ In headless gate contexts, fire-and-forget background dispatch is forbidden:
160
+ use the gate's inline or synchronously awaited route contract instead.
161
+
162
+ For a silent background child, provider transcript filesystem metadata at the
163
+ documented runtime path can provide observable liveness evidence. Check only
164
+ metadata such as mtime and size. This evidence shows observable activity; it
165
+ is never a health verdict and never authorizes replacement, timeout extension,
166
+ or a second launch.
167
+
148
168
  ## Baseline Role Classes
149
169
 
150
170
  Specific role names are extensible, but map every dispatch to one class:
package/assets/skills/oat-dispatch-subagents/references/provider-claude.md CHANGED
@@ -42,3 +42,24 @@ satisfy a universal catalog rule.
42
42
 
43
43
  Verify current `claude --help` before using a CLI route. Preserve the caller's
44
44
  authority and construct a self-contained bounded prompt.
45
+
46
+ ## Dispatch Mode and Liveness
47
+
48
+ The background-wait ceiling hazard applies only to Claude print mode
49
+ (`claude -p`). Print-mode background children are terminated after
50
+ `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` (600 seconds by default). Interactive
51
+ Claude Code sessions are unaffected. Print mode is reachable in autonomous
52
+ and headless invocations outside gates as well as through gate exec targets, so
53
+ do not choose an unawaitable background route there. In gate contexts, defer to
54
+ the headless inline/synchronously-awaited route contract rather than
55
+ duplicating its decision.
56
+
57
+ Nested Claude subagent transcripts live below the parent session:
58
+
59
+ ```text
60
+ ~/.claude/projects/<encoded-cwd>/<parent-session-id>/subagents/agent-<id>.jsonl
61
+ ```
62
+
63
+ For a silent awaited child, use that specific file's mtime and size as
64
+ observable activity evidence only. Metadata change is not a health verdict and
65
+ does not alter acceptance or recovery policy.
package/assets/skills/oat-dispatch-subagents/references/provider-codex.md CHANGED
@@ -49,6 +49,22 @@ Only an actual role-selection rejection before child start permits another
49
49
  recorded route. Timeout, interruption, `BLOCKED`, or task failure after
50
50
  acceptance does not.
51
51
 
52
+ ## Child Transcript Liveness
53
+
54
+ Each native Codex subagent gets a separate rollout:
55
+
56
+ ```text
57
+ ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<start-timestamp>-<child-thread-id>.jsonl
58
+ ```
59
+
60
+ The child's `session_meta` carries `parent_thread_id`; the root rollout carries
61
+ the corresponding dispatch, steering, and result records. Because the
62
+ dispatcher knows the child thread ID at launch, resolve the child's own rollout
63
+ and inspect only its filesystem mtime and size for observable liveness
64
+ evidence. Rollouts shard by session start date: a fresh child of a long-lived
65
+ root can be in a different date directory, so resolve from the child's spawn
66
+ date, never the parent's. Metadata change is not a health verdict.
67
+
52
68
  ## CLI Route
53
69
 
54
70
  When native dispatch cannot express the complete target and the route is
package/assets/skills/oat-dispatch-subagents/references/provider-cursor.md CHANGED
@@ -29,6 +29,27 @@ Do not infer Cursor IDE behavior from a headless CLI surface. Keep bounded
29
29
  recon on economical explicit targets and reserve stronger targets for
30
30
  context-heavy or consequential work.
31
31
 
32
+ ## Dispatch Mode and Liveness
33
+
34
+ In an interactive Cursor session, a user message can interrupt a foreground
35
+ subagent turn. Run multi-minute implementers, fix loops, and reviewers in
36
+ background when the host provides a durable awaited handle; reserve foreground
37
+ for short checks. This background preference does not apply to headless gate
38
+ children, which must follow the inline/synchronously-awaited gate route
39
+ contract and never fire-and-forget.
40
+
41
+ The dispatch-returned agent ID directly addresses that background child's
42
+ transcript:
43
+
44
+ ```text
45
+ ~/.cursor/projects/<encoded-cwd>/agent-transcripts/<agentId>/<agentId>.jsonl
46
+ ```
47
+
48
+ This is a sibling of the main thread's transcript directory. For silent-child
49
+ liveness, stat that specific file's mtime and size rather than inferring from a
50
+ directory. Metadata change is observable activity evidence, not a health
51
+ verdict.
52
+
32
53
  ## Pre-Start CLI Routes
33
54
 
34
55
  When the current native intersection is absent or unsatisfactory, a caller may
package/assets/skills/oat-project-autonomous/references/gate-inventory.md CHANGED
@@ -239,6 +239,9 @@ remains immutable baseline evidence for the original p01-t01 verification.
239
239
  | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `ffcdc9d576c0 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `9497d9f94eed -> COMPLETE-01`; `7b59c728d3fb -> COMPLETE-01`; `48e10a9636fe -> COMPLETE-01`; `c0dad37fc166 -> COMPLETE-01`; `aa9a36243ec1 -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `12f7c30a54c8 -> NG`; `fffe5eea5ebd -> NG` |
240
240
  | `oat-project-review-provide/SKILL.md` | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `fab62c510bd0 -> REVIEWPROVIDE-05`; `a9f30853c867 -> REVIEWPROVIDE-05`; `0929c916fc20 -> REVIEWPROVIDE-05`; `f9a37c63afab -> REVIEWPROVIDE-05`; `687bb9368f92 -> REVIEWPROVIDE-05`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `fcb9de611ff3 -> NG`; `d2a838dfb18d -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG` |
241
241
  | `oat-project-review-receive/SKILL.md` | `9b8a3743d626 -> NG`; `df49c8c6f192 -> NG`; `4ee8730382d3 -> NG`; `655d61df0a8f -> NG`; `765f897d67ac -> NG`; `53b58d16dd32 -> NG`; `fb8755a3bdf4 -> NG`; `c8ab5dd90075 -> NG`; `1f7dd98dff2f -> NG`; `56f78c6740e6 -> NG`; `76f5fb5a88cd -> NG`; `085abfa3599f -> REVIEWRECEIVE-01`; `3ad3aadb8c60 -> NG`; `a7d114059bb6 -> NG`; `ac88cfaa83d9 -> NG`; `3f758313fedb -> REVIEWRECEIVE-08`; `f31f07284718 -> REVIEWRECEIVE-02`; `aba178a21441 -> REVIEWRECEIVE-04`; `a37e601cd731 -> REVIEWRECEIVE-05`; `20e05e1a4381 -> REVIEWRECEIVE-06`; `90001dadf75f -> REVIEWRECEIVE-07`; `f8fd58180ecf -> NG`; `c3abcdc02d9f -> NG`; `f2ebdd6abb9b -> NG` |
242
+ | `oat-project-review-provide/SKILL.md` | `2e794bf4fc4a -> REVIEWPROVIDE-08`; `5441ab977b46 -> REVIEWPROVIDE-08` |
243
+ | `oat-dispatch-subagents/SKILL.md` | `49987359dc09 -> NG` |
244
+ | `oat-dispatch-subagents/references/provider-claude.md` | `06f64bd01ba6 -> NG` |
242
245
  | `oat-dispatch-subagents/SKILL.md` | `cb4f86157fd6 -> DISPATCH-01`; `f165b1626192 -> DISPATCH-01`; `7ed5e2b1eb71 -> PDISPATCH-01`; `11c72bcdebad -> DISPATCH-02`; `0834ee701e12 -> DISPATCH-02`; `7fda54e1d519 -> PDISPATCH-01` |
243
246
  | `oat-dispatch-subagents/references/provider-claude.md` | `fbe3a21e9533 -> NG` |
244
247
  | `oat-dispatch-subagents/references/provider-codex.md` | `95b0f82018c7 -> NG` |
package/assets/skills/oat-project-document/references/docs/autonomy-contract.md CHANGED
@@ -239,6 +239,9 @@ remains immutable baseline evidence for the original p01-t01 verification.
239
239
  | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `ffcdc9d576c0 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `9497d9f94eed -> COMPLETE-01`; `7b59c728d3fb -> COMPLETE-01`; `48e10a9636fe -> COMPLETE-01`; `c0dad37fc166 -> COMPLETE-01`; `aa9a36243ec1 -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `12f7c30a54c8 -> NG`; `fffe5eea5ebd -> NG` |
240
240
  | `oat-project-review-provide/SKILL.md` | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `fab62c510bd0 -> REVIEWPROVIDE-05`; `a9f30853c867 -> REVIEWPROVIDE-05`; `0929c916fc20 -> REVIEWPROVIDE-05`; `f9a37c63afab -> REVIEWPROVIDE-05`; `687bb9368f92 -> REVIEWPROVIDE-05`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `fcb9de611ff3 -> NG`; `d2a838dfb18d -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG` |
241
241
  | `oat-project-review-receive/SKILL.md` | `9b8a3743d626 -> NG`; `df49c8c6f192 -> NG`; `4ee8730382d3 -> NG`; `655d61df0a8f -> NG`; `765f897d67ac -> NG`; `53b58d16dd32 -> NG`; `fb8755a3bdf4 -> NG`; `c8ab5dd90075 -> NG`; `1f7dd98dff2f -> NG`; `56f78c6740e6 -> NG`; `76f5fb5a88cd -> NG`; `085abfa3599f -> REVIEWRECEIVE-01`; `3ad3aadb8c60 -> NG`; `a7d114059bb6 -> NG`; `ac88cfaa83d9 -> NG`; `3f758313fedb -> REVIEWRECEIVE-08`; `f31f07284718 -> REVIEWRECEIVE-02`; `aba178a21441 -> REVIEWRECEIVE-04`; `a37e601cd731 -> REVIEWRECEIVE-05`; `20e05e1a4381 -> REVIEWRECEIVE-06`; `90001dadf75f -> REVIEWRECEIVE-07`; `f8fd58180ecf -> NG`; `c3abcdc02d9f -> NG`; `f2ebdd6abb9b -> NG` |
242
+ | `oat-project-review-provide/SKILL.md` | `2e794bf4fc4a -> REVIEWPROVIDE-08`; `5441ab977b46 -> REVIEWPROVIDE-08` |
243
+ | `oat-dispatch-subagents/SKILL.md` | `49987359dc09 -> NG` |
244
+ | `oat-dispatch-subagents/references/provider-claude.md` | `06f64bd01ba6 -> NG` |
242
245
  | `oat-dispatch-subagents/SKILL.md` | `cb4f86157fd6 -> DISPATCH-01`; `f165b1626192 -> DISPATCH-01`; `7ed5e2b1eb71 -> PDISPATCH-01`; `11c72bcdebad -> DISPATCH-02`; `0834ee701e12 -> DISPATCH-02`; `7fda54e1d519 -> PDISPATCH-01` |
243
246
  | `oat-dispatch-subagents/references/provider-claude.md` | `fbe3a21e9533 -> NG` |
244
247
  | `oat-dispatch-subagents/references/provider-codex.md` | `95b0f82018c7 -> NG` |
package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md CHANGED
@@ -239,6 +239,9 @@ remains immutable baseline evidence for the original p01-t01 verification.
239
239
  | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `ffcdc9d576c0 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `9497d9f94eed -> COMPLETE-01`; `7b59c728d3fb -> COMPLETE-01`; `48e10a9636fe -> COMPLETE-01`; `c0dad37fc166 -> COMPLETE-01`; `aa9a36243ec1 -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `12f7c30a54c8 -> NG`; `fffe5eea5ebd -> NG` |
240
240
  | `oat-project-review-provide/SKILL.md` | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `fab62c510bd0 -> REVIEWPROVIDE-05`; `a9f30853c867 -> REVIEWPROVIDE-05`; `0929c916fc20 -> REVIEWPROVIDE-05`; `f9a37c63afab -> REVIEWPROVIDE-05`; `687bb9368f92 -> REVIEWPROVIDE-05`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `fcb9de611ff3 -> NG`; `d2a838dfb18d -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG` |
241
241
  | `oat-project-review-receive/SKILL.md` | `9b8a3743d626 -> NG`; `df49c8c6f192 -> NG`; `4ee8730382d3 -> NG`; `655d61df0a8f -> NG`; `765f897d67ac -> NG`; `53b58d16dd32 -> NG`; `fb8755a3bdf4 -> NG`; `c8ab5dd90075 -> NG`; `1f7dd98dff2f -> NG`; `56f78c6740e6 -> NG`; `76f5fb5a88cd -> NG`; `085abfa3599f -> REVIEWRECEIVE-01`; `3ad3aadb8c60 -> NG`; `a7d114059bb6 -> NG`; `ac88cfaa83d9 -> NG`; `3f758313fedb -> REVIEWRECEIVE-08`; `f31f07284718 -> REVIEWRECEIVE-02`; `aba178a21441 -> REVIEWRECEIVE-04`; `a37e601cd731 -> REVIEWRECEIVE-05`; `20e05e1a4381 -> REVIEWRECEIVE-06`; `90001dadf75f -> REVIEWRECEIVE-07`; `f8fd58180ecf -> NG`; `c3abcdc02d9f -> NG`; `f2ebdd6abb9b -> NG` |
242
+ | `oat-project-review-provide/SKILL.md` | `2e794bf4fc4a -> REVIEWPROVIDE-08`; `5441ab977b46 -> REVIEWPROVIDE-08` |
243
+ | `oat-dispatch-subagents/SKILL.md` | `49987359dc09 -> NG` |
244
+ | `oat-dispatch-subagents/references/provider-claude.md` | `06f64bd01ba6 -> NG` |
242
245
  | `oat-dispatch-subagents/SKILL.md` | `cb4f86157fd6 -> DISPATCH-01`; `f165b1626192 -> DISPATCH-01`; `7ed5e2b1eb71 -> PDISPATCH-01`; `11c72bcdebad -> DISPATCH-02`; `0834ee701e12 -> DISPATCH-02`; `7fda54e1d519 -> PDISPATCH-01` |
243
246
  | `oat-dispatch-subagents/references/provider-claude.md` | `fbe3a21e9533 -> NG` |
244
247
  | `oat-dispatch-subagents/references/provider-codex.md` | `95b0f82018c7 -> NG` |