Skip to content

docs(builtins): correct enable semantics — builtins default to disabled#111

Open
punk-dev-robot wants to merge 1 commit into
eqtylab:mainfrom
punk-dev-robot:docs/builtins-explicit-enable
Open

docs(builtins): correct enable semantics — builtins default to disabled#111
punk-dev-robot wants to merge 1 commit into
eqtylab:mainfrom
punk-dev-robot:docs/builtins-explicit-enable

Conversation

@punk-dev-robot
Copy link
Copy Markdown

Problem

Several docs and the rulebook template state that builtins are enabled by
default when configured
, and the enabled struct field is documented as
"defaults to true". The code is the opposite:

fn default_enabled() -> bool {
    false // Builtins must be explicitly enabled with `enabled: true`
}

BuiltinsConfig::enabled_builtins() only lists a builtin when enabled == true,
so a configured-but-unenabled block (e.g. rulebook_security_guardrails: with a
message and protected_paths but no enabled: true) is silently inert. The
docs lead users to believe the builtin is active when it is not — a dangerous
gap for a security tool.

Fix

Align the docs with the deliberate, security-motivated explicit-enable
default (default stays false; no behavior change):

  • cupcake-core/src/engine/builtins.rs — 10 struct field doc comments said
    "defaults to true" → "defaults to false; must be set explicitly"
  • fixtures/init/base-config.yml — template header + inline # enabled: true
    notes
  • docs/docs/reference/builtin-config.md — header, inline examples, and the
    "Enabling/Disabling Builtins" prose + example (added enabled: true)
  • docs/docs/tutorials/{claude-code,cursor,opencode}.md — builtin bullet

Verification

cargo test -p cupcake-core --test global_builtins_config_test passes, including
test_global_builtins_default_values, which asserts a builtin without an explicit
enabled: true is not in the enabled set — confirming the documented behavior.

Multiple docs and the rulebook template claimed builtins are 'enabled by
default when configured' / the enabled field 'defaults to true'. The code is
the opposite: default_enabled() returns false and BuiltinsConfig::enabled_builtins()
only lists a builtin when enabled == true, so a configured-but-unenabled block
is silently inert. This mismatch makes users believe a builtin is active when
it is not.

Align the docs with the (deliberate, security-motivated) explicit-enable
default:
- builtins.rs: struct field doc comments (x10) said 'defaults to true'
- fixtures/init/base-config.yml: template header + inline notes
- docs/reference/builtin-config.md: header, inline examples, prose + example
- docs/tutorials/{claude-code,cursor,opencode}.md: builtin bullet

No behavior change; default stays false.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant