@open-agent-toolkit/cli 0.2.51 → 0.2.52

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan-writing
-version: 1.2.20
+version: 1.2.21
 description: Use when authoring or mutating plan.md in any OAT workflow. Defines canonical format invariants — stable task IDs, required sections, review table rules, and resume guardrails.
 disable-model-invocation: true
 user-invocable: false
@@ -259,6 +259,17 @@ unavailable in the current session. Base Codex roles are allowed only for
 explicit inherit/default behavior and the documented managed-uncapped reviewer
 fallback.
 
+Artifact-review launches preserve native dispatch lineage. Construct and
+redact the complete generic record plus OAT role event before the native call.
+Immediately after the call returns `accepted` or `blocked-before-start`, the
+calling project workflow runs `oat project dispatch record --project
+"$PROJECT_PATH" --event-file - --json`. Only a rejection attesting
+`provesNoChildStarted: true` permits one exact-target approximation with a
+fresh request ID. Preserve exact model, effort, route, authority, and provider
+controls. Timeout, `BLOCKED`, refusal after acceptance, runtime mismatch,
+missing telemetry, interruption, and malformed output never authorize fallback
+or replacement.
+
 Inline review of a concrete managed exception target is permitted only with
 verified equivalent current-host model and effort controls. The default
 inheritance route may review inline because the planning parent is the selected

package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md

@@ -256,7 +256,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
 | `oat-dispatch-subagents/references/provider-claude.md`         | `fbe3a21e9533 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `oat-dispatch-subagents/references/provider-codex.md`          | `95b0f82018c7 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `oat-dispatch-subagents/references/provider-cursor.md`         | `f781555295a9 -> NG`; `55ccfef14fd6 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `oat-dispatch-subagents/references/record-schema.md`           | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `oat-dispatch-subagents/references/record-schema.md`           | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `oat-project-dispatch-subagents/SKILL.md`                      | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `oat-project-plan/SKILL.md`                                    | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `oat-project-implement/references/completion-and-closeout.md`  | `6909a5a5a1fa -> IMPLEMENT-19`; `a7c02ef670fd -> IMPLEMENT-19`; `9dde56d89a71 -> IMPLEMENT-16`; `13c41b2b2590 -> IMPLEMENT-16`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md

@@ -256,7 +256,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
 | `oat-dispatch-subagents/references/provider-claude.md`         | `fbe3a21e9533 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `oat-dispatch-subagents/references/provider-codex.md`          | `95b0f82018c7 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `oat-dispatch-subagents/references/provider-cursor.md`         | `f781555295a9 -> NG`; `55ccfef14fd6 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `oat-dispatch-subagents/references/record-schema.md`           | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `oat-dispatch-subagents/references/record-schema.md`           | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `oat-project-dispatch-subagents/SKILL.md`                      | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `oat-project-plan/SKILL.md`                                    | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `oat-project-implement/references/completion-and-closeout.md`  | `6909a5a5a1fa -> IMPLEMENT-19`; `a7c02ef670fd -> IMPLEMENT-19`; `9dde56d89a71 -> IMPLEMENT-16`; `13c41b2b2590 -> IMPLEMENT-16`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.5.2
+version: 1.5.3
 description: Use when the user explicitly asks to review an OAT project — e.g. "review project", "review the project", "run project review", or confirms a previously offered review. Do NOT auto-invoke on completed work alone. Resolves a project review scope and offers before running.
 disable-model-invocation: false
 user-invocable: true
@@ -724,6 +724,17 @@ After constructing the complete provider payload, record the launcher-owned
 missing telemetry, missing reviewer self-report, or contradictory self-report
 must not populate, replace, or overwrite them and must not trigger fallback.
 
+Persist native dispatch lineage around the host-owned review launch. Construct
+and redact the complete generic record plus OAT role event before the native
+call. Immediately after the call returns `accepted` or
+`blocked-before-start`, run `oat project dispatch record --project
+"$PROJECT_PATH" --event-file - --json`. The rejected form must attest
+`provesNoChildStarted: true`; only it permits one exact-target approximation
+with a fresh request ID. Preserve the exact model, effort, route, authority,
+and provider controls. Timeout, `BLOCKED`, refusal after acceptance, runtime
+mismatch, missing telemetry, interruption, and malformed output never
+authorize fallback or replacement.
+
 Once the native host accepts a reviewer, every terminal result is an
 authoritative review outcome. An accepted reviewer returning `BLOCKED` is a
 terminal blocking review outcome: it blocks the review and does not invoke or

