# Rulecraft development - Follow Laravel conventions, SOLID pragmatically, SLAP, and clear domain naming. - Keep abstractions and dependencies tied to concrete requirements. Use Eloquent directly; do not add generic repositories, managers, or plugin frameworks without a need. - Declare `strict_types=1` at the start of every PHP source/config/migration/route/test/tool file. Keep PHPStan at level 8 and fix underlying type issues without suppressions or baselines. Pint enforces strict declarations. - Add native parameter/return types where compatible. Use PHPDoc for properties and generic collections/arrays to preserve PHP 7.3 support. Keep descriptions concise and omit prose that repeats the method name. - Package source, migrations, tests, configuration, and examples must support PHP 7.3 syntax. Laravel support targets 7 through 13; each framework uses its compatible PHP runtime. - Every package table name comes from `rulecraft.tables`, including migrations, rollback, foreign keys, models, and relationships. - Action registrations from config and providers share an application-scoped registry. Reject duplicate names and resolve handlers through the container only when executing. - `evaluate()` never executes actions. `run()` executes eligible actions only after the group passes. - Groups form a single-parent tree. `all`/`any` combine direct rule and child-group results. Preserve cycle/depth guards, default depth 10, and configurable table/constraint names in the consolidated initial migration. Keep the unreleased initial schema in one migration. - Actions require a passing selected root and a passing ancestor path. Use eligible rule results rather than all matching leaves. Permission assignments must reference roots. - Conditional permissions require the user's actual role-permission grant and that exact grant's passing condition group. Never combine grants and conditions across roles. Keep Spatie guard and team scoping intact. - Groups/rules default to enabled. Disabled nodes count as false rather than being omitted; disabled groups skip validation and their subtree. Disabled ancestors block direct child checks. Preserve disabled result snapshots and prevent actions from disabled paths. - Policy transfer uses strict versioned JSON for a complete root tree. Validate all expressions/schema before writes, reject duplicate group names, and save transactionally without overwriting. Preserve ordering, states, action names, and JSON parameter shapes; never transfer handler code, IDs, config, or permission mappings. Export stdout must contain only raw JSON so clipboard pipes work. - Context validation is optional and configured by exact group name. Invalid context skips that group’s expressions/descendants, records validation errors, and cannot authorize an ANY parent or execute actions. Keep context values unchanged. - Dispatch GroupEvaluated once per completed public group selection, including run() before handler resolution; nested nodes stay in the result. Permission checks dispatch completed grant-group events then one PermissionEvaluated, including valid denials without grants. Include results/context and permission selection metadata; do not emit completion events for aborted evaluations, validation-only calls, transfers, or guest Blade permission shortcuts. Keep audit storage and metrics application-owned. - Builder access is opt-in and uses host web/auth/CSRF plus a configurable Laravel ability. Keep all endpoints protected, assets scoped/versioned, and component instances independent. Compile visual metadata on the server; retain raw expressions and invalidate stale metadata. Preview uses shared in-memory evaluation without policy writes, action resolution, or normal completion events. Save transactionally with original-parent ID scoping and revision checks. Preserve typed literals and raw JSON parameter text through browser transport; version 2 exports retain visual metadata while version 1 remains accepted. - Visual expression providers register once in expression_providers and optionally implement BuilderExpressionProvider. Require declared functions, ordered scalar argument metadata, and matching return types. Compile on the server without invoking evaluator callbacks. Use one builder definition schema (source/operator/operand), without version flags or legacy branches. Field sources include their type and remain editable when the optional catalog is removed; function sources and comparison operands include their declared signature. Validate both sides through the same compiler, require compatible scalar return types, and bind newly selected function arguments to matching context keys. Preserve actual bindings in loaded definitions. Membership still requires a literal list. Keep transfer compilation independent of destination builder metadata, while syntax checks still require registered functions. - Keep visual conditions in three full-width Source/Operator/Compare with rows. Place each operand kind and value together, with read-only typed function signatures directly below their selectors. Do not show function type or argument-mapping inputs. Show Name/Priority/Editor in a visible first Rule details section. Keep editable field types beside Source, known field types as badges, and literal types beside Compare with. Use separate optional Messages, Action, and Generated expression disclosure panels. Place failure/success text inside Messages, collapsed by default, with a Defaults/customized-count summary. Preserve each panel's disclosure state during redraws, supply group-unique default rule names, and show descriptive operator labels with their symbols. - Rule failure/success messages are nullable plain text on each rule. Snapshot the configured outcome message; ordinary false conditions have a rule-name fallback, true conditions have no default, and disabled/error results have no message. Group failedMessage() combines visited ordinary failures; passedMessage() combines configured success text from eligible passing paths only. Helpers default to a space separator and return empty strings when no text contributes. Preserve messages in builder preview/save/load/revisions and both policy formats; never interpolate context or render message HTML. - Core evaluation does not require Spatie. Conditional permission integration uses a small `GrantResolver` contract, with Spatie as the default integration. - Keep PHP lines within 100 characters where practical; wrap argument lists, arrays, and fluent calls without changing values. Prefer a meaningful local variable when wrapping a complex loop expression would hurt readability. - Use progressive disclosure in docs: README owns the implemented feature list and getting started for every core workflow. Keep exhaustive methods/results/errors in docs/api-reference.md, syntax in docs/expressions.md, and all settings/defaults/registrations in docs/configuration.md. Index complete use cases in docs/examples.md with detailed workflows under docs/examples/. Keep common outcomes beside examples and update links when pages move. - Keep public calls concise and Laravel-style. Fluent options must not leak between evaluations. - Run `composer validate --strict`, `composer lint`, and `composer test` after relevant changes. Use the CI matrix for runtime combinations unavailable locally. - Historical dependency security exceptions belong only in isolated compatibility test commands; do not disable auditing globally or in the published package configuration.

