Recommendations

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Recommendations are workspace-scoped improvement suggestions produced by automated analyzers or submitted manually by operators. Each recommendation tracks a specific finding, links to supporting evidence, and follows a governed lifecycle from discovery through resolution.

How Recommendations Work

The recommendation substrate combines automated signal analysis with human review. Automated analyzers (such as the meta optimizer) scan workspace execution data for patterns that indicate reliability, performance, or configuration issues. When a pattern exceeds a configured threshold, the analyzer creates a recommendation with evidence references linking back to the source signals.

Operators review recommendations in the portal, accept or dismiss them, and mark resolved findings as converted or superseded.

Sandbox Compatibility Recommendations

The workload builder’s Find compatible sandboxes action performs a read-only comparison between the drafted workload_profile and up to the first 1,000 visible workspace or built-in sandbox_profile assets, ordered lexicographically by slug. When more than 1,000 profiles are visible, the ranking is partial: the API returns truncated: true and the Portal displays a warning that additional candidates were not compared. The action does not modify a sandbox, select a candidate, or bypass release readiness.

The result classifies each candidate as compatible, near fit, blocked, or a built-in baseline. Candidate details separate two kinds of findings:

• Required changes are blocking mismatches. Each item names the constrained field and shows the candidate’s current value and the value required by the workload.
• Review before use items are advisory evidence gaps. Tool use without tool-call evidence, retrieval without retrieval evidence, and any active sandbox capability with no meaningful trace should be reviewed before selection or derivation. These advisories do not by themselves make a candidate incompatible.

Before scoring, the control plane validates each stored candidate against the current sandbox schema, business rules, and cross-field invariants. Corrupt or obsolete stored content fails closed as blocked, ranks behind valid candidates, and cannot be selected or used as a derivation parent.

Selecting Derive a workspace copy opens a guided least-privilege plan. The Portal prepopulates the complete set of required changes from that candidate’s typed required_changes; operators do not author schema paths or invent replacement values. Exact evidence improvements from review_gaps can be included after review, but remain optional.

A compatible candidate and a built-in baseline with no required changes can be selected directly. A baseline with required changes, a near_fit candidate, or a blocked candidate must complete guided derivation and return as compatible. Changing workload posture invalidates any in-flight score, displayed candidates, and prior selection.

Compatibility compares data sensitivity, retrieval boundary, required capabilities, tool allowance/families/side effects, egress posture and host allowlist, and evidence trace strength. A workload’s code_execution category requires the corresponding sandbox capability; other category values do not add a sandbox constraint.

Every runtime-authority over-grant is returned as a typed required tightening. For example, surplus egress hosts are replaced by the workload’s exact allowlist, and an unrestricted external-network baseline is tightened to the declared posture and hosts. A near-fit candidate therefore includes the complete typed plan needed to become compatible.

allowlisted_external requires at least one host. Other egress postures cannot retain an allowlist, and malformed stored profiles fail closed instead of being reported as compatible. Persisted workload validation errors expose only the failed field path and schema constraint, never the rejected stored value. Host tokens cannot contain whitespace.

Tool-family values are canonical identifiers. The bounded family for the first-party HTTP Request tool is http_request; a display label such as HTTP Request is not an equivalent derivation value. A guided tool plan keeps the capability flag, tool allowance, exact workload-declared family set, and side-effect ceiling internally consistent. Tool-enabled workload and sandbox profiles must declare a non-empty, unique family set and an explicit side-effect ceiling; the workload form blocks submission until those values are complete, and missing or empty runtime family bounds admit no tools. Runtime admission also rejects any plugin whose side-effect class exceeds the resolved sandbox ceiling.

Trace strength follows this ordered lattice:

none < basic < detailed < full_replay

A candidate with less trace than the workload requires is blocked. Equal or stronger trace satisfies the requirement, and stronger evidence is not treated as an authority over-grant.

Audience, autonomy level, memory scope, and evidence retention are not compared because the current sandbox contract has no matching enforcement rule for them. They remain governed workload declarations and may still matter to policy and release review.

API clients can request the same read-only result with POST /v1/recommendations/sandbox. Each candidate includes the existing classification, match, gap, and blocker fields plus structured required_changes and review_gaps arrays.

Derivation requires the same workload_profile_version_id used for scoring. Each repeated --change or SDK change entry must be an exact typed field/value pair returned for the selected parent by sandbox recommendation. The server rejects arbitrary fields, duplicate fields, unrelated capability expansion, altered values, incomplete plans, and invalid cross-field combinations. The caller must hold asset.create, asset.view, and recommendation.read in the active workspace. A rationale required for loosened constraints is recorded in append-only audit metadata and is limited to 2,000 characters by the API and Portal input; SDK and CLI calls receive the same server-side rejection.

Before writing, the server reloads the bound workload profile, recalculates the candidate and applies the submitted plan in memory. A result that remains blocked is rejected. A successful derived profile is normalized to lifecycle_posture: workspace_scoped even when its parent is a built-in, retains immutable derived_from and constraint_diff provenance, and is persisted with its audit record atomically. The Portal selects the returned version only after that operation succeeds, so failed validation or re-scoring does not leave a partial derived profile or replace the current selection. The Portal locks workload posture and derivation request inputs while that mutation is pending. In the workload builder, step navigation and Register workload (the terminal action, shown only on the Review step) are also disabled, and submission remains guarded against programmatic activation. The Portal surfaces and selects every successful response for the active authoring context before workload creation can use that derived version. If the active workspace or workload identity changes, the Portal clears the departed context and ignores its stale response for selection. When that response cannot be confirmed, its submitted slug remains blocked for the lifetime of the current draft; workspace inspection is diagnostic, and continuing requires a new slug.

Workload and parent version IDs are resolved through the repository’s tenant visibility predicate, so a foreign workspace version is excluded by the query itself. Only an explicitly marked global built-in is visible outside its owning workspace.

The SDK and CLI expose the same bound operation. First retrieve the exact changes, then submit those values unchanged:

orqestractl recommendations sandbox recommend \
  --workload-profile-version-id "$WORKLOAD_PROFILE_VERSION_ID"
 
orqestractl recommendations sandbox derive \
  --workload-profile-version-id "$WORKLOAD_PROFILE_VERSION_ID" \
  --parent-version-id "$SANDBOX_PROFILE_VERSION_ID" \
  --derived-slug my-workload-sandbox \
  --change 'capabilities.tool_use=true' \
  --change 'tool_posture.allowed=true' \
  --change 'tool_posture.families=["http_request"]' \
  --change 'tool_posture.max_side_effect_class=read_write' \
  --acknowledge-loosened \
  --rationale "Required for the declared HTTP Request workflow"

The example changes are illustrative. Submit only the complete field/value set returned for your workload and parent; do not reuse a plan from another score.

Sandbox compatibility results are request-scoped and are not persisted as recommendation records. The lifecycle below applies to persisted improvement recommendations.

Recommendation Lifecycle

Every recommendation starts in open status and follows a governed state machine:

• open — newly created, awaiting review
• accepted — operator has acknowledged the finding
• dismissed — operator has reviewed and decided not to act
• converted — operator has marked the recommendation for follow-up action
• superseded — a newer recommendation replaced this one

Dismissed recommendations can be reopened (returned to open). All other terminal states are final.

Assistant Drafts and Self-Improvement

The personal assistant and the self-improvement skill can author recommendations, but only as drafts for human review. A draft carries provenance metadata that the portal, SDK, and CLI all surface:

• provenance_kind — assistant_draft, self_improvement_skill, or optimizer
• required_human_role — the role expected to review before a human applies it
• self_improvement_skill_ref — the skill asset that authored a self-improvement draft
• draft_only — always true for assistant- and self-improvement-authored items

The control plane fails closed on this contract: a 422 is returned if an assistant- or self-improvement-authored recommendation is created without draft_only set true (omitted or disabled), or if a self_improvement_skill draft omits its skill reference.

What converting a draft does — and does not — do

Converting a draft that proposes asset content lands that content as a draft asset version through the normal asset-version path, for a human to review and promote through the governed release lifecycle. It never reaches operational governance state. Specifically, converting an assistant draft cannot:

• activate a release
• change an active policy decision
• alter a secret or live connection
• expand permissions or grant tool access
• curate memory without review

Even when a draft carries concrete content for a sensitive governed kind — a policy bundle, a connection, a memory binding, or a tool — converting it only creates a draft-lifecycle asset version; the active policy, connection, permission-grant, and memory tables are never written. These guarantees are pinned by the trust-boundary probes ORQ-C-ASSISTANT-DRAFT-CONVERSION-001 and ORQ-C-ASSISTANT-DRAFT-GOVERNED-BOUNDARY-001, so a regression that let a draft mutate production would fail the pen-test suite.

Bounded Skill Patches (SkillOpt)

A self-improvement optimizer can propose a bounded skill patch: a small set of typed add / delete / replace operations against a governed skill asset’s text, rather than a free-form rewrite. Each patch carries an edit budget, the operations’ target paths, protected-section and forbidden-mutation checks, train-evidence references, and a reference to a governed held-out evaluation suite. A patch can never expand permissions, change secrets, activate a release, or bypass policy — those operation paths are rejected as forbidden mutation classes.

