@open-agent-toolkit/cli 0.2.58 → 0.2.59

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.58"
+  "oatVersion": "0.2.59"
 }

package/assets/docs/cli-utilities/configuration.md

@@ -367,6 +367,22 @@ Repo-local and user config can also hold workflow defaults, including
 example, one user may prefer `claude -p` as a gate target while another prefers
 `codex exec`.
 
+### Per-project gate posture
+
+Project state is a separate surface from the five config layers. One project can
+disable a configured lifecycle gate for itself through
+`oat_skill_gate_overrides` in that project's `state.md`, keyed by gate-aware
+skill name with the single permitted value `disabled`.
+
+Config layers decide whether a gate exists; the project override then decides
+whether an existing gate runs for that project. An override never creates
+configuration, never mutates any config layer, and is never written by a
+non-interactive run. Resolve it with
+`oat gate resolve <skill> --project <path-or-name> --json`; without `--project`
+the command keeps its original raw output. See
+[Workflow gates](./workflow-gates.md) for the full resolution envelope and the
+phase-review and autonomous exclusions.
+
 In practice, you usually inspect these via:
 
 ```bash

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

@@ -68,6 +68,83 @@ in skill frontmatter with `oat_gateable: true`, and
 `oat internal validate-oat-skills` warns when config targets a missing or
 non-gateable skill.
 
+### Per-project gate overrides
+
+Gate configuration is shared, but one project can opt out of a configured
+lifecycle gate without changing any config layer. The override lives only in
+that project's `state.md`:
+
+```yaml
+oat_skill_gate_overrides:
+  oat-project-implement: disabled
+```
+
+The map is strict. Keys are gate-aware skill names and the only permitted value
+is the literal `disabled`. Arrays, booleans, `enabled`, unknown values,
+duplicate keys, and malformed maps are rejected with the offending project state
+path. An absent map means follow configuration; keeping every gate leaves the
+map absent.
+
+Override keys are accepted only for skills that declare `oat_gateable: true`.
+A configured gate may still be resolved and executed for a lifecycle skill that
+is not gate-aware — `oat-project-discover` and `oat-project-design` are the
+current examples — but because no override key for such a skill is accepted,
+their configured gates apply to every project and cannot be disabled per
+project.
+
+Precedence is layered, not merged: config layers decide whether a gate exists
+at all, and the project override then decides whether an existing gate runs for
+that project. An override never creates configuration, so a project may record
+an override for a skill that has no configured gate; the gate stays absent.
+Overrides never mutate shared, local, or user config, and config changes never
+rewrite a project's override.
+
+Interactive project setup offers a keep-or-disable choice per configured gate,
+one skill at a time; there is no single switch that disables every gate.
+Non-interactive runs never prompt and never write a new map, and an explicit
+existing map is preserved unchanged on resume and import.
+
+Resolution is opt-in. Without `--project`, `oat gate resolve` keeps returning
+the raw `GateConfig | null` that existing consumers parse:
+
+```bash
+oat gate resolve oat-project-implement --json
+```
+
+With project context it returns a discriminated envelope instead:
+
+```bash
+oat gate resolve oat-project-implement --project "$PROJECT_PATH" --json
+```
+
+The envelope's `resolution` is one of three values:
+
+| `resolution`                     | Meaning                                   | `configuredGate` | `effectiveGate` |
+| -------------------------------- | ----------------------------------------- | ---------------- | --------------- |
+| `configured`                     | A configured gate runs for this project.  | the gate         | the gate        |
+| `configured_disabled_by_project` | Configured, but this project disabled it. | the gate         | `null`          |
+| `not_configured`                 | No gate is configured for this skill.     | `null`           | `null`          |
+
+`configured_disabled_by_project` retains `configuredGate` so evidence of a
+deliberate opt-out can never be mistaken for absent configuration. It also
+carries `configSource` and a `projectOverride` record naming the
+`state.md:oat_skill_gate_overrides` source.
+
+`configSource` reports the layer that owned the decision. For
+`not_configured` it is the layer that explicitly declared the skill `null`, and
+`null` only when no layer mentions the skill at all, so a deliberate
+layer-level disable stays distinguishable from an absent declaration.
+`configuredGate` is `null` in both cases, so neither reads as configured.
+
+Disabled is a posture, not an outcome. A project-disabled gate launches no
+process and never enters the passed, missing, or failed branches. Project
+progress reports every active override by skill key so the deliberate posture
+stays visible to reviewers.
+
+This mechanism covers configured lifecycle skill gates only. It does not affect
+the optional `oat_phase_review_gate`, HiLL policy, or autonomous design-gate
+behavior, and it cannot disable every gate with one project-wide boolean.
+
 ### Implementation exit-gate closeout
 
 For `oat-project-implement`, the configured skill gate is a final, resumable
@@ -82,14 +159,22 @@ configured command. The state records:
 
 - `pending`, `allowed`, `blocked`, or `stale` status;
 - a `configured` or `no_gate` resolution;
-- `passed`, `warned`, `prompt_approved`, or `no_gate` allowed dispositions;
+- `passed`, `warned`, `prompt_approved`, `project_disabled`, or `no_gate`
+  allowed dispositions;
 - the resolved configuration fingerprint, reviewed HEAD, implementation
   fingerprint, gate run, envelope, and receive provenance; and
 - launch and receive reconciliation data needed to resume without duplicating
   an accepted run or completed receive.
 
-A `null` resolution is explicit success for that closeout generation:
-`allowed/no_gate` with `disposition: no_gate`. Configured success becomes
+Only a `not_configured` resolution is explicit success for that closeout
+generation: `allowed/no_gate` with `disposition: no_gate`. A null, missing,
+malformed, or unrecognized resolver result fails closed as unresolved and is
+never treated as no gate. A gate this project disabled
+persists `allowed/configured` with `disposition: project_disabled`, the
+configured command retained as never-executed evidence, null launch and receive
+provenance, and a `project_override` record. `config_fingerprint` covers the
+resolved override state, so re-enabling the gate changes the fingerprint and a
+stored `project_disabled` result is routed as stale instead of reused. Configured success becomes
 `allowed/passed`; `warn` and an explicit `prompt` continuation persist their
 own allowed dispositions only for a validated, receive-eligible `blocked`
 envelope after eligible receive completes durably. Unresolved, malformed,

package/assets/docs/contributing/skills.md

@@ -277,15 +277,37 @@ Use `create-agnostic-skill` or `create-oat-skill` as the starting point; both in
 
 ## Gate-aware skills
 
-A skill that supports configured final gates must declare `oat_gateable: true`
+A skill that supports configured final gates should declare `oat_gateable: true`
 in frontmatter and include a final Gate Execution step in its process contract.
-Without both pieces, a configured `workflow.gates.skills.<skill>` entry is a
-validation warning rather than an executable contract.
+Without both pieces, a configured `workflow.gates.skills.<skill>` entry raises a
+`Configured gate targets skill without oat_gateable: true` validation warning.
+
+The warning does not make the gate inert. `oat_gateable` governs per-project
+override eligibility, not executability: `oat gate resolve` runs the same
+lookup for every skill name, so a configured gate on a non-gate-aware skill
+still resolves as `configured` and still executes if that skill carries a Gate
+Execution step. `oat-project-discover` and `oat-project-design` are the current
+examples. Because no `oat_skill_gate_overrides` key is accepted for a skill
+outside `oat_gateable`, their configured gates apply to every project and can
+never resolve `configured_disabled_by_project`. Prefer declaring
+`oat_gateable: true` for any skill whose gate should be disableable per project.
 
 The Gate Execution step should:
 
-1. Run `oat gate resolve <this-skill> --json`.
-2. Treat `null` as "no gate configured."
+1. Run `oat gate resolve <this-skill> --project "$PROJECT_PATH" --json`
+   (`$PROJECT_PATH` is the resolved project path exported in step 3).
+   Project context is required. Without `--project` the command returns the
+   legacy raw gate and can never report a project override, so the skill would
+   silently run a gate the project deliberately disabled.
+2. Handle all three `resolution` values explicitly:
+   - `configured` - run `effectiveGate` exactly as configured.
+   - `configured_disabled_by_project` - the project disabled this configured gate. Do not launch any process; emit `configured but disabled by project override`, including the project path and the `projectOverride` source, and finish the skill. The returned `configuredGate` is evidence only and is never executed.
+   - `not_configured` - no gate is configured; finish the skill.
+
+   A null, missing, malformed, or unrecognized result is an operational failure
+   that fails closed as unresolved. Never treat it as "no gate configured." See
+   [Per-project gate overrides](../cli-utilities/workflow-gates.md#per-project-gate-overrides).
+
 3. Export the resolved path with `export PROJECT_PATH` before launching the
    command shell.
 4. For `oat gate review`, require the configured command to use

package/assets/docs/provider-sync/commands.md

@@ -88,6 +88,29 @@ Key behavior:
   `versionSkew` array (`{ scope, producingVersion, invokingVersion }`) in both
   `--dry-run` and apply envelopes; a scope without skew is omitted from the
   array.
+- When a run's only effect is that restamp — no planned operations and no
+  failures, but skew present — apply reports
+  `Manifest version refreshed; no content changes required.` instead of
+  `No changes required.`, so a manifest write is never described as a no-op.
+
+`oat sync` is not the only command that replaces a manifest's producer version.
+`oat init`, `oat remove skill`, and `oat status` each capture the manifest's
+pre-mutation `oatVersion` while loading and planning, compare it with the
+invoking CLI version, and log the same advisory immediately before a qualifying
+save when the two differ:
+
+```text
+Manifest version restamp [init user]: manifest produced by oat "0.2.58" will be restamped to oat "0.2.59".
+```
+
+The advisory sits immediately before the save, so a run that aborts earlier
+never announces a restamp it did not perform; a save that fails after the
+advisory still leaves the manifest unrestamped. An equal or absent version stays
+quiet. JSON mode suppresses the human warning; `oat init` and `oat remove skill`
+report the applied restamps under a top-level `manifestVersionRestamps` array of
+`{ scope, producingVersion, invokingVersion }` entries. The `oat remove skill`
+dry-run payload omits the field rather than naming a restamp no save will
+perform.
 
 Preview project and user cleanup before applying it:
 

package/assets/docs/workflows/projects/autonomy.md

@@ -136,8 +136,11 @@ At final closeout, autonomy follows the same authoritative order as an
 interactive run: final verification, mandatory final lifecycle review,
 configured implementation exit gate, pre-approval sequence, final HiLL
 approval, post-approval sequence, then implementation completion and success
-output. A null gate resolution persists an explicit no-gate allowance before
-the sequence starts.
+output. A `not_configured` resolution persists an explicit no-gate allowance
+before the sequence starts; a null, missing, or unrecognized resolver result
+fails closed as unresolved. A gate this project disabled persists an
+`allowed/configured` result with `disposition: project_disabled` and never
+launches the configured command.
 
 Autonomy does not turn an ordinary independent review into configured-gate
 provenance. A configured review must produce a gate-originated artifact with

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -438,7 +438,8 @@ write authority. See
 ## Dispatch Report V1 and Producer Provenance
 
 Resolver calls that pass `--report-scope` and `--report-action` include a
-`dispatchReport` object in JSON output. Consumers must require
+`dispatchReport` object in JSON output, plus the additive `dispatchStamp`
+string described below. Consumers must require
 `dispatchReport.schemaVersion: 1` before dispatch. The report keeps these
 concerns separate:
 
@@ -485,18 +486,53 @@ also retain a parseable compatibility stamp for later review gates:
 Dispatch: scope=p06-t03 action=implementation role=implementer producer=gpt-5.6-sol provenance=declared model_axis=selected:gpt-5.6-sol effort_axis=selected:high dispatch_policy=high dispatch_ceiling=high target=oat-phase-implementer-gpt-5-6-sol-high
 ```
 
-The stamp must be derived through `toDispatchStampRecord(dispatchReport)` and
-`formatDispatchStamp`; callers must not reconstruct it from policy labels, role
-names, candidate strings, or target names. `producer` is the runtime model slug
-when OAT can establish it; otherwise it is `unknown`. `provenance` is
-`declared`, `observed`, `inferred`, or `unknown`. Selected model and effort axes
-can remain exact even when runtime producer identity is not reported.
+`producer` is the runtime model slug when OAT can establish it; otherwise it is
+`unknown`. `provenance` is `declared`, `observed`, `inferred`, or `unknown`.
+Selected model and effort axes can remain exact even when runtime producer
+identity is not reported.
 
 Before launching an implementation, fix, or reviewer, surface the structured
 notices in `dispatchReport.notices` and render the report. Structured notices
 and runtime disclosure use the effective target returned by that resolver call,
 never a target inferred from the bundled recommendation version.
 
+### The additive `dispatchStamp` field
+
+JSON responses that carry `dispatchReport` also carry `dispatchStamp`, a single
+canonical string produced by the same formatter that owns the grammar above:
+
+```json
+{
+  "status": "resolved",
+  "dispatchReport": { "schemaVersion": 1 },
+  "dispatchStamp": "Dispatch: scope=p06-t03 action=implementation role=implementer ..."
+}
+```
+
+Field eligibility matches report eligibility exactly. The field is present when
+and only when `dispatchReport` is present, so non-report resolver calls and
+error envelopes never carry it. `DispatchReportV1`, its schema version, and the
+stamp grammar are unchanged; the field is purely additive.
+
+Eligibility tracks report presence, not dispatch authorization or exit code. A
+`status: blocked` response that was asked for report context therefore carries
+both `dispatchReport` and `dispatchStamp` while still exiting `1`: the stamp
+records what OAT resolved, and a blocked resolution is a resolved fact about an
+unusable route rather than a missing report. Only a call without report context,
+or an error envelope that never built a report, omits the field.
+
+Consumers read `dispatchStamp` directly, validate that it is a non-empty string
+beginning with the canonical `Dispatch:` prefix, and copy it byte-for-byte into
+dispatch and audit metadata. Reformatting the report through
+`toDispatchStampRecord(dispatchReport)` and `formatDispatchStamp` is an optional
+corroboration where that library is already loaded; it is never the normal path,
+and no out-of-tree shim is required. Callers must not reconstruct the stamp from
+policy labels, role names, candidate strings, or target names.
+
+A stamp carrying `producer=unknown provenance=unknown` is truthful, not
+degraded: the resolver reports configured invocation, and those fields stay
+`unknown` until an independent runtime observation exists.
+
 ## Legacy Compatibility
 
 The following remain readable during migration:

package/assets/docs/workflows/projects/implementation-execution.md

@@ -250,8 +250,11 @@ for another.
 
 Resolution and policy outcomes are explicit:
 
-- A null resolution persists `allowed/no_gate` for the current implementation
-  basis.
+- A `not_configured` resolution persists `allowed/no_gate` for the current
+  implementation basis; a null, missing, or unrecognized resolver result fails
+  closed as unresolved instead.
+- A gate the project disabled persists `allowed/configured` with
+  `disposition: project_disabled` and never launches.
 - A configured passing review persists `allowed/passed` after any eligible
   review receive is durably completed.
 - `warn` persists `allowed/warned`; `prompt` proceeds only after explicit

package/assets/docs/workflows/projects/lifecycle.md

@@ -56,9 +56,10 @@ Implementation closeout has one authoritative order:
 
 The configured exit gate is independent from the mandatory lifecycle review,
 root-owned phase reviews, and optional `oat_phase_review_gate`. It must reach an
-allowed and fresh disposition before pre-approval work starts. A null
-configuration is recorded explicitly as `allowed/no_gate`; it is not inferred
-from missing state.
+allowed and fresh disposition before pre-approval work starts. A
+`not_configured` resolution is recorded explicitly as `allowed/no_gate`; it is
+not inferred from missing state, and a null, missing, or unrecognized resolver
+result fails closed as unresolved instead.
 
 After implementation closeout finishes:
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.58",
-  "docs-config": "0.2.58",
-  "docs-theme": "0.2.58",
-  "docs-transforms": "0.2.58"
+  "cli": "0.2.59",
+  "docs-config": "0.2.59",
+  "docs-theme": "0.2.59",
+  "docs-transforms": "0.2.59"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-autonomous
-version: 1.0.10
+version: 1.0.11
 description: Use when a user explicitly asks to run an OAT project autonomously end-to-end. Activates session-only autonomy, resumes the correct lifecycle phase, and drives the existing OAT skills through final PR or a reported boundary.
 argument-hint: '<goal | project-slug | ticket-ref>'
 disable-model-invocation: true