package/assets/skills/oat-project-review-provide-remote/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide-remote
-version: 1.1.1
+version: 1.1.2
 description: Use when reviewing a GitHub PR opened on another machine for an active OAT project and posting findings back as a single PR review. Resolves the project from the PR diff, reads project artifacts for mode-aware review, and posts via gh api.
 disable-model-invocation: true
 user-invocable: true
@@ -311,6 +311,17 @@ route. After acceptance, continue only through the existing reviewer handle;
 timeout, interruption, malformed output, or `BLOCKED` never authorizes a
 replacement launch.
 
+Persist native dispatch lineage around the host-owned remote-review launch.
+Construct and redact the complete generic record plus OAT role event before the
+native call. Immediately after the call returns `accepted` or
+`blocked-before-start`, run `oat project dispatch record --project
+"$PROJECT_PATH" --event-file - --json`. The rejected form must attest
+`provesNoChildStarted: true`; only it permits one exact-target approximation
+with a fresh request ID. Preserve exact model, effort, route, authority, and
+provider controls. Timeout, `BLOCKED`, refusal after acceptance, runtime
+mismatch, malformed output, interruption, and missing telemetry never
+authorize fallback or replacement.
+
 This resolver command is independent of lifecycle gates. Reusable `oat gate
 review` commands must remain provider-neutral and must not contain or add a
 provider/model `--target` argument.

package/dist/agents/canonical/index.d.ts

@@ -1,4 +1,6 @@
 export { parseCanonicalAgentFile, parseCanonicalAgentMarkdown } from './parse.js';
+export { resolveCanonicalRole } from './resolve.js';
 export { renderCanonicalAgentMarkdown } from './render.js';
