Open Source · Troubleshooting

Diagnose the boundary before changing policy.

READY_POLICY_ONLY

Interception/policy works but trusted postcondition semantics are missing for at least one protected action. Review the affected operation/resource and Effect Profile; do not map a generic tool name to strong semantics merely to make the status green.

ATTENTION

ruleoak protect status
ruleoak effect pending
ruleoak record verify

Resolve configuration, stale state, evidence or unresolved effects before treating the boundary as ready.

Unresolved effect

ruleoak effect show --id <effect-id>
ruleoak effect reconcile --limit 20
ruleoak effect retry-plan --id <effect-id>

Reconciliation never replays the original action. If ambiguity remains, inspect the external system manually or improve the observation/Profile.

MCP traffic bypasses RuleOak

Confirm the client actually launches/connects through RuleOak rather than a separate direct server registration.

Source manifest fails after copying files

Hidden directories such as .github/ and .ruleoak/ are part of the source tree. Use a clean extraction/clone and avoid copy workflows that omit dotfiles.

Aggregate qualification times out

Run focused constituent gates to locate the boundary. Preserve completed PASS evidence separately and do not convert a timeout into PASS.