Rulecraft development

Follow Laravel conventions, SOLID pragmatically, SLAP, and clear domain naming.
Keep abstractions and dependencies tied to concrete requirements. Use Eloquent directly; do not add generic repositories, managers, or plugin frameworks without a need.
Declare strict_types=1 at the start of every PHP source/config/migration/route/test/tool file. Keep PHPStan at level 8 and fix underlying type issues without suppressions or baselines. Pint enforces strict declarations.
Add native parameter/return types where compatible. Use PHPDoc for properties and generic collections/arrays to preserve PHP 7.3 support. Keep descriptions concise and omit prose that repeats the method name.
Package source, migrations, tests, configuration, and examples must support PHP 7.3 syntax. Laravel support targets 7 through 13; each framework uses its compatible PHP runtime.
Every package table name comes from rulecraft.tables, including migrations, rollback, foreign keys, models, and relationships.
Action registrations from config and providers share an application-scoped registry. Reject duplicate names and resolve handlers through the container only when executing.
evaluate() never executes actions. run() executes eligible actions only after the group passes.
Groups form a single-parent tree. all/any combine direct rule and child-group results. Preserve cycle/depth guards, default depth 10, and configurable table/constraint names in the consolidated initial migration. Keep the unreleased initial schema in one migration.
Actions require a passing selected root and a passing ancestor path. Use eligible rule results rather than all matching leaves. Permission assignments must reference roots.
Conditional permissions require the user's actual role-permission grant and that exact grant's passing condition group. Never combine grants and conditions across roles. Keep Spatie guard and team scoping intact.
Groups/rules default to enabled. Disabled nodes count as false rather than being omitted; disabled groups skip validation and their subtree. Disabled ancestors block direct child checks. Preserve disabled result snapshots and prevent actions from disabled paths.
Policy transfer uses strict versioned JSON for a complete root tree. Validate all expressions/schema before writes, reject duplicate group names, and save transactionally without overwriting. Preserve ordering, states, action names, and JSON parameter shapes; never transfer handler code, IDs, config, or permission mappings. Export stdout must contain only raw JSON so clipboard pipes work.
Context validation is optional and configured by exact group name. Invalid context skips that group’s expressions/descendants, records validation errors, and cannot authorize an ANY parent or execute actions. Keep context values unchanged.
Dispatch GroupEvaluated once per completed public group selection, including run() before handler resolution; nested nodes stay in the result. Permission checks dispatch completed grant-group events then one PermissionEvaluated, including valid denials without grants. Include results/context and permission selection metadata; do not emit completion events for aborted evaluations, validation-only calls, transfers, or guest Blade permission shortcuts. Keep audit storage and metrics application-owned.
Builder access is opt-in and uses host web/auth/CSRF plus a configurable Laravel ability. Keep all endpoints protected, assets scoped/versioned, and component instances independent. Compile visual metadata on the server; retain raw expressions and invalidate stale metadata. Preview uses shared in-memory evaluation without policy writes, action resolution, or normal completion events. Save transactionally with original-parent ID scoping and revision checks. Preserve typed literals and raw JSON parameter text through browser transport; version 2 exports retain visual metadata while version 1 remains accepted.
Visual expression providers register once in expression_providers and optionally implement BuilderExpressionProvider. Require declared functions, ordered scalar argument metadata, and matching return types. Compile on the server without invoking evaluator callbacks. Use one builder definition schema (source/operator/operand), without version flags or legacy branches. Field sources include their type and remain editable when the optional catalog is removed; function sources and comparison operands include their declared signature. Validate both sides through the same compiler, require compatible scalar return types, and bind newly selected function arguments to matching context keys. Preserve actual bindings in loaded definitions. Membership still requires a literal list. Keep transfer compilation independent of destination builder metadata, while syntax checks still require registered functions.
Keep visual conditions in three full-width Source/Operator/Compare with rows. Place each operand kind and value together, with read-only typed function signatures directly below their selectors. Do not show function type or argument-mapping inputs. Show Name/Priority/Editor in a visible first Rule details section. Keep editable field types beside Source, known field types as badges, and literal types beside Compare with. Use separate optional Messages, Action, and Generated expression disclosure panels. Place failure/success text inside Messages, collapsed by default, with a Defaults/customized-count summary. Preserve each panel's disclosure state during redraws, supply group-unique default rule names, and show descriptive operator labels with their symbols.
Rule failure/success messages are nullable plain text on each rule. Snapshot the configured outcome message; ordinary false conditions have a rule-name fallback, true conditions have no default, and disabled/error results have no message. Group failedMessage() combines visited ordinary failures; passedMessage() combines configured success text from eligible passing paths only. Helpers default to a space separator and return empty strings when no text contributes. Preserve messages in builder preview/save/load/revisions and both policy formats; never interpolate context or render message HTML.
Core evaluation does not require Spatie. Conditional permission integration uses a small GrantResolver contract, with Spatie as the default integration.
Keep PHP lines within 100 characters where practical; wrap argument lists, arrays, and fluent calls without changing values. Prefer a meaningful local variable when wrapping a complex loop expression would hurt readability.
Use progressive disclosure in docs: README owns the implemented feature list and getting started for every core workflow. Keep exhaustive methods/results/errors in docs/api-reference.md, syntax in docs/expressions.md, and all settings/defaults/registrations in docs/configuration.md. Index complete use cases in docs/examples.md with detailed workflows under docs/examples/. Keep common outcomes beside examples and update links when pages move.
Keep public calls concise and Laravel-style. Fluent options must not leak between evaluations.
Run composer validate --strict, composer lint, and composer test after relevant changes. Use the CI matrix for runtime combinations unavailable locally.
Historical dependency security exceptions belong only in isolated compatibility test commands; do not disable auditing globally or in the published package configuration.