+export type { CandidateMiss, CanonicalRoleCandidateOutcome, CanonicalRoleEvidence, CanonicalRoleTier, CanonicalRoleValidation, RecoveryAction, RedactedPath, ResolveCanonicalRoleInput, } from './resolve.js';
 export type { CanonicalAgentDocument, CanonicalAgentFrontmatter, CanonicalAgentTools, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/agents/canonical/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/canonical/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EACV,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/canonical/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EACV,aAAa,EACb,6BAA6B,EAC7B,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,yBAAyB,GAC1B,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,SAAS,CAAC"}

package/dist/agents/canonical/index.js

@@ -1,2 +1,3 @@
 export { parseCanonicalAgentFile, parseCanonicalAgentMarkdown } from './parse.js';
+export { resolveCanonicalRole } from './resolve.js';
 export { renderCanonicalAgentMarkdown } from './render.js';

package/dist/agents/canonical/resolve.d.ts

@@ -0,0 +1,45 @@
+export type CanonicalRoleTier = 'loaded' | 'user' | 'project';
+export type CanonicalRoleValidation = 'direct-canonical' | 'exact-canonical-symlink';
+export type CanonicalRoleCandidateOutcome = 'missing' | 'broken-symlink' | 'escaping-symlink' | 'noncanonical-copy' | 'wrong-target' | 'invalid-role';
+export type RedactedPath = string;
+export interface CandidateMiss {
+    tier: CanonicalRoleTier;
+    candidate: RedactedPath;
+    outcome: CanonicalRoleCandidateOutcome;
+}
+export interface RecoveryAction {
+    command: string;
+}
+export type CanonicalRoleEvidence = {
+    status: 'resolved';
+    dependency: string;
+    canonicalRole: string;
+    tier: CanonicalRoleTier;
+    validation: CanonicalRoleValidation;
+    canonicalPath: RedactedPath;
+    selectedPath: RedactedPath;
+    roleVersion: string;
+    contentDigest: string;
+    candidateMisses: readonly CandidateMiss[];
+} | {
+    status: 'missing';
+    dependency: string;
+    canonicalRole: string;
+    candidateMisses: readonly CandidateMiss[];
+    recovery: readonly RecoveryAction[];
+};
+export interface ResolveCanonicalRoleInput {
+    dependency: string;
+    canonicalRole: string;
+    skillDir: string;
+    userCanonicalRoot: string;
+    projectCanonicalRoot: string;
+}
+/**
+ * Deliberately a library for skill-side callers: dispatch protocols resolve
+ * role identity before the native launch and hand the resulting evidence to
+ * `oat project dispatch record`, which validates it. There is intentionally no
+ * production call site inside the CLI.
+ */
+export declare function resolveCanonicalRole(input: ResolveCanonicalRoleInput): CanonicalRoleEvidence;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/agents/canonical/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/agents/canonical/resolve.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAC9D,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,GAClB,yBAAyB,CAAC;AAC9B,MAAM,MAAM,6BAA6B,GACrC,SAAS,GACT,gBAAgB,GAChB,kBAAkB,GAClB,mBAAmB,GACnB,cAAc,GACd,cAAc,CAAC;AAEnB,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,6BAA6B,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,qBAAqB,GAC7B;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,EAAE,uBAAuB,CAAC;IACpC,aAAa,EAAE,YAAY,CAAC;IAC5B,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC,CAAC;AAEN,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AA2JD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,yBAAyB,GAC/B,qBAAqB,CA0DvB"}

package/dist/agents/canonical/resolve.js

@@ -0,0 +1,175 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parseCanonicalAgentMarkdown } from './parse.js';
+function redactedCandidate(tier, role) {
+    return `<${tier}>/agents/${role}.md`;
+}
+/**
+ * Resolve symlinks before comparing roots.
+ *
+ * `path.resolve` normalizes a path but does not follow symlinks, so the same
+ * canonical file was labelled `<loaded>` or `<user>` depending on whether the
+ * caller happened to pass a realpath'd `skillDir`. On macOS a tmpdir root
+ * realpaths from `/var/...` to `/private/var/...`, which broke the string
+ * match; on Linux it did not. A provenance label must not depend on an
+ * incidental property of the caller's argument.
+ */
+function sameRoot(left, right) {
+    const normalize = (value) => {
+        try {
+            return realpathSync(value);
+        }
+        catch {
+            return resolve(value);
+        }
+    };
+    return normalize(left) === normalize(right);
+}
+function canonicalTier(candidate, userCanonicalRoot, projectCanonicalRoot) {
+    if (sameRoot(candidate.canonicalRoot, userCanonicalRoot)) {
+        return 'user';
+    }
+    if (sameRoot(candidate.canonicalRoot, projectCanonicalRoot)) {
+        return 'project';
+    }
+    return candidate.tier;
+}
+function inspectCandidate(candidate, role) {
+    const selectedFile = join(candidate.providerRoot, 'agents', `${role}.md`);
+    const canonicalFile = join(candidate.canonicalRoot, 'agents', `${role}.md`);
+    const miss = (outcome) => ({
+        tier: candidate.tier,
+        candidate: redactedCandidate(candidate.tier, role),
+        outcome,
+    });
+    let selectedStat;
+    try {
+        selectedStat = lstatSync(selectedFile);
+    }
+    catch {
+        return miss('missing');
+    }
+    if (selectedStat.isSymbolicLink()) {
+        let selectedRealpath;
+        try {
+            selectedRealpath = realpathSync(selectedFile);
+        }
+        catch {
+            return miss('broken-symlink');
+        }
+        try {
+            if (!lstatSync(canonicalFile).isFile()) {
+                return miss('escaping-symlink');
+            }
+            if (selectedFile !== canonicalFile &&
+                selectedRealpath === realpathSync(canonicalFile)) {
+                return {
+                    validation: 'exact-canonical-symlink',
+                    selectedFile,
+                    canonicalFile,
+                };
+            }
+        }
+        catch {
+            return miss('escaping-symlink');
+        }
+        return miss('escaping-symlink');
+    }
+    if (!selectedStat.isFile()) {
+        return miss('wrong-target');
+    }
+    if (selectedFile !== canonicalFile) {
+        return miss('noncanonical-copy');
+    }
+    return { validation: 'direct-canonical', selectedFile, canonicalFile };
+}
+function resolveRoleIdentity(resolved, candidate, input, candidateMisses) {
+    try {
+        const content = readFileSync(resolved.canonicalFile, 'utf8');
+        const document = parseCanonicalAgentMarkdown(content, '<canonical-role>');
+        const version = document.frontmatter.version;
+        if (document.name !== input.canonicalRole ||
+            typeof version !== 'string' ||
+            version.trim() === '') {
+            throw new Error('Canonical role identity is invalid');
+        }
+        const canonicalPath = redactedCandidate(canonicalTier(candidate, input.userCanonicalRoot, input.projectCanonicalRoot), input.canonicalRole);
+        return {
+            status: 'resolved',
+            dependency: input.dependency,
+            canonicalRole: input.canonicalRole,
+            tier: candidate.tier,
+            validation: resolved.validation,
+            canonicalPath,
+            selectedPath: redactedCandidate(candidate.tier, input.canonicalRole),
+            roleVersion: version.trim(),
+            contentDigest: `sha256:${createHash('sha256').update(content).digest('hex')}`,
+            candidateMisses,
+        };
+    }
+    catch {
+        return {
+            tier: candidate.tier,
+            candidate: redactedCandidate(candidate.tier, input.canonicalRole),
+            outcome: 'invalid-role',
+        };
+    }
+}
+/**
+ * Deliberately a library for skill-side callers: dispatch protocols resolve
+ * role identity before the native launch and hand the resulting evidence to
+ * `oat project dispatch record`, which validates it. There is intentionally no
+ * production call site inside the CLI.
+ */
+export function resolveCanonicalRole(input) {
+    const loadedRoot = resolve(input.skillDir, '..', '..');
+    const loadedCanonicalRoot = basename(loadedRoot) === '.agents'
+        ? loadedRoot
+        : join(dirname(loadedRoot), '.agents');
+    const candidates = [
+        {
+            tier: 'loaded',
+            providerRoot: loadedRoot,
+            canonicalRoot: loadedCanonicalRoot,
+        },
+        {
+            tier: 'user',
+            providerRoot: input.userCanonicalRoot,
+            canonicalRoot: input.userCanonicalRoot,
+        },
+        {
+            tier: 'project',
+            providerRoot: input.projectCanonicalRoot,
+            canonicalRoot: input.projectCanonicalRoot,
+        },
+    ];
+    const candidateMisses = [];
+    for (const candidate of candidates) {
+        const inspected = inspectCandidate(candidate, input.canonicalRole);
+        if ('outcome' in inspected) {
+            candidateMisses.push(inspected);
+            continue;
+        }
+        const evidence = resolveRoleIdentity(inspected, candidate, input, candidateMisses);
+        if ('outcome' in evidence) {
+            candidateMisses.push(evidence);
+            continue;
+        }
+        return evidence;
+    }
+    return {
+        status: 'missing',
+        dependency: input.dependency,
+        canonicalRole: input.canonicalRole,
+        candidateMisses,
+        recovery: [
+            {
+                command: `oat tools install ${input.dependency} --scope <user|project>`,
+            },
+            {
+                command: `oat tools update --pack ${input.dependency} --scope <user|project>`,
+            },
+        ],
+    };
+}