Held-out validation gate

The optimizer submits a candidate patch with a reference to a governed held-out evaluation_suite to POST /v1/recommendations/skill-patch/emit. The control plane runs a held-out validation gate: it system-executes the target skill’s current head content and the server-applied candidate over the suite — the platform produces both scores, so it never trusts a caller-supplied score or output — requires the split to be genuinely held out (no leakage from the train evidence) and the candidate to strictly improve the system-executed validation score, and enforces the bounded-patch contract. A patch whose before_hash no longer matches the current head fails the gate closed.

• Pass → an open, draft-only skill_patch recommendation is created through the standard recommendation path, with the optimizer input and held-out validation evidence linked, for human review.
• Fail → the attempt is persisted as an evidence-backed rejected edit (negative feedback tied to the optimizer run and target skill), and no convertible recommendation is created.

A skill-patch recommendation can only be produced by this gate; the generic recommendation-create endpoint rejects skill-patch-shaped payloads, so a passed gate cannot be forged.

Reviewing and converting

The recommendation detail page shows the target skill and version, the gate result and score delta, the edit budget, each bounded operation, the evidence references, and any protected-section or forbidden-mutation findings. A reviewer with the recommendation-convert and asset-edit permissions can convert a gate-passed recommendation. Conversion applies the bounded operations to the target skill server-side — rebasing onto the skill’s latest version and verifying each operation’s before_hash, so a patch proposed against content that has since changed is rejected as stale — and lands the result as a draft skill version through the normal asset-version path. It never activates production: promotion still runs through the governed release, approval, and evaluation lifecycle.

These guarantees are pinned by the trust-boundary probes ORQ-A-SKILL-PATCH-CONTRACT-AUTHZ-001 (contract authz + fail-closed bounds), ORQ-C-SKILL-PATCH-EMIT-GATE-001 (gated emission: no evidence-free pass, no forbidden mutation, workspace isolation), ORQ-B-SKILL-PATCH-EMIT-EVIDENCE-001 (adversarial optimizer evidence cannot pass the gate), and ORQ-C-SKILL-PATCH-CONVERT-001 (conversion is gate-bound, integrity-checked, and lands only a draft version).

Viewing Recommendations

Open a workload and choose its Recommendations tab to see that workload’s recommendations, or open Recommendations from the command palette (under Monitor) to see all recommendations for the active workspace, including release recommendations, which appear only there. The full list supports filtering by status and source, and searching by title.

Click any recommendation to see its full detail including rationale, proposed action, evidence references, and available state transitions.

Running the Meta Optimizer

The meta optimizer is a read-only analyzer that scans workspace execution history for reliability signals. It does not modify any active assets, releases, policies, or secrets.

To trigger an analysis run:

1. Navigate to the recommendation list page
2. The optimizer examines execution outcomes within a configurable lookback window (default 14 days)
3. When the failure count for any workload exceeds the threshold, it creates a reliability recommendation with evidence

The optimizer can also be triggered via the REST API:

curl -X POST "https://your-instance/v1/recommendations/optimizer-runs?workspace_id=YOUR_WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lookback_days": 14}'

Running the Temporal Obligation Monitor

The temporal obligation monitor is an offline, advisory analyzer for sequence-based governance risks — failures that are visible over time rather than at a single point. It evaluates three bounded v1 patterns over the workspace’s existing records:

1. Repeated unresolved exception — the same policy-exception subject is excepted repeatedly, or an approved exception remains unresolved past its expiry.
2. Release/readiness missing evidence — a release asserts readiness (approved/active) without recorded approval evidence.
3. Repeated obligation failure — a workload repeatedly fails a policy obligation (for example, evidence capture or human review) across executions.

Each detected pattern is written as an advisory recommendation that appears in the same recommendation queue and detail views as every other recommendation, for a human to review, accept, dismiss, or supersede.

The monitor is advisory-only by design: it never blocks or mutates a release, execution, policy, exception, or evidence record, and it introduces no runtime or release-activation gate. Its only effect is the advisory recommendation rows it writes, and its run is recorded in the governance audit log. This boundary is pinned by the ORQ-C-TEMPORAL-OBLIGATION-MONITOR-TENANT-ISOLATION pen-test probe, which proves the run is workspace-scoped and writes nothing but recommendations.

Trigger a run via the REST API (the window defaults to 30 days):

curl -X POST "https://your-instance/v1/recommendations/temporal-obligation-runs?workspace_id=YOUR_WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"window_days": 30}'

Permissions

Recommendation access is controlled by three workspace-scoped permissions:

REST API