Refusal codes¶
Every reason code the pre-tool hook can refuse with, generated
from cli/compass_pkg/refusals.py by compass _refusal --list. Do not
hand-edit the list below - regenerate it after any change to the registry,
and tests/test_refusal_registry.py fails the build if it goes stale.
A refusal always has three lines - Blocked:, Why:, Fix: - and ends
with its code in brackets, e.g. [no-red-on-record]. Search this page for a
code from a refusal you hit.
bad-current-task¶
Blocked: this edit Why: '.compass/current-task' names '{slug}', which is not one path segment - a slug names a directory directly under .compass/work/. Fix: fix .compass/current-task to name a real issue slug, then retry.
bad-session-issue¶
Blocked: this edit Why: COMPASS_ISSUE names '{slug}', which is not an issue directly under .compass/work/. It names this session's issue ahead of .compass/current-task, so the edit is not judged by another issue instead. Fix: set COMPASS_ISSUE to a real issue slug, or unset it to use .compass/current-task, then retry.
config-invalid¶
Blocked: edit to {target} (tool: {tool}) Why: '.compass/config.yml' could not be read: {detail} Fix: fix .compass/config.yml and retry.
no-acceptance-criteria¶
Blocked: edit to {target} (tool: {tool}) Why: the acceptance-before-code guardrail blocks this: define: full is set but manifest.yml has no scenarios. Fix: add the scenarios to acceptance-criteria.md and manifest.yml (compass scenario add), or run /compass:assess --reassess if this is exploratory.
no-delivery-approach¶
Blocked: this edit Why: issue '{slug}' has no delivery-approach.md - its assessment did not finish. Fix: run /compass:assess.
no-red-on-record¶
Blocked: edit to {target} (tool: {tool}, guarded by {guard})
Why: no failing test is on record for issue '{slug}' - the red-before-green strategy applies here.
Fix: run compass tdd-red --scenario
not-initialised¶
Blocked: this edit Why: no issue has been assessed yet - {detail}. Fix: run /compass:assess before changing code, or /compass:quick-fix for a small, low-risk change.
pointer-moved¶
Blocked: this edit
Why: another session moved .compass/current-task from this session's issue '{previous}' to '{slug}', so this edit would count against the wrong issue.
Fix: in this session, run compass issue use {previous} to carry on, or compass issue use {slug} to switch, then retry.
python-missing¶
Blocked: edit to {target} (tool: {tool}) Why: python3 was not found on the PATH, so Compass cannot check whether this edit is allowed. Fix: install python3 (3.10+) or put it on PATH, then retry.
reader-failed¶
Blocked: edit to {target} (tool: {tool}) Why: the {reader} could not run. {cause}{detail} Fix: fix the install and retry - this is not about your edit.
red-marker-no-record¶
Blocked: this edit
Why: the .red marker for issue '{slug}' has no matching record in evidence/ - the marker alone is not evidence.
Fix: run compass tdd-red --scenario
red-unsigned¶
Blocked: this edit
Why: the red record for issue '{slug}' carries no identity - no content_digest - and this project needs one for records written since records_signed_since: {since_date}.
Fix: run compass tdd-red --scenario