package/dist/commands/decision/agents-guidance.d.ts

@@ -7,8 +7,8 @@ export interface InitializeDecisionAgentsGuidanceOptions {
     decisionsRoot: string;
 }
 export interface DecisionAgentsGuidanceResult {
-    root: UpsertSectionResult['action'];
-    scoped: UpsertSectionResult['action'];
+    root: UpsertSectionResult;
+    scoped: UpsertSectionResult;
 }
 export declare function initializeScopedDecisionAgentsGuidance(decisionsRoot: string): Promise<UpsertSectionResult>;
 export declare function initializeDecisionAgentsGuidance(options: InitializeDecisionAgentsGuidanceOptions): Promise<DecisionAgentsGuidanceResult>;

package/dist/commands/decision/agents-guidance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-guidance.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/agents-guidance.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AAEpC,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAwBvD,wBAAgB,8BAA8B,CAC5C,aAAa,SAAyB,GACrC,MAAM,CAWR;AAED,wBAAgB,oCAAoC,IAAI,MAAM,CAU7D;AAED,MAAM,WAAW,uCAAuC;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACvC;AAED,wBAAsB,sCAAsC,CAC1D,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAO9B;AAED,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,OAAO,CAAC,4BAA4B,CAAC,CAgBvC"}
+{"version":3,"file":"agents-guidance.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/agents-guidance.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AAEpC,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAwBvD,wBAAgB,8BAA8B,CAC5C,aAAa,SAAyB,GACrC,MAAM,CAWR;AAED,wBAAgB,oCAAoC,IAAI,MAAM,CAU7D;AAED,MAAM,WAAW,uCAAuC;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,wBAAsB,sCAAsC,CAC1D,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAO9B;AAED,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,OAAO,CAAC,4BAA4B,CAAC,CAavC"}

package/dist/commands/decision/agents-guidance.js

@@ -45,8 +45,5 @@ export async function initializeScopedDecisionAgentsGuidance(decisionsRoot) {
 export async function initializeDecisionAgentsGuidance(options) {
     const scoped = await initializeScopedDecisionAgentsGuidance(options.decisionsRoot);
     const root = await upsertAgentsMdSection(options.projectRoot, DECISION_AGENTS_SECTION_KEY, buildDecisionAgentsSectionBody(displayDecisionsPath(options.projectRoot, options.decisionsRoot)));
-    return {
-        root: root.action,
-        scoped: scoped.action,
-    };
+    return { root, scoped };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,gCAAgC,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAyB7D,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,gCAAgC,EAAE,OAAO,gCAAgC,CAAC;IAC1E,yBAAyB,EAAE,OAAO,yBAAyB,CAAC;IAC5D,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AAmED,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAqNT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAO5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,gCAAgC,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAyB7D,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,gCAAgC,EAAE,OAAO,gCAAgC,CAAC;IAC1E,yBAAyB,EAAE,OAAO,yBAAyB,CAAC;IAC5D,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AAmED,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CA6OT"}

package/dist/commands/decision/index.js

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path';
 import { buildCommandContext } from '../../app/command-context.js';
 import { resolvePjmAdoption } from '../pjm/adoption.js';
+import { formatAgentsMdGuidanceResult, formatAgentsMdMutationFailure, } from '../shared/agents-md.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { CliError } from '../../errors/index.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
@@ -80,23 +81,41 @@ export function createDecisionCommand(overrides = {}) {
                 });
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                throw new Error(`Decision index initialized at ${result.decisionsRoot}, but AGENTS.md guidance could not be written: ${message}. Fix the guidance write error and rerun \`oat decision init\`.`, { cause: error });
+                throw new Error(`Decision scaffold completed, but AGENTS.md guidance could not be written: ${formatAgentsMdMutationFailure(error)} Fix the guidance write error and rerun \`oat decision init\`.`, { cause: error });
             }
+            const guidanceIncomplete = [guidance.root, guidance.scoped].some(({ action }) => action === 'manual-required' || action === 'blocked');
             if (context.json) {
-                context.logger.json({ status: 'ok', ...result, guidance });
+                context.logger.json(guidanceIncomplete
+                    ? {
+                        status: 'partial',
+                        scaffold: { status: 'complete' },
+                        created: result.created,
+                        skipped: result.skipped,
+                        guidance,
+                    }
+                    : { status: 'ok', ...result, guidance });
             }
             else {
-                context.logger.info(`Initialized decision scaffold at ${result.decisionsRoot}`);
+                context.logger.info(guidanceIncomplete
+                    ? 'Initialized decision scaffold.'
+                    : `Initialized decision scaffold at ${result.decisionsRoot}`);
                 if (result.created.length > 0) {
                     context.logger.info(`Created: ${result.created.join(', ')}`);
                 }
                 if (result.skipped.length > 0) {
                     context.logger.info(`Skipped existing: ${result.skipped.join(', ')}`);
                 }
-                context.logger.info(`AGENTS.md guidance: root=${guidance.root}, decisions=${guidance.scoped}`);
+                context.logger.info(`AGENTS.md guidance: root=${guidance.root.action}, decisions=${guidance.scoped.action}`);
+                if (guidanceIncomplete) {
+                    context.logger.warn('Decision scaffold completed; AGENTS.md guidance requires manual action.');
+                    for (const guidanceResult of [guidance.root, guidance.scoped]) {
+                        for (const line of formatAgentsMdGuidanceResult(guidanceResult)) {
+                            context.logger.info(line);
+                        }
+                    }
+                }
             }
-            process.exitCode = 0;
+            process.exitCode = guidanceIncomplete ? 1 : 0;
         }
         catch (error) {
             reportError(context, error);

package/dist/commands/docs/init/index.d.ts

@@ -4,13 +4,19 @@ import { type PromptContext, type SelectChoice } from '../../shared/shared.promp
 import { type OatConfig } from '../../../config/oat-config.js';
 import { Command } from 'commander';
 import { type DocsInitResolvedOptions } from './resolve-options.js';
+import { type RootPackagePatchResult } from './root-package.js';
+interface DocsInitExecutionResult {
+    createdFiles: string[];
+    appRoot: string;
+    rootPackagePatch: RootPackagePatchResult;
+}
 interface DocsInitDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
     resolveAssetsRoot: () => Promise<string>;
     detectRepoShape: (repoRoot: string) => Promise<'monorepo' | 'single-package'>;
     inputWithDefault: (message: string, defaultValue: string, ctx: PromptContext) => Promise<string | null>;
     selectWithAbort: <T extends string>(message: string, choices: SelectChoice<T>[], ctx: PromptContext) => Promise<T | null>;
-    runDocsInit: (context: CommandContext, options: DocsInitResolvedOptions, assetsRoot: string) => Promise<void>;
+    runDocsInit: (context: CommandContext, options: DocsInitResolvedOptions, assetsRoot: string) => Promise<DocsInitExecutionResult | void>;
     upsertAgentsMdSection: (repoRoot: string, key: string, body: string) => Promise<UpsertSectionResult>;
     readOatConfig: (repoRoot: string) => Promise<OatConfig>;
     confirmAction: (message: string, ctx: PromptContext) => Promise<boolean>;

package/dist/commands/docs/init/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAmB3B,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAyGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AAoHD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CA6CT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAexB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,sBAAsB,CAAC;CAC1C;AAED,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAqGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AA6JD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CA6